MDK dashboard

` | `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:

.: : ` | No file resolves at that path relative to the package root | | `ERR_PLUGIN_DUPLICATE_NAME:

.` | Rename or remove the duplicate entry in that section | **Device instantiation**: `runtime.start()` runs this per configured device (see [`worker-runtime-v2.js`](https://github.com/tetherto/mdk/blob/main/backend/core/mdk-worker/lib/worker-runtime-v2.js)), and [`createInstance`](https://github.com/tetherto/mdk/blob/main/backend/core/mdk-worker/index.js) (Step 7) runs the identical check for one device at a time in tests: | Error | Diagnostic and remediation | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `ERR_INSTANCE_HANDLER_NOT_FOUND: :

.: ` | The path that resolved fine at contract-load time no longer resolves inside this device's module context; check for a typo | | `ERR_INSTANCE_HANDLER_LOAD_FAILED: :

.: ` | The handler file exists but throws while loading; the nested error names the real failure (a missing import, a syntax error) | | `ERR_INSTANCE_HANDLER_NOT_FUNCTION: :

.` | The module must assign a function to `module.exports` | For errors from a live Kernel registration or requests once your Worker is actually hosted, 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) - See the end-user experience of controlling and monitoring your device via the Worker in [Test a Worker's next steps](/guides/workers/test-a-worker) # Test a new Worker (/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 package on `WorkerRuntimeV2` in a Node.js host process by pointing it at the Worker plugin package's directory (see [Build a third-party Worker](/guides/workers/build-a-worker)). 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: WorkerRuntimeV2, 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) - npm 11 [(< 12)](/reference/environment) - 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 `WorkerRuntimeV2`) 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). The monorepo is a real root npm workspace, but npm does not auto-install a git dependency's own transitive workspace tree — so run a single install inside the checked-out copy once after adding it: ```bash (cd node_modules/@tetherto/mdk && npm install) ``` 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 path = require("path"); const { WorkerRuntimeV2 } = require("@tetherto/mdk/backend/core/mdk-worker"); const WORKER_DIR = path.resolve(__dirname, "../your-worker-repo"); async function startVendorWorker({ workerId, kernelTopic, seedDevices }) { const runtime = new WorkerRuntimeV2(WORKER_DIR, { 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 }; ``` `WorkerRuntimeV2`'s first argument is the Worker plugin package's own directory, the same one that holds its `mdk-contract.json` (see [Build a third-party Worker](/guides/workers/build-a-worker)); there is no plugin module to `require()`. Required options are `workerId` and a non-empty `devices` array. Each device's `config` object here becomes the ambient `opts` its handlers read from `@tetherto/mdk-worker/device`. `kernelTopic` is needed only for DHT discovery. Without a `store`, `WorkerRuntimeV2` 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. `WorkerRuntimeV2` 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 a frozen `{ deviceId, config, services }` for a device that is currently `online`, or `null` otherwise. There is no `device` key: a directory-loaded plugin has no per-device client object for the host to reach into, since handler modules bind to their device privately through the ambient context (see Step 4 of Build a third-party Worker). A host process that needs to act on a live device drives it the same way a Gateway request would, through `runtime.handleRequest(...)`, rather than through `getDeviceContext(...).device`. ### Register directly with a live Kernel When Kernel and the Worker host share a process, register the runtime's public key directly. The following host script (save it next to your worker as e.g. `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({ kernelKey: 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 local-directory discovery on one machine When the Worker host and Kernel are separate processes on the same machine, neither `registerWorker()` nor a DHT topic is needed: the Worker publishes its RPC key to a shared directory and Kernel picks it up from there. Both sides default that directory to `/.worker-keys`, so passing the same `root` is the whole configuration. ```js "use strict"; const os = require("os"); const path = require("path"); const { getKernel, waitForDiscovery, shutdown, } = require("@tetherto/mdk/backend/core/mdk"); const { keysDir, publishWorkerKey, } = require("@tetherto/mdk/backend/core/mdk/lib/local-discovery"); const { startVendorWorker } = require("./index"); const ROOT = path.join(os.tmpdir(), `vendor-worker-local-${process.pid}`); async function main() { let worker; let kernel; try { worker = await startVendorWorker({ workerId: "vendor-demo", seedDevices: [ { id: "vendor-0", opts: { host: "127.0.0.1", port: 9001 } }, ], }); publishWorkerKey( keysDir(ROOT), "vendor-demo", worker.runtime.getPublicKey().toString("hex"), ); kernel = await getKernel({ root: ROOT, discovery: { mode: "local" } }); const workers = await waitForDiscovery(kernel, { minWorkers: 1, timeoutMs: 30000, }); 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; }); ``` The two halves are shown in one script here so it runs as a single check, but the mode exists for the split case: publish from the Worker process, then read from the Kernel process. Order does not matter. Kernel rescans the directory every four seconds on top of watching it, so a Worker that publishes before Kernel starts is found on the first scan, and one whose RPC server is not yet listening is retried on a later one. Pass a `storeDir` to `WorkerRuntimeV2` if you restart Workers. The published key is only stable across restarts when the runtime has a store to persist its seeds in (see Step 2); without one, every restart looks like a new peer to Kernel and stale `.key` files accumulate. Every process must resolve the same filesystem path, so this mode only covers one machine. Workers on separate hosts need DHT discovery, in the next step. ### 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](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/architecture.md#discovery-model) for how the three modes compare. ## Troubleshooting ### Runtime construction `new WorkerRuntimeV2(dir, opts)` runs two phases synchronously: it loads and validates the Worker plugin package at `dir` first (see [Troubleshooting](/guides/workers/build-a-worker) in Build a third-party Worker for `ERR_WORKER_DIR_REQUIRED` and the contract/handler errors), then validates `opts`: | 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 store services](https://github.com/tetherto/mdk/blob/main/backend/core/mdk-worker/README.md#store-services)) 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 | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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` | Every device reports `online` as soon as `runtime.start()` returns; a directory-loaded plugin has no boot-time probe, so an unreachable device is never a startup symptom (see [Step 5](/guides/workers/build-a-worker) of Build a third-party Worker). If a device is unreachable, look for it at request time instead, in the table below. ### Request time | Error | Diagnostic and remediation | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 omitted its target device ID | | `ERR_DEVICE_ID_REQUIRED` | A 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 | An unreachable device does not surface as `ERR_DEVICE_UNAVAILABLE` for a directory-loaded plugin: with no `connect()` probe and no offline state, the failure comes back from inside the handler's own response instead, isolated to the telemetry channel that touched the network (`{ error: '...' }` under that channel's key in `metrics`, or `status: 'FAILED'` for a command); see the [directory-loaded plugin model](/guides/workers/build-a-worker) in Build a third-party Worker. ## Next steps - Understand the [security boundaries](https://github.com/tetherto/mdk/blob/main/backend/core/gateway/README.md#security-model) Understand the end-user experience of controlling and monitoring your device via the Worker: - Build a [minimal dashboard](/tutorials/build-a-dashboard) around one Worker - Run the [Starter site example](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/README.md) with a supervised, multi-Worker fleet - Connect [the operator agent](/guides/agent) to query and command your Workers over MCP # 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. ## Browse by stack area ### App toolkit - **UI Devkit**: [components](/reference/ui/components/), [hooks](/reference/ui/hooks/), [types](/reference/ui/types/), and [utilities](/reference/ui/utilities/) for the React UI Devkit ### 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 ### Workers - **[Workers](/reference/worker/)**: device protocol adapters that wrap vendor hardware APIs and expose them through the MDK Protocol ## Next steps - [Architecture](/concepts/architecture) for narrative explanations - [Try the demo](/tutorials/run-a-site) for step-by-step instructions # Environment requirements (/reference/environment) ## Overview Every guide and tutorial in this repo assumes the same baseline; this page explains the npm ceiling. ## Requirements - [Node.js](https://nodejs.org/) >=24 (LTS) - npm 11 (< 12) - Git (latest stable version) Check the installed npm version with `npm --version`. ## Why npm stays below 12 npm 12 disables fetching git-based dependencies by default and fails with `EALLOWGIT`: ```text npm error code EALLOWGIT npm error Fetching packages of type "git" have been disabled ``` `examples/full-site` and `examples/mvp-site` depend on the Whatsminer Worker directly from its git repository, so `npm install` on npm 12 fails on that dependency before it reaches anything else. If `npm --version` already reports 12 or higher, repin with: ```bash npm install -g npm@11 ``` # 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 pulls telemetry on its own cadence — it performs no aggregation itself | [`backend/core/kernel/`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md) | | **Gateway** | The developer-owned HTTP entry point between non-Node clients (UI) and Kernel. Required for browser and HTTP consumers; AI agents reach Kernel through the standalone MCP server instead. Not used in the in-process Antminer-rack example below | [`backend/core/gateway/`](https://github.com/tetherto/mdk/blob/main/backend/core/gateway/README.md) | | **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/`](/reference/worker) | | **Worker Plugin** | The executable device integration: [`mdk-contract.json`](https://github.com/tetherto/mdk/blob/main/backend/core/mdk-worker/mdk-contract.schema.json) plus its handler files, loaded from a package directory by `WorkerRuntimeV2` | [`backend/workers/miners/antminer/plugin/index.js`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/plugin/index.js) | | **Worker contract** | The declarative [`mdk-contract.json`](https://github.com/tetherto/mdk/blob/main/backend/core/mdk-worker/mdk-contract.schema.json) alone, as read, validated, published, rendered, or queried | [`backend/workers/miners/antminer/plugin/mdk-contract.json`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/plugin/mdk-contract.json) | | **Driver class** | The JavaScript class a Worker exports, one per device family (for example `Antminer`, `Whatsminer`), not one per model. Drives every device that Worker registers. | [`backend/workers/miners/antminer/lib/antminer.js`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/lib/antminer.js) | | **Thing** | One registered device instance. Created by sending a `registerThing` command to the Worker's provisioning service, not by calling a driver-class method directly. Identified by a generated `deviceId`. | [`backend/core/mdk/lib/services/provisioning.service.js`](https://github.com/tetherto/mdk/blob/main/backend/core/mdk/lib/services/provisioning.service.js) | | **MCP** (Model Context Protocol) | The protocol AI agents use to discover and call tools. `@tetherto/mdk-mcp` runs as its own standalone process, deriving tools from a plugin's routes; the Gateway hosts no MCP itself | [`backend/core/mcp/`](https://github.com/tetherto/mdk/blob/main/backend/core/mcp/README.md) | ### 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). [Scalability](/concepts/scalability) covers the multi-Worker view, parallel Workers, and multi-site deployments. ## 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({ kernelKey: 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 a mining site end to end](/tutorials/run-a-site) - Learn more about: - Multi-process discovery across machines: [Worker discovery](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/architecture.md#discovery-model) - Gateway implementation details, including HTTP routing and plugin registration: [`backend/core/gateway/README.md`](https://github.com/tetherto/mdk/blob/main/backend/core/gateway/README.md) - Building your own Worker for a new device family: [the build walkthrough](/guides/workers/build-a-worker) - The install and run pattern every shipped Worker package follows: [`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/plugin/mdk-contract.json`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/plugin/mdk-contract.json) # Kernel reference (/reference/kernel) `@tetherto/mdk-kernel` is the orchestration kernel of the MDK stack. This subsection holds the canonical specs for its internal modules. For the architectural narrative explaining how the Kernel fits into the rest of the stack, see [Architecture](/concepts/architecture). ## 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) ## Overview [Kernel](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/index.js)'s coordination splits across single-purpose modules. Each owns its own state, persistence boundary, and scaling characteristics. It communicates with the others only through its declared interface. The [Kernel's Architecture overview](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#architecture) provides the canonical spec for each module's interfaces, state machine, and recovery behavior. ## Modules - [`WorkerRegistry`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#workerregistry): holds two flat indexes, `deviceId` to its owning Worker and `workerId` to that Worker's record, and drives each Worker through its registration lifecycle - [`CommandDispatcher`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#commanddispatcher): validates an incoming command, resolves the target device or devices, and hands off to the Command State Machine - [`CommandStateMachine`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#commandstatemachine): tracks every command's execution lifecycle in a write-ahead log - [`TelemetryCollector`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#telemetrycollector): a proxy that routes telemetry queries to the Worker that owns the data, persisting none of it - [`Scheduler`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#scheduler): the system metronome that fires the recurring telemetry, health, and state jobs - [`HealthMonitor`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#healthmonitor): pings every registered Worker on a cadence and marks dead ones unroutable - [`ActionManager`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#actionmanager): handles the write action approval lifecycle at the Kernel layer - [`ActionCaller`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#actioncaller): resolves an approved action into the per-Worker write calls that carry it out ## Next steps - Review the [Protocol messages](/reference/protocol/messages): the actions these modules route and execute - See the [Kernel architecture](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md): the architectural narrative behind this module split - Understand [approval-gated writes](https://github.com/tetherto/mdk/blob/main/docs/concepts/control-plane.md#approval-gated-writes): the cross-layer flow [`ActionManager`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#actionmanager) and [`ActionCaller`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#actioncaller) implement # Protocol reference (/reference/protocol) The MDK Protocol is the contract that crosses every layer of the stack: Workers, `@tetherto/mdk-kernel`, 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#why-hrpc). ## 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) ## Overview Every MDK Protocol message uses the same envelope regardless of which layers are talking. This page shows the envelope shape and one worked example. ## Envelope ```json { "id": "uuid-v4", "version": "0.2.0", "type": "request | response | event", "action": "", "sender": "", "target": " | null", "deviceId": "string | null", "timestamp": 1711640000000, "payload": {} } ``` External consumers (UI or AI agents) only provide `deviceId`. [Kernel](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/index.js) resolves the target Worker identity internally. A concrete request and response pair, end to end: ```json // request: Gateway asks Kernel to reboot device wm-001 { "id": "8d1c-e3a4", "version": "0.2.0", "type": "request", "action": "command.request", "sender": "gateway", "target": null, "deviceId": "wm-001", "timestamp": 1711640000000, "payload": { "command": "reboot" } } // response: Kernel relays the Worker's terminal result { "id": "1f9b-77c2", "version": "0.2.0", "type": "response", "action": "command.result", "sender": "kernel:kernel:shard-1", "target": "gateway", "deviceId": "wm-001", "timestamp": 1711640002145, "payload": { "status": "SUCCESS", "elapsedMs": 2145 } } ``` ## Next steps - Learn more about actions and command targeting: - The [Kernel README](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#mdk-protocol) holds the full action catalogue (worker discovery, scheduled polling, command dispatch, kernel queries, and the write action lifecycle) and [command targeting rules](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#command-control) (`payload.scope`'s `device`, `worker`, and `rack` values, and the 1024-target cap) - [Approval-gated writes](https://github.com/tetherto/mdk/blob/main/docs/concepts/control-plane.md#approval-gated-writes) details the write action lifecycle's full cross-layer flow, and use [the write-actions how-to](/guides/gateway/write-actions) to submit and approve actions from a Gateway consumer - [How MDK works](/concepts/architecture): for the architectural narrative explaining when each action fires - See the [Kernel MDK Protocol spec](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#mdk-protocol) for every action, direction, and purpose - [Kernel modules](/reference/kernel/modules): the per-module specs that route and execute these actions - [Build a Worker](/guides/workers/build-a-worker): implement the Worker side of this protocol # Supported hardware (/reference/supported-hardware) ## Manufacturer-maintained workers ### Miners } title="Whatsminer" href="https://github.com/whatsminer/whatsminer-mdk-worker" description="microbt · Not enumerated; see manufacturer documentation" /> ## MDK-maintained workers ### Miners } title="Antminer" href="https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/README.md" description="bitmain · S19XP, S19XPH, S21, S21PRO" /> } title="Avalon" href="https://github.com/tetherto/mdk/blob/main/backend/workers/miners/avalon/README.md" description="canaan · A1346" /> ### Containers } title="Antspace" href="https://github.com/tetherto/mdk/blob/main/backend/workers/containers/antspace/README.md" description="bitmain · HK3, IMM" /> } title="Bitdeer" href="https://github.com/tetherto/mdk/blob/main/backend/workers/containers/bitdeer/README.md" description="bitdeer · D40-A1346, D40-M30, D40-M56, D40-S19XP" /> ### Power meters } title="ABB" href="https://github.com/tetherto/mdk/blob/main/backend/workers/power-meter/abb/README.md" description="abb · B23, B24, M1M20, M4M20, REU615" /> } title="SATEC" href="https://github.com/tetherto/mdk/blob/main/backend/workers/power-meter/satec/README.md" description="satec · PM180" /> } title="Schneider Electric" href="https://github.com/tetherto/mdk/blob/main/backend/workers/power-meter/schneider/README.md" description="schneider · P3U30, PM5340" /> ### Sensors } title="Seneca" href="https://github.com/tetherto/mdk/blob/main/backend/workers/temperature/seneca/README.md" description="seneca · Z-4RTD-2" /> ### Mining pools } title="F2Pool" href="https://github.com/tetherto/mdk/blob/main/backend/workers/minerpools/f2pool/README.md" description="f2pool · F2POOL-BTC" /> } title="Ocean" href="https://github.com/tetherto/mdk/blob/main/backend/workers/minerpools/ocean/README.md" description="ocean · OCEAN-BTC" /> ## Contract conformance All worker contracts validate cleanly against the vendored schema. # Supported plugins (/reference/supported-plugins) ## Overview A Gateway loads exactly the plugins your stack declares in `spec.gateway.plugins[]`, and nothing else. Nothing here auto-registers: a plugin contributes its routes only when a stack names it. MDK ships the following plugins: - Bundled site plugins, ready to use once a stack declares them as `@tetherto/mdk-plugins/` subpaths - Inert plugins, shipped for reference but not wired (declaration does not provide working endpoints) - Optional standalone plugins offered through [`mdk onboard`](/guides/cli/install#command-groups) ## MDK plugins ### Bundled site plugins #### `site-hashrate` | Method | Path | Description | | --- | --- | --- | | `GET` | `/api/site/hashrate-history` | Fans out telemetry.pull to every registered worker and returns site-level hashrate history aggregated by timestamp. Defaults to last 7 days when start/end are omitted | #### `site-monitor` | Method | Path | Description | | --- | --- | --- | | `GET` | `/auth/site` | Returns the site name from the gateway config (common.json `site`) | | `GET` | `/auth/featureConfig` | Returns the `featureConfig` object from the gateway config (common.json `featureConfig`) | | `GET` | `/site-monitor/hashrate` | Pulls metrics telemetry from every READY worker's devices via the MDK protocol and returns per-device hashrate/power plus site totals | #### `telemetry` | Method | Path | Description | | --- | --- | --- | | `GET` | `/auth/metrics/hashrate` | Returns daily hashrate history and summary for the site. Optionally groups by miner type or container | | `GET` | `/auth/metrics/consumption` | Returns daily power consumption (W and MWh) history and summary for the site | | `GET` | `/auth/metrics/efficiency` | Returns daily mining efficiency (W/TH) history and summary for the site | | `GET` | `/auth/metrics/miner-status` | Returns daily online/offline/sleep/maintenance miner counts and averages | | `GET` | `/auth/metrics/power-mode` | Returns miner count by power mode category (low/normal/high/sleep/offline) over time | | `GET` | `/auth/metrics/power-mode/timeline` | Returns per-miner power mode segments over a time range, optionally filtered by container | | `GET` | `/auth/metrics/temperature` | Returns max and average temperature per container over time, with site-level aggregates | | `GET` | `/auth/metrics/containers/{id}` | Returns latest telemetry snapshot and miner list for a specific container | | `GET` | `/auth/metrics/containers/{id}/history` | Returns historical telemetry log for a specific container | ### Inert #### `auth` | Method | Path | Description | | --- | --- | --- | | `GET` | `/auth/userinfo` | Returns the authenticated user's profile from the validated JWT | | `POST` | `/auth/token` | Issues a new JWT from an existing valid token, optionally scoping TTL and roles | | `GET` | `/auth/permissions` | Returns the permission set encoded in the current token | | `GET` | `/auth/ext-data` | Proxies an external data request to the Kernel network by type and optional query filter | ### Optional plugins #### `agent` | Method | Path | Description | | --- | --- | --- | | `POST` | `/agent/sessions` | Opens an agent session bound to the caller's identity | | `POST` | `/agent/sessions/:id/messages` | Streams an agent turn over SSE; write tools pause for an operator's approval | | `POST` | `/agent/sessions/:id/approvals/:approvalId` | Approves or rejects a paused write, resuming or ending the turn | | `DELETE` | `/agent/sessions/:id` | Deletes a session owned by the caller | #### `demo` | Method | Path | Description | | --- | --- | --- | | `GET` | `/api/demo/summary` | Fans out metrics telemetry to every registered demo-worker device (fingerprint: `hashrate_rt` + history) and returns fleet totals plus a per-device breakdown. Aggregation lives here — workers only ever answer for one device | | `GET` | `/api/demo/history` | Pulls the demo-worker `history` telemetry channel (SQLite recent samples: ts, `hashrate_ths`, `power_w`, `board_temp_c`) for every matched device, or a single device when `deviceId` is set | ## Next steps - [Declare a plugin in your stack](/guides/gateway/plugins): the manifest, controllers, and how a stack loads them - [Read the bundled-plugin package notes](https://github.com/tetherto/mdk/blob/main/backend/core/plugins/README.md): the `@tetherto/mdk-plugins` subpath plugins and the inert auth plugin # UI Reference (/reference/ui) Complete API reference for the MDK UI packages: `@tetherto/mdk-react-devkit`, `@tetherto/mdk-react-adapter`, and `@tetherto/mdk-ui-foundation`. ## Quick links | Section | Description | Count | |---------|-------------|-------| | [Components](/reference/ui/components) | React components for building UIs | 286 components | | [Hooks](/reference/ui/hooks) | React hooks for state and data | 107 hooks | | [Query Helpers](/reference/ui/query-helpers) | TanStack Query helpers for data fetching | 18 queryHelpers | | [Stores](/reference/ui/stores) | Zustand stores for state management | 5 stores | | [Types](/reference/ui/types) | TypeScript type definitions | 257 types | | [Utilities](/reference/ui/utilities) | Helper functions and formatters | 189 utilities | ## Package overview ### `@tetherto/mdk-react-devkit` The main UI component library. Provides: - Production-ready React components - Component-specific hooks - TypeScript types for all components ```tsx ``` ### `@tetherto/mdk-react-adapter` React bindings for the foundation layer. Provides: - Zustand store access hooks - Authentication hooks - Permission hooks - Data fetching hooks ```tsx ``` ### `@tetherto/mdk-ui-foundation` Framework-agnostic foundation layer. Provides: - Zustand stores - TanStack Query helpers - Utility functions - TypeScript types ```tsx ``` ## Get started 1. [Install the packages](/guides/ui/install) 2. Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` 3. Browse components by category or search for specific APIs # Components (/reference/ui/components) The `@tetherto/mdk-react-devkit` package provides production-ready React components organized by category. ## 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. - Import the core styles in your app's entry point: ```tsx ``` ## Browse by category | Category | Description | |----------|-------------| | [Actions](/reference/ui/components/actions) | Buttons, action triggers, and export controls | | [Auth](/reference/ui/components/auth) | Authentication and sign-in components | | [Branding](/reference/ui/components/branding) | Logos, wordmarks, and brand elements | | [Cards](/reference/ui/components/cards) | Card containers and card-based layouts | | [Charts](/reference/ui/components/charts) | Data visualization and chart components | | [Dashboard](/reference/ui/components/dashboard) | Dashboard layouts and containers | | [Dashboards](/reference/ui/components/dashboards) | Pre-built dashboard compositions | | [Dialogs](/reference/ui/components/dialogs) | Modal dialogs and confirmation prompts | | [Display](/reference/ui/components/display) | Data display and formatting components | | [Features](/reference/ui/components/features) | Feature-specific composite components | | [Feedback](/reference/ui/components/feedback) | Alerts, toasts, and user feedback | | [Filters](/reference/ui/components/filters) | Filter controls and filter bars | | [Forms](/reference/ui/components/forms) | Form inputs, selects, and validation | | [Layout](/reference/ui/components/layout) | Page layouts, grids, and spacing | | [Media](/reference/ui/components/media) | Images, icons, and media display | | [Misc](/reference/ui/components/misc) | Utility and miscellaneous components | | [Monitoring](/reference/ui/components/monitoring) | System monitoring and status displays | | [Navigation](/reference/ui/components/navigation) | Sidebars, tabs, and navigation menus | | [Overlays](/reference/ui/components/overlays) | Popovers, tooltips, and overlay panels | | [Pages](/reference/ui/components/pages) | Full-page layouts and page shells | | [Settings](/reference/ui/components/settings) | Settings panels and preference controls | | [Tables](/reference/ui/components/tables) | Data tables and table utilities | | [Widgets](/reference/ui/components/widgets) | Dashboard widgets and data cards | ## Import pattern Components are imported from the package root: ```tsx ``` ## Styling Components use BEM-style CSS classes (e.g., `.mdk-button`, `.mdk-card__header`) for styling consistency. Every component forwards `className` to its root element. # Action (/reference/ui/components/actions) Components for triggering actions and user interactions. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit ### Button ```tsx ``` Primary action button with variants, sizes, loading state, icon placement, and full-width layout. Forwards refs and all native ` ) ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ActionButton` [**`ActionButton`**](/reference/ui/components/actions/#actionbutton) component with confirmation popover or dialog `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/action-button/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/action-button/index.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `confirmation` | Required | `ActionButtonConfirmation` | - | Configuration for the confirmation UI | | `className` | Optional | `string` | - | Additional class for the trigger button | | `disabled` | Optional | `boolean` | - | Disables the trigger button | | `label` | Optional | `string` | - | [**`Button`**](/reference/ui/components/actions/#button) label text | | `loading` | Optional | `boolean` | - | Shows a spinner on the trigger button | | `mode` | Optional | `"dialog" \| "popover"` | `"popover"` | Confirmation mode: popover (inline) or dialog (modal) | | `variant` | Optional | `"primary" \| "danger" \| "secondary"` | `"secondary"` | Visual style of the trigger button | ### `Button` Primary action button. Supports loading state with spinner, icon placement, variants, sizes, and full-width layout. Forwards refs and all native button attributes `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/button/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/button/index.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `contentClassName` | Optional | `string` | - | Class names applied to the inner content wrapper | | `disabled` | Optional | `boolean` | `false` | Disable the button | | `fullWidth` | Optional | `boolean` | `false` | Make the button stretch to fill its container | | `icon` | Optional | `React.ReactNode` | - | Icon node rendered alongside `children` | | `iconPosition` | Optional | `"left" \| "right"` | `"left"` | Icon placement relative to children | | `loading` | Optional | `boolean` | `false` | Show a spinner instead of the content and disable the button | | `size` | Optional | `"sm" \| "md" \| "lg"` | - | Size token (`sm`, `md`, `lg`) | | `type` | Optional | `"button" \| "submit" \| "reset"` | `"button"` | Native button type | | `variant` | Optional | `"icon" \| "link" \| "primary" \| "danger" \| "secondary" \| "tertiary" \| "nav-link" \| "outline" \| "ghost"` | `"secondary"` | Visual variant (e.g. `primary`, `secondary`, `ghost`) | ### `StatsExport` Dropdown button that triggers asynchronous CSV or JSON export. Shows a spinner while the corresponding handler is awaited `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/stats-export/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/stats-export/index.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onCsvExport` | Required | `() => Promise` | - | Awaited; spinner shown while pending | | `onJsonExport` | Required | `() => Promise` | - | Awaited; spinner shown while pending | | `disabled` | Optional | `boolean` | `false` | Disable the trigger | | `hideLabel` | Optional | `boolean` | `false` | Hides the textual "Export" label | # Auth (/reference/ui/components/auth) Components for authentication flows and user sign-in. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `RequireAuth` Route guard that reads the session token from the headless `authStore` (via `useAuth`) and renders the children only when a token is present. Otherwise it renders `fallback` — typically `` from `react-router`. Router-agnostic by design `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/auth/require-auth/require-auth.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/auth/require-auth/require-auth.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Required | `React.ReactNode` | - | Rendered when a token is present | | `fallback` | Required | `React.ReactNode` | - | Rendered when no token is present — typically `` | | `rememberPath` | Optional | `boolean` | `true` | When true (default), the current location is persisted to sessionStorage before rendering the fallback so the sign-in flow can return there | ### `SignInGoogleButton` One-click Google OAuth sign-in trigger. Defaults to a full-page redirect to `${oauthBaseUrl}/oauth/google`, mirroring the reference app's production flow `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/auth/sign-in-google-button/sign-in-google-button.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/auth/sign-in-google-button/sign-in-google-button.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `oauthBaseUrl` | Required | `string` | - | Base URL of the OAuth backend (no trailing slash). Click navigates to `${oauthBaseUrl}/oauth/google` | | `contentClassName` | Optional | `string` | - | Class names applied to the inner content wrapper | | `disabled` | Optional | `boolean` | `false` | Disable the button | | `fullWidth` | Optional | `boolean` | `false` | Make the button stretch to fill its container | | `icon` | Optional | `React.ReactNode` | - | Icon node rendered alongside `children` | | `iconPosition` | Optional | `"left" \| "right"` | `"left"` | Icon placement relative to children | | `label` | Optional | `string` | `"Sign in with Google"` | Override the visible button label | | `loading` | Optional | `boolean` | `false` | Show a spinner instead of the content and disable the button | | `onClick` | Optional | `(() => void)` | `redirect` | Override the click behaviour entirely. When set, `oauthBaseUrl` is ignored | | `size` | Optional | `"sm" \| "md" \| "lg"` | - | Size token (`sm`, `md`, `lg`) | | `type` | Optional | `"button" \| "submit" \| "reset"` | `"button"` | Native button type | | `variant` | Optional | `"icon" \| "link" \| "primary" \| "danger" \| "secondary" \| "tertiary" \| "nav-link" \| "outline" \| "ghost"` | `"secondary"` | Visual variant (e.g. `primary`, `secondary`, `ghost`) | # Branding (/reference/ui/components/branding) Components for brand identity and visual consistency. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `MdkWordmark` MDK wordmark — the canonical brand lockup, rendered as inline SVG so it tints to `currentColor`. Use this in [``](/reference/ui/components/navigation/#appheader) (via the `logo` slot) or anywhere else the brand should appear `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/mdk-wordmark/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/mdk-wordmark/index.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Optional class hook on the outer `

Chart content

) const [range, setRange] = useState('24h') return (

) } ``` #### Related API - [**`useChartDataCheck`**](/reference/ui/hooks/charts/#usechartdatacheck) @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ActualEbitdaCard` Stat card summarising the realised EBITDA for the selected reporting window vs the prior period `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/actual-ebitda-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/actual-ebitda-card.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `value` | Required | `number` | - | - | ### `AreaChart` Presentational Chart.js area chart (Line with fill). Data must be provided via props; this component does no fetching of its own `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/area-chart/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/area-chart/index.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `ChartData<"line", (number \| Point \| null)[], unknown>` | - | Chart data - required, provided by parent | | `className` | Optional | `string` | - | Additional class names | | `height` | Optional | `number` | `300` | Chart height in pixels | | `options` | Optional | `object` | - | Chart.js options - merged with defaults | | `tooltip` | Optional | `ChartTooltipConfig` | - | Custom HTML tooltip configuration. When provided, replaces the default Chart.js tooltip | ### `AverageDowntimeChart` Stacked bar chart of average downtime (curtailment vs operational issues). Wraps [`ChartContainer`](/reference/ui/components/charts/#chartcontainer) and [`BarChart`](/reference/ui/components/charts/#barchart); pass period labels and rate arrays via `data` `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/average-downtime-chart/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/average-downtime-chart/index.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `barWidth` | Optional | `number` | `38` | Max bar thickness | | `className` | Optional | `string` | - | Extra class on the container | | `data` | Optional | `AverageDowntimeChartData` | - | Period labels and rate arrays (fractions 0–1) | | `emptyMessage` | Optional | `string` | - | Message when there are no period labels or rate series | | `height` | Optional | `number` | `280` | Chart height in pixels | | `isLoading` | Optional | `boolean` | `false` | Shows loading overlay | | `showDataLabels` | Optional | `boolean` | `false` | Show values above stacked bars | | `title` | Optional | `string` | `"Monthly Average Downtime"` | Chart title (unit renders on its own line below) | | `unit` | Optional | `string` | `%` | Unit subtitle under the title | | `yTicksFormatter` | Optional | `(value: number) => string` | - | Formats Y-axis ticks, tooltips, and bar data labels (values are 0–1 rates). Defaults to rate × 100 via `formatNumber` | ### `AvgAllInCostChart` Avg All-in [**`Cost`**](/reference/ui/components/dashboards/#cost) - revenue vs cost ($/MWh) bar chart over time. Renders the OSS `SiteEnergyVsCostChart`. The revenue/cost time-series isn't carried by the cost-summary response, so consumers feed it through as a separate prop (the OSS app sources it from `useAvgAllInPowerCostData`) `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/avg-all-in-cost-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/avg-all-in-cost-chart.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `dateRange` | Required | `FinancialDateRange \| null` | - | - | | `data` | Optional | `readonly AvgAllInCostDataPoint[]` | - | - | | `isLoading` | Optional | `boolean` | - | - | ### `BarChart` Presentational Chart.js bar chart. Data must be pre-aggregated; use grouped or stacked categories via `datasets` `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/bar-chart/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/bar-chart/index.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `any` | - | Chart data - required, provided by parent. Use `as any` for mixed bar+line datasets | | `className` | Optional | `string` | - | Additional class for the wrapper `div` | | `formatDataLabel` | Optional | `((value: number) => string)` | - | Format data label values (default: round to nearest integer) | | `formatYLabel` | Optional | `((value: number) => string)` | - | Format Y-axis tick labels | | `height` | Optional | `number` | `300` | Chart height in pixels | | `isHorizontal` | Optional | `boolean` | `false` | Render bars horizontally (indexAxis: 'y') | | `isStacked` | Optional | `boolean` | `false` | Stack bars on top of each other | | `legendAlign` | Optional | `"center" \| "start" \| "end"` | `"start"` | Alignment of the legend labels within their position | | `legendPosition` | Optional | `"left" \| "right" \| "top" \| "bottom"` | `"top"` | Position of the legend | | `options` | Optional | `object` | - | Chart.js options - merged with defaults | | `showDataLabels` | Optional | `boolean` | `false` | Show values above each bar | | `showLegend` | Optional | `boolean` | `true` | Show built-in Chart.js legend | | `tooltip` | Optional | `ChartTooltipConfig` | - | Custom HTML tooltip configuration. When provided, replaces the default Chart.js tooltip | ### `BitcoinPriceCard` Stat card showing the BTC reference price used by the reporting view with currency and timestamp `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/bitcoin-price-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/bitcoin-price-card.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `value` | Required | `number` | - | - | ### `BitcoinProducedCard` Stat card summarising the bitcoin produced during the reporting window with delta to prior period `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/bitcoin-produced-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/bitcoin-produced-card.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `value` | Required | `number` | - | - | ### `BitcoinProducedChart` Time-series chart of bitcoin produced per day across the selected reporting window `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/bitcoin-produced-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/bitcoin-produced-chart.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartData` | Required | `BarChartDataResult` | - | - | | `hasAllZeros` | Optional | `boolean` | - | - | | `height` | Optional | `number` | - | - | | `isLoading` | Optional | `boolean` | - | - | ### `BitcoinProductionCostCard` Stat card showing the average cost in USD to produce one bitcoin during the reporting window `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/bitcoin-production-cost-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/bitcoin-production-cost-card.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `value` | Required | `number` | - | - | ### `ChartContainer` Standard chrome for charts: title, optional highlighted value, legend with toggle, range selector (radio cards), loading / empty states, and a footer for min/max/avg stats `agent-ready`

Source

[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/chart-container/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/chart-container/index.tsx)

#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Required | `React.ReactNode` | - | The chart element to render | | `className` | Optional | `string` | - | Additional class for the root element | | `empty` | Optional | `boolean` | - | Hides the chart and shows `emptyMessage` | | `emptyMessage` | Optional | `string` | `"No data available"` | Message shown when `empty` is true | | `footer` | Optional | `React.ReactNode` | - | Custom footer content rendered below the chart | | `footerClassName` | Optional | `string` | - | Additional class for the footer area | | `header` | Optional | `React.ReactNode` | - | Replaces the default `title` heading with a custom element | | `headerAction` | Optional | `React.ReactNode` | - | Optional action rendered on the right side of the header row (e.g. an expand/fullscreen toggle). Sits alongside the range selector when both are present. Purely additive - omit it and the header renders exactly as before | | `highlightedValue` | Optional | `HighlightedValueProps` | - | Large value/unit displayed alongside the legend | | `legendData` | Optional | `LegendItem[]` | - | Color-keyed legend items; each item can be toggled | | `loading` | Optional | `boolean` | - | Shows a centered [``](/reference/ui/components/feedback/#loader) overlay | | `minMaxAvg` | Optional | `Partial<{ min: string; max: string; avg: string; }>` | - | Built-in footer showing Min / Avg / Max values | | `onToggleDataset` | Optional | `((index: number) => void)` | - | Fired when a legend item is clicked | | `rangeSelector` | Optional | `RangeSelectorProps` | - | [**`Radio`**](/reference/ui/components/forms/#radio)-card time-range selector | | `timeRange` | Optional | `string` | - | Time range label shown in the footer | | `title` | Optional | `string` | - | Chart heading (renders as `

` unless `header` is provided) | | `titleExtra` | Optional | `React.ReactNode` | - | Optional node rendered immediately after the title text (e.g. an info tooltip). Only shown when `title` is set and `header` is not. Additive - omit it and the title renders exactly as before | ### `ChartExpandAction` Expand / collapse toggle rendered in a dashboard chart card's header. Swaps between a maximize and a minimize glyph based on `isExpanded` `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/chart-expand-action.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/chart-expand-action.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isExpanded` | Required | `boolean` | - | Whether the parent chart is currently expanded to full width | | `onToggle` | Optional | `VoidFunction` | - | Toggles the expanded state | ### `ChartStatsFooter` [`ChartStatsFooter`](/reference/ui/components/charts/#chartstatsfooter) - Displays Min/Max/Avg values and optional stats grid below a chart `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/chart-stats-footer/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/chart-stats-footer/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Custom class name | | `minMaxAvg` | Optional | `Partial<{ min: string; max: string; avg: string; }>` | - | Min/Max/Avg values row | | `secondaryLabel` | Optional | `SecondaryLabel` | - | Secondary label displayed below stats | | `stats` | Optional | `ChartStatsFooterItem[]` | - | Additional stats displayed in a columnar grid | | `statsPerColumn` | Optional | `number` | `1` | Number of stat items per column (default: 1) | ### `CostCharts` Convenience wrapper that renders the three cost-page charts in declaration order. Pages that need bespoke layouts (e.g. [`CostContent`](/reference/ui/components/dashboards/#costcontent)'s 2x2 [`Mosaic`](/reference/ui/components/layout/#mosaic)) compose the individual chart components directly instead `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/cost-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/cost-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `btcPriceLog` | Required | `readonly BtcPriceTimeSeriesEntry[]` | - | - | | `costLog` | Required | `readonly CostTimeSeriesEntry[]` | - | - | | `dateRange` | Required | `FinancialDateRange \| null` | - | - | | `totals` | Required | `CostSummaryMonetaryTotals \| null` | - | - | | `avgAllInCostData` | Optional | `readonly AvgAllInCostDataPoint[]` | - | - | | `isLoading` | Optional | `boolean` | - | - | ### `DetailLegend` [`DetailLegend`](/reference/ui/components/charts/#detaillegend) - Enhanced chart legend with current values and percentage change indicators `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/detail-legend/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/detail-legend/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `items` | Required | `DetailLegendItem[]` | - | Legend items to display | | `className` | Optional | `string` | - | Custom class name | | `onToggle` | Optional | `((label: string, index: number) => void)` | - | Callback when a legend item is toggled | ### `DoughnutChart` [`DoughnutChart`](/reference/ui/components/charts/#doughnutchart) – Presentational Chart.js doughnut chart with custom HTML legend matching the MDK design `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/doughnut-chart/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/doughnut-chart/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `DoughnutChartDataset[]` | - | Array of labelled slices | | `borderWidth` | Optional | `number` | `4` | Border width between segments (default: 4) | | `className` | Optional | `string` | - | Additional class for the root element | | `cutout` | Optional | `string` | `"75%"` | Doughnut cutout percentage (default: '75%') | | `formatValue` | Optional | `((value: number) => string)` | - | Formats slice values in the built-in legend and default tooltip (default: raw number) | | `height` | Optional | `number` | `260` | Chart height in pixels | | `legendPosition` | Optional | `"left" \| "right" \| "top" \| "bottom"` | `"top"` | Where to place the legend relative to the chart (default: 'top') | | `options` | Optional | `object` | - | Chart.js options – merged with defaults | | `tooltip` | Optional | `ChartTooltipConfig` | - | Custom HTML tooltip configuration. When provided, replaces the default doughnut tooltip (which shows label, value with unit, and percentage). Use `valueFormatter` to replicate the percentage display if needed | | `unit` | Optional | `string` | `""` | Unit suffix appended to values in tooltips and legends | ### `Ebitda` Top-level EBITDA section of the reporting view — pulls together metric cards, charts, and tables `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/ebitda.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/ebitda.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `btcProducedChartInput` | Required | `ToBarChartDataInput \| null` | - | Data for the BTC produced chart | | `currentBTCPrice` | Required | `number` | - | Current Bitcoin price in USD | | `datePicker` | Required | `React.ReactElement>` | - | Date picker element | | `ebitdaChartInput` | Required | `ToBarChartDataInput \| null` | - | Data for the EBITDA bar chart | | `hasBtcProducedAllZeros` | Required | `boolean` | - | Whether all BTC produced values are zero | | `hasDateSelection` | Required | `boolean` | - | When false, show the "select a period" hint instead of empty data | | `metrics` | Required | `EbitdaDisplayMetrics \| null` | - | Computed EBITDA metrics | | `showEbitdaBarChart` | Required | `boolean` | - | Show the EBITDA bar chart | | `errors` | Optional | `string[]` | `[]` | Error messages to display | | `isLoading` | Optional | `boolean` | `false` | Loading state | | `setCostHref` | Optional | `string` | - | Optional URL for the "Set Monthly [`Cost`](/reference/ui/components/dashboards/#cost)" control (hidden when omitted) | ### `EbitdaCharts` Chart panel inside the EBITDA section visualising revenue, cost, and EBITDA over time `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/ebitda-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/ebitda-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `btcDisplayData` | Required | `BarChartDataResult` | - | - | | `ebitdaChartData` | Required | `BarChartDataResult` | - | - | | `hasBtcProducedAllZeros` | Required | `boolean` | - | - | | `isLoading` | Required | `boolean` | - | - | | `showEbitdaBarChart` | Required | `boolean` | - | - | ### `EbitdaHodlCard` Stat card projecting EBITDA assuming all produced bitcoin is held instead of sold `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/ebitda-hodl-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/ebitda-hodl-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `currentBTCPrice` | Required | `number` | - | - | | `value` | Required | `number` | - | - | ### `EbitdaMetrics` Row of summary metric cards across the top of the EBITDA section (actual, hodl, selling, cost) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/ebitda-metrics.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/ebitda-metrics.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `currentBTCPrice` | Required | `number` | - | - | | `metrics` | Required | `EbitdaDisplayMetrics` | - | - | ### `EbitdaSellingCard` Stat card projecting EBITDA assuming all produced bitcoin is sold at the daily reference price `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/ebitda-selling-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/ebitda-selling-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `value` | Required | `number` | - | - | ### `EnergyBalance` Full energy balance view with tabbed revenue and cost sections, charts, and metric cards `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onCostDisplayModeChange` | Required | `(mode: DisplayMode) => void` | - | Called when the user toggles USD / BTC on the cost tab | | `onRevenueDisplayModeChange` | Required | `(mode: DisplayMode) => void` | - | Called when the user toggles USD / BTC on the revenue tab | | `onTabChange` | Required | `(tab: EnergyBalanceTab) => void` | - | Called when the user switches between Revenue and [`Cost`](/reference/ui/components/dashboards/#cost) tabs | | `viewModel` | Required | `EnergyBalanceViewModel` | - | All display state: chart inputs, metrics, active tab, display modes, loading/error flags. Returned directly by [`useEnergyBalanceViewModel`](/reference/ui/hooks/charts/#useenergybalanceviewmodel) | | `isDemoMode` | Optional | `boolean` | `false` | Suppresses error banners in demo/mock environments | | `setCostHref` | Optional | `string` | - | Optional URL for the "Set Monthly [`Cost`](/reference/ui/components/dashboards/#cost)" control (hidden when omitted) | | `timeframeControls` | Optional | `React.ReactNode` | - | Slot for timeframe / date-range controls rendered by the host app | ### `EnergyBalanceCostCharts` Layout container for the energy cost tab charts: revenue-vs-cost bar chart and power line chart `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance-cost-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance-cost-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `barLabelFormatter` | Required | `(v: number) => string` | - | - | | `btcUnit` | Required | `string \| null` | - | - | | `costChartData` | Required | `BarChartDataResult` | - | - | | `displayMode` | Required | `"BTC" \| "USD"` | - | - | | `onDisplayModeChange` | Required | `(mode: DisplayMode) => void` | - | - | | `periodType` | Required | `"month" \| "week" \| "day"` | - | - | | `powerChartInput` | Required | `ThresholdLineChartInput` | - | - | | `showCostBarChart` | Required | `boolean` | - | Show the revenue-vs-cost bar chart only for non-daily periods | ### `EnergyBalanceCostMetrics` Grid of stat cards summarising energy cost metrics for the selected period `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance-cost-metrics.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance-cost-metrics.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `metrics` | Required | `EnergyCostMetrics` | - | - | ### `EnergyBalancePowerChart` Line chart visualising power consumption against threshold for the energy balance view `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/components/energy-balance-power-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/components/energy-balance-power-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartInput` | Required | `ThresholdLineChartInput` | - | Series and optional threshold line for power vs availability | | `periodType` | Required | `"month" \| "week" \| "day"` | - | Controls x-axis date formatting (`month` uses `MM-yy`) | | `fillHeight` | Optional | `boolean` | `false` | Stretch the panel and chart to fill a mosaic cell (uses height `320` and `mdk-energy-balancepanel--fill`). Used on the revenue tab power column in [`EnergyBalanceRevenueCharts`](/reference/ui/components/charts/#energybalancerevenuecharts) | | `height` | Optional | `number` | `280` | Chart height when `fillHeight` is false | ### `EnergyBalanceRevenueCharts` [`Mosaic`](/reference/ui/components/layout/#mosaic) layout of revenue, downtime, and power charts for the energy balance revenue tab `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance-revenue-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance-revenue-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `averageDowntimeData` | Required | `AverageDowntimeChartData` | - | - | | `barLabelFormatter` | Required | `(v: number) => string` | - | - | | `displayMode` | Required | `"BTC" \| "USD"` | - | - | | `onDisplayModeChange` | Required | `(mode: DisplayMode) => void` | - | - | | `periodType` | Required | `"month" \| "week" \| "day"` | - | - | | `powerChartInput` | Required | `ThresholdLineChartInput` | - | - | | `revenueChartData` | Required | `BarChartDataResult` | - | - | | `revenueMetrics` | Required | `EnergyRevenueMetrics` | - | - | ### `EnergyBalanceRevenueMetrics` Grid of stat cards summarising energy revenue metrics for the selected period `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance-revenue-metrics.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/energy-balance-revenue-metrics.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `metrics` | Required | `EnergyRevenueMetrics` | - | - | ### `EnergyCostChart` Bar chart comparing site revenue vs cost per MWh, with USD/BTC currency toggle `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/components/energy-cost-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/components/energy-cost-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `barLabelFormatter` | Required | `(v: number) => string` | - | - | | `btcUnit` | Required | `string \| null` | - | - | | `chartData` | Required | `BarChartDataResult` | - | - | | `displayMode` | Required | `"BTC" \| "USD"` | - | - | | `onDisplayModeChange` | Required | `(mode: DisplayMode) => void` | - | - | | `height` | Optional | `number` | - | - | ### `EnergyMetricCard` Stat card for a single energy balance metric `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/components/energy-metric-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/components/energy-metric-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `name` | Required | `string` | - | Metric label shown on the card | | `unit` | Required | `string` | - | Unit suffix shown next to the value | | `value` | Required | `number` | - | Metric value, formatted via `formatNumber` | | `fallback` | Optional | `string` | - | Text shown when `value` can't be formatted | ### `EnergyReportMinerTypeView` Energy report — power consumption grouped by miner model (latest day in range) `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/composite/reporting-tool/operational/energy-report/miner-type-view/miner-type-view.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/composite/reporting-tool/operational/energy-report/miner-type-view/miner-type-view.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `containers` | Optional | `Container[]` | - | - | | `groupedConsumption` | Optional | `MetricsConsumptionGroupedResponse` | - | - | | `isLoading` | Optional | `boolean` | - | - | | `onTimeFrameChange` | Optional | `((start: Date, end: Date) => void)` | - | - | ### `EnergyReportMinerUnitView` Energy report — power consumption grouped by mining unit / container `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/composite/reporting-tool/operational/energy-report/miner-unit-view/miner-unit-view.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/composite/reporting-tool/operational/energy-report/miner-unit-view/miner-unit-view.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `containers` | Optional | `Container[]` | - | - | | `groupedConsumption` | Optional | `MetricsConsumptionGroupedResponse` | - | - | | `isLoading` | Optional | `boolean` | - | - | | `onTimeFrameChange` | Optional | `((start: Date, end: Date) => void)` | - | - | ### `EnergyReportSiteView` Energy report site tab — power trend, power-mode table, and per–mining-unit activity cards `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/composite/reporting-tool/operational/energy-report/site-view/site-view.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/composite/reporting-tool/operational/energy-report/site-view/site-view.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `dateRange` | Required | `EnergyReportDateRange` | - | - | | `consumptionError` | Optional | `unknown` | - | - | | `consumptionFetching` | Optional | `boolean` | - | - | | `consumptionLoading` | Optional | `boolean` | - | - | | `consumptionLog` | Optional | `MetricsConsumptionLogEntry[]` | - | - | | `containers` | Optional | `EnergyReportContainer[]` | - | - | | `containersLoading` | Optional | `boolean` | - | - | | `nominalConfigLoading` | Optional | `boolean` | - | - | | `nominalPowerAvailabilityMw` | Optional | `number \| null` | - | - | | `onDateRangeChange` | Optional | `((range: EnergyReportDateRange) => void)` | - | - | | `onRefetchSnapshot` | Optional | `VoidFunction` | - | - | | `snapshotLoading` | Optional | `boolean` | - | - | | `tailLog` | Optional | `EnergyReportTailLogItem[][]` | - | - | | `tailLogLoading` | Optional | `boolean` | - | - | ### `EnergyRevenueChart` Bar chart showing site energy revenue per MWh, with USD/BTC currency toggle `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/components/energy-revenue-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/energy-balance/components/energy-revenue-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `barLabelFormatter` | Required | `(v: number) => string` | - | - | | `chartData` | Required | `BarChartDataResult` | - | - | | `displayMode` | Required | `"BTC" \| "USD"` | - | - | | `onDisplayModeChange` | Required | `(mode: DisplayMode) => void` | - | - | | `height` | Optional | `number` | - | - | ### `GaugeChart` [`GaugeChart`](/reference/ui/components/charts/#gaugechart) - Presentational gauge / speedometer chart. Implementation note: the gauge is drawn by a pure-SVG internal implementation (see `./gauge-svg.tsx`), so the component is bundler- and runtime-agnostic and carries no third-party runtime dependency. The gauge packages on NPM are published CommonJS-only with a `module` field pointing at the same CJS file, which crashes under ESM bundlers that add no `esModule ? .default : module` interop shim (Webpack 4, raw esbuild, some SSR setups) with React's "Element type is invalid" error `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/gauge-chart/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/gauge-chart/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `percent` | Required | `number` | - | Value between 0 and 1 (e.g. 0.75 = 75%). Values outside the range are clamped | | `arcsLength` | Optional | `number[]` | - | Custom arc-segment proportions (auto-normalised), overriding `nrOfLevels`. e.g. `[0.7, 0.3]` for a progress-style gauge whose first arc is the fill | | `arcWidth` | Optional | `number` | `0.2` | Arc thickness as a fraction of the gauge radius (0–1) | | `className` | Optional | `string` | - | Additional class for the root `div` | | `colors` | Optional | `string[]` | `[COLOR.GREEN, COLOR.RED]` | Arc colours in HEX format | | `formatTextValue` | Optional | `((percent: number) => string)` | - | Format the center label from the clamped fraction (0–1) | | `height` | Optional | `string \| number` | `200` | Chart height in pixels or any CSS length (e.g. `'200px'` or `'50%'`) | | `hideNeedle` | Optional | `boolean` | `false` | Hide the needle + hub (e.g. for a progress-style gauge) | | `hideText` | Optional | `boolean` | `false` | Hide the percentage text rendered inside the gauge | | `id` | Optional | `string` | `"mdk-gauge-chart"` | Stable id used for the gauge's accessibility labels | | `maxWidth` | Optional | `number` | - | Maximum width in pixels | | `needleColor` | Optional | `string` | `COLOR.STEEL_GRAY` | Needle + hub colour | | `nrOfLevels` | Optional | `number` | `3` | Number of arc segments. Ignored when `arcsLength` is provided | ### `Hashrate` Top-level hashrate reporting section - composes the site / miner-type / mining-unit drilldowns into a tabbed shell. Each tab fetches independently because the three views use different `groupBy` axes; the composite stitches them via per-tab prop bags `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/hashrate/hashrate.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/hashrate/hashrate.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `defaultTab` | Optional | `"site-view" \| "miner-type-view" \| "mining-unit-view"` | `"site-view"` | Tab selected on first render. Defaults to the Site View | | `minerTypeView` | Optional | `HashrateMinerTypeViewProps` | - | Props forwarded to the Miner Type View tab | | `miningUnitView` | Optional | `HashrateMiningUnitViewProps` | - | Props forwarded to the Mining Unit View tab | | `siteView` | Optional | `HashrateSiteViewProps` | - | Props forwarded to the Site View tab | ### `HashrateMinerTypeView` [`Hashrate`](/reference/ui/components/charts/#hashrate) drilldown grouped by miner model - bar chart of the latest hashrate per miner type, with an optional multi-select filter `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/hashrate/tabs/miner-type-view/miner-type-view.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/hashrate/tabs/miner-type-view/miner-type-view.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `dateRange` | Optional | `HashrateDateRange` | - | Selected date range | | `isLoading` | Optional | `boolean` | `false` | Drives the chart spinner | | `log` | Optional | `HashrateGroupedLog` | `[]` | [`Hashrate`](/reference/ui/components/charts/#hashrate) log grouped by miner type (groupBy=miner) | | `onDateRangeChange` | Optional | `((range: HashrateDateRange) => void)` | - | Fires when the user picks a new range | | `onReset` | Optional | `VoidFunction` | - | Optional reset handler | ### `HashrateMiningUnitView` [`Hashrate`](/reference/ui/components/charts/#hashrate) drilldown grouped by mining unit / container - bar chart of the latest hashrate per container with an optional multi-select filter. Drops BE-leaked rollup keys (`group-N`, `maintenance`) via the utils layer `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/hashrate/tabs/mining-unit-view/mining-unit-view.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/hashrate/tabs/mining-unit-view/mining-unit-view.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `dateRange` | Optional | `HashrateDateRange` | - | Selected date range | | `isLoading` | Optional | `boolean` | `false` | Drives the chart spinner | | `log` | Optional | `HashrateGroupedLog` | `[]` | [`Hashrate`](/reference/ui/components/charts/#hashrate) log grouped by container / mining unit (groupBy=container) | | `onDateRangeChange` | Optional | `((range: HashrateDateRange) => void)` | - | Fires when the user picks a new range | | `onReset` | Optional | `VoidFunction` | - | Optional reset handler | ### `HashrateSiteView` Site-level hashrate trend - aggregates hashrate across the whole site for the selected date range, with an optional miner-type filter that scopes the sum to a subset `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/hashrate/tabs/site-view/site-view.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/hashrate/tabs/site-view/site-view.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `dateRange` | Optional | `HashrateDateRange` | - | Selected date range used by the host to drive the query | | `isLoading` | Optional | `boolean` | `false` | Loading state - drives the chart spinner | | `log` | Optional | `HashrateGroupedLog` | `[]` | [`Hashrate`](/reference/ui/components/charts/#hashrate) log grouped by miner type | | `onDateRangeChange` | Optional | `((range: HashrateDateRange) => void)` | - | Fires when the user picks a new range from the [`DateRangePicker`](/reference/ui/components/forms/#daterangepicker) | | `onReset` | Optional | `VoidFunction` | - | Optional reset handler shown as a "Reset" button next to the date picker | ### `Heatmap` [`Heatmap`](/reference/ui/components/charts/#heatmap) — a generic grid of value-coloured cells on a low→high gradient. Presentational and domain-agnostic: pass a row-major matrix of cells and an optional `[min, max]` range (auto-derived otherwise). Use `renderCell` to overlay domain content (socket borders, selection, tooltips) without forking the primitive — the grid still owns each cell's background colour. Pair with [`HeatmapLegend`](/reference/ui/components/charts/#heatmaplegend) for a gradient scale `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/heatmap/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/heatmap/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `HeatmapCell[][]` | - | Rows of cells (row-major). Rows may be ragged | | `ariaLabel` | Optional | `string` | `"Heatmap"` | Accessible label for the grid | | `className` | Optional | `string` | - | Additional class for the root element | | `colors` | Optional | `readonly string[]` | `HEATMAP_GRADIENT` | Gradient stops low→high. Defaults to the cold→hot `HEATMAP_GRADIENT` | | `emptyColor` | Optional | `string` | `#000000` | Colour used for `null` cells | | `max` | Optional | `number` | `auto` | Range ceiling (maps to the last gradient stop); auto-derived from the finite values when omitted | | `min` | Optional | `number` | `auto` | Range floor (maps to the first gradient stop); auto-derived from the finite values when omitted | | `renderCell` | Optional | `((cell: HeatmapCell, context: HeatmapCellContext) => React.ReactNode)` | - | Override the cell's inner content — e.g. to overlay socket borders, selection, or tooltips for a PDU grid. The primitive still owns the cell's background colour (passed via `context.color`) | | `showValues` | Optional | `boolean` | `false` | Render each cell's value/label as text | ### `HeatmapLegend` [`HeatmapLegend`](/reference/ui/components/charts/#heatmaplegend) — a gradient bar with low/high scale labels, matching the gradient used by [`Heatmap`](/reference/ui/components/charts/#heatmap) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/heatmap/heatmap-legend.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/heatmap/heatmap-legend.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `max` | Required | `string \| number` | - | Value (or pre-formatted label) at the high end of the scale | | `min` | Required | `string \| number` | - | Value (or pre-formatted label) at the low end of the scale | | `className` | Optional | `string` | - | Additional class for the root element | | `colors` | Optional | `readonly string[]` | `HEATMAP_GRADIENT` | Gradient stops low→high | | `label` | Optional | `string` | - | Heading above the gradient bar (e.g. "Temperature") | | `unit` | Optional | `string` | - | Unit suffix appended to `min`/`max` | ### `LineChart` Customisable Chart.js line chart with built-in zoom, tooltip, and legend. Data is passed via props; the component does no fetching `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/line-chart/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/line-chart/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `LineChartData` | - | Data of the chart | | `backgroundColor` | Optional | `string` | - | Background color of the chart | | `beginAtZero` | Optional | `boolean` | - | Starts the value axis at 0 | | `chartRef` | Optional | `React.MutableRefObject` | - | Mutable ref to hold the LightWeightCharts reference | | `customDateFormat` | Optional | `string` | - | Custom date format | | `customLabel` | Optional | `string` | - | TODO: Doc | | `disableAutoRange` | Optional | `boolean` | - | Disable automatically determining range | | `fadedBackground` | Optional | `boolean` | - | Use a faded background | | `fixedTimezone` | Optional | `string` | - | Applies offset if provided, otherwise timestamps are assumed to already be in local time. Otherwise, use browser's current timezone offset for consistent time display | | `height` | Optional | `number` | `240` | Controls the height of the chart | | `horizontalLineLabelVisible` | Optional | `boolean` | - | Show horizontal line at mouse position | | `priceFormatter` | Optional | `((value: number) => string)` | - | Callback to format ticks on y axis | | `roundPrecision` | Optional | `number` | - | The number of decimals to show | | `shouldResetZoom` | Optional | `boolean` | - | Wether to Reset Zoom | | `showDateInTooltip` | Optional | `boolean` | - | Show date line in tooltip | | `showPointMarkers` | Optional | `boolean` | - | Show a marker on the line | | `skipMinWidth` | Optional | `boolean` | - | Do not enforce a min width | | `skipRound` | Optional | `boolean` | - | Prevent rounding of values | | `timeline` | Optional | `string` | - | TODO: DOC | | `uniformDistribution` | Optional | `boolean` | - | Changes horizontal scale marks generation. With this flag equal to true, marks of the same weight are either all drawn or none are drawn at all | | `unit` | Optional | `string` | `""` | The unit to display with values | | `verticalLineLabelVisible` | Optional | `boolean` | - | Show vertical line at mouse position | | `yTicksFormatter` | Optional | `((value: number) => string)` | - | Callback to format ticks on y axis. If `priceFormatter` is given. It would be used instead | ### `LineChartCard` Composable line-chart card with title, timeline range selector, legend (basic or detailed), error boundary, and an optional min/max/avg footer. Accepts either pre-shaped `data` or `rawData` + a `dataAdapter` callback so upstream domain components can keep their data wrangling local `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/line-chart-card/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/line-chart-card/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartProps` | Optional | `Partial` | - | Pass-through props to the core [`LineChart`](/reference/ui/components/charts/#linechart) | | `chartRef` | Optional | `React.MutableRefObject` | - | Ref to the lightweight-charts IChartApi | | `className` | Optional | `string` | - | Custom class name | | `data` | Optional | `LineChartCardData` | - | Pre-adapted chart data (use this OR rawData+dataAdapter) | | `dataAdapter` | Optional | `(data: unknown) => LineChartCardData` | - | Adapter to transform rawData into LineChartCardData | | `defaultTimeline` | Optional | `string` | `first option` | Default timeline when uncontrolled | | `detailLegends` | Optional | `boolean` | `false` | Show detail legends with current values | | `headerAction` | Optional | `React.ReactNode` | - | Optional action rendered on the right of the card header (e.g. an expand toggle). Passed straight through to [`ChartContainer`](/reference/ui/components/charts/#chartcontainer). Additive - omit it and the card header is unchanged | | `isLoading` | Optional | `boolean` | `false` | Loading state | | `minHeight` | Optional | `string \| number` | `350` | Minimum chart height | | `onTimelineChange` | Optional | `(timeline: string) => void` | - | Callback when timeline changes | | `rawData` | Optional | `unknown` | - | Raw data to be transformed by dataAdapter | | `shouldResetZoom` | Optional | `boolean` | `true` | Whether to reset zoom on timeline change (default: true) | | `timeline` | Optional | `string` | - | Controlled timeline value | | `timelineOptions` | Optional | `TimelineOption[]` | - | Timeline range selector options | | `title` | Optional | `string` | - | Chart title | | `titleExtra` | Optional | `React.ReactNode` | - | Optional node rendered next to the title (e.g. an info tooltip). Passed straight through to [`ChartContainer`](/reference/ui/components/charts/#chartcontainer). Additive | ### `MinMaxAvg` Min / Max / Avg summary row with consistent MDK label and value styling `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/min-max-avg/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/min-max-avg/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `avg` | Optional | `string` | - | Average value (hidden if empty) | | `className` | Optional | `string` | - | Additional root class | | `max` | Optional | `string` | - | Maximum value (hidden if empty) | | `min` | Optional | `string` | - | Minimum value (hidden if empty) | ### `MonthlyEbitdaChart` Bar chart comparing EBITDA across the most recent months for trend visualisation `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/monthly-ebitda-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/ebitda/components/monthly-ebitda-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartData` | Required | `BarChartDataResult` | - | - | | `height` | Optional | `number` | - | - | ### `OperationalHashrateChart` [`Hashrate`](/reference/ui/components/charts/#hashrate) trend card for the operational dashboard. Renders the site hashrate over time (TH/s) with an optional nominal reference line, plus an expand toggle. Purely presentational - pass pre-shaped data from [`useOperationsDashboard`](/reference/ui/hooks/misc/#useoperationsdashboard) `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/hashrate-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/hashrate-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `LineChartCardData` | - | - | | `isExpanded` | Optional | `boolean` | - | - | | `isLoading` | Optional | `boolean` | - | - | | `onToggleExpand` | Optional | `VoidFunction` | - | - | ### `OperationalMinersStatusChart` Miners-status card for the operational dashboard. Renders a stacked daily breakdown of miner states (online / error / offline / sleep / maintenance) with an expand toggle. Purely presentational - pass pre-shaped data from [`useOperationsDashboard`](/reference/ui/hooks/misc/#useoperationsdashboard) `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/miners-status-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/miners-status-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `MinersStatusChartData` | - | - | | `isExpanded` | Optional | `boolean` | - | - | | `isLoading` | Optional | `boolean` | - | - | | `onToggleExpand` | Optional | `VoidFunction` | - | - | ### `OperationalPowerConsumptionChart` Power-consumption trend card for the operational dashboard. Renders site power draw over time (MW) with an optional power-availability reference line, plus an expand toggle. Purely presentational - pass pre-shaped data from [`useOperationsDashboard`](/reference/ui/hooks/misc/#useoperationsdashboard) `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/power-consumption-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/power-consumption-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `LineChartCardData` | - | - | | `isExpanded` | Optional | `boolean` | - | - | | `isLoading` | Optional | `boolean` | - | - | | `onToggleExpand` | Optional | `VoidFunction` | - | - | ### `OperationalSiteEfficiencyChart` Site-efficiency trend card for the operational dashboard. Renders measured site efficiency over time (W/TH/s) with an optional nominal reference line, an info tooltip, and an expand toggle. Purely presentational - pass pre-shaped data from [`useOperationsDashboard`](/reference/ui/hooks/misc/#useoperationsdashboard) `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/site-efficiency-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/dashboard/site-efficiency-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `LineChartCardData` | - | - | | `isExpanded` | Optional | `boolean` | - | - | | `isLoading` | Optional | `boolean` | - | - | | `onToggleExpand` | Optional | `VoidFunction` | - | - | ### `OperationsEnergyChart` Doughnut breakdown of Operations vs Energy cost (in USD totals). Mirrors the OSS [`OperationsEnergyCostChart`](/reference/ui/components/charts/#operationsenergycostchart). Returns the empty-state placeholder when both totals are zero (the OSS chart hides both slices in that case) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/operations-energy-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/operations-energy-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `totals` | Required | `CostSummaryMonetaryTotals \| null` | - | - | | `isLoading` | Optional | `boolean` | - | - | ### `OperationsEnergyCostChart` Doughnut breakdown of Operations vs Energy cost (USD per MWh). Wraps [`ChartContainer`](/reference/ui/components/charts/#chartcontainer) and [`DoughnutChart`](/reference/ui/components/charts/#doughnutchart); pass `operationalCostsUSD` and `energyCostsUSD` via `data` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/operations-energy-cost-chart/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/operations-energy-cost-chart/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Extra class on the container | | `data` | Optional | `Partial<{ energyCostsUSD: number; operationalCostsUSD: number; }>` | - | `operationalCostsUSD` and `energyCostsUSD` | | `emptyMessage` | Optional | `string` | - | Message when both costs are zero or missing | | `height` | Optional | `number` | `200` | Doughnut height in pixels | | `isLoading` | Optional | `boolean` | `false` | Shows loading overlay on the chart area | | `title` | Optional | `string` | `"Operations vs Energy Cost"` | Chart title | | `unit` | Optional | `string` | `$/MWh` | Subtitle and tooltip unit label | ### `PowerModeTimelineChart` Timeline chart for power-mode state changes over time. Wraps [`TimelineChart`](/reference/ui/components/charts/#timelinechart) with mining-specific data shaping `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/power-mode-timeline-chart/power-mode-timeline-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/power-mode-timeline-chart/power-mode-timeline-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `PowerModeTimelineEntry[]` | `[]` | Initial power-mode entries (each with start/end ts + mode) | | `dataUpdates` | Optional | `PowerModeTimelineEntry[]` | `[]` | Streaming updates appended to the initial data | | `isLoading` | Optional | `boolean` | `false` | Show a loading skeleton instead of the chart | | `timezone` | Optional | `string` | `"UTC"` | IANA timezone string for x-axis tick formatting | | `title` | Optional | `string` | `CHART_TITLES.POWER_MODE_TIMELINE` | Chart title | ### `ProductionCostChart` Production cost over time, overlaid with BTC price. Mirrors the OSS `ProductionCostPriceChart` - both series rendered as bars on the same x-axis (bucket labels derived from `dateRange.period`) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/production-cost-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/production-cost-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `btcPriceLog` | Required | `readonly BtcPriceTimeSeriesEntry[]` | - | - | | `costLog` | Required | `readonly CostTimeSeriesEntry[]` | - | - | | `dateRange` | Required | `FinancialDateRange \| null` | - | - | | `isLoading` | Optional | `boolean` | - | - | ### `RevenueChart` Stacked bar chart displaying monthly revenue per site. Automatically switches between BTC and Sats display based on value scale. Receives pre-fetched data as props — no internal data fetching `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/revenue-chart/revenue-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/revenue-chart/revenue-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `RevenueDataItem[]` | `[]` | Raw API response, each entry is one time period with site IDs as dynamic keys | | `isLoading` | Optional | `boolean` | `false` | Shows a loading spinner while data is being fetched | | `legendAlign` | Optional | `"center" \| "start" \| "end"` | `"start"` | Chart legend alignment | | `legendPosition` | Optional | `"left" \| "right" \| "top" \| "bottom"` | `"bottom"` | Chart legend position | | `siteList` | Optional | `(string \| SiteItem)[]` | `[]` | List to resolve site IDs to display names | ### `ThresholdLineChart` Line chart with optional horizontal threshold lines. Wraps [`ChartContainer`](/reference/ui/components/charts/#chartcontainer) and [`LineChart`](/reference/ui/components/charts/#linechart); pass `series` and optional `thresholds` via `data` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/threshold-line-chart/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/threshold-line-chart/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Extra class on the container | | `data` | Optional | `ThresholdLineChartData` | - | `series` points plus optional `thresholds` lines | | `emptyMessage` | Optional | `string` | - | Message when data is missing or all zero | | `height` | Optional | `number` | `280` | Chart height in pixels (`360` when `isTall`) | | `isLegendVisible` | Optional | `boolean` | `true` | Legend with click-to-hide series | | `isTall` | Optional | `boolean` | `false` | When true, uses a taller default height (360px) | | `title` | Optional | `string` | - | Chart title (unit appended when `unit` is set) | | `unit` | Optional | `string` | - | Shown in title and axis/tooltip formatting | | `yTicksFormatter` | Optional | `(value: number) => string` | - | Custom Y-axis tick labels | ### `TimelineChart` Discrete-event timeline chart (e.g. miner state over time) with a category legend. Supports streaming updates via `newData` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/timeline-chart/timeline-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/timeline-chart/timeline-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `initialData` | Required | `TimelineChartData` | - | Initial timeline data | | `axisTitleText` | Optional | `AxisTitleText` | `{ x: "Time", y: "" }` | Axis title strings | | `height` | Optional | `number` | - | Chart pixel height | | `isLoading` | Optional | `boolean` | `false` | Show loader | | `newData` | Optional | `TimelineChartData` | - | Streaming updates appended to the initial data | | `range` | Optional | `ChartRange` | - | Visible time window | | `skipUpdates` | Optional | `boolean` | `false` | Ignore `newData` | | `title` | Optional | `string` | - | Chart title | # Dashboard (/reference/ui/components/dashboard) Components for building dashboard layouts and containers. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `AlarmsBellButton` Top-bar bell button with a three-line severity badge (critical / high / medium). Counts are caller-provided so the button stays domain-agnostic; pair with `useActiveIncidents` or `useSiteMinerCounts` to wire them. `onClick` fires for the bell itself; pass `onSeverityClick` to make each count its own button (severity-filtered deep-link). The two are independent — clicking a severity does not also fire `onClick` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-actions/alarms-bell-button.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-actions/alarms-bell-button.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Additional class names | | `counts` | Optional | `AlarmsBellButtonCounts` | `{}` | Severity-bucketed alarm counts rendered in the stacked badge | | `label` | Optional | `string` | `"Active alarms"` | Accessible label. Defaults to "Active alarms" | | `onClick` | Optional | `((event: React.MouseEvent) => void)` | - | Click handler — typically opens an alerts panel or routes to /alerts | | `onSeverityClick` | Optional | `((severity: AlarmSeverity, event: React.MouseEvent) => void)` | - | Click handler for an individual severity count. When provided, each badge row becomes its own button so an operator can jump straight to the alerts page filtered by that severity (e.g. `/alerts?severity=critical`). When omitted, the counts render as plain (non-interactive) text | ### `DashboardDateRangePicker` Dashboard-friendly wrapper around the core [`DateRangePicker`](/reference/ui/components/forms/#daterangepicker) that speaks `{ start, end }` epoch-millisecond timestamps instead of `Date` objects, so it drops straight into `useDashboardDateRange` from `@tetherto/mdk-react-adapter` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/dashboard-date-range-picker/dashboard-date-range-picker.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/dashboard-date-range-picker/dashboard-date-range-picker.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onChange` | Required | `(next: DashboardDateRange) => void` | - | Fires with the next `{ start, end }` window when the user applies a range | | `value` | Required | `DashboardDateRange` | - | Current range as `{ start, end }` epoch-millisecond timestamps | | `className` | Optional | `string` | - | Optional class hook | | `dateFormat` | Optional | `string` | `"dd/MM/yyyy"` | Display format. Defaults to `dd/MM/yyyy` | | `disabled` | Optional | `boolean` | `false` | Disable the trigger | ### `ExportButton` Split-button trigger for downloading the current dashboard state. The left half labels the action (`↓ Export`); the right half opens a dropdown with the available formats and invokes `onExport(format)` on selection `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/export-button/export-button.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/export-button/export-button.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onExport` | Required | `(format: ExportFormat) => void` | - | Fires with the chosen format when the user picks an item | | `className` | Optional | `string` | - | Optional class hook on the wrapper | | `disabled` | Optional | `boolean` | `false` | Disable the button | | `formats` | Optional | `readonly ExportFormat[]` | `['csv', 'json']` | Formats to offer in the dropdown — defaults to `['csv', 'json']` | | `label` | Optional | `string` | `"Export"` | [`Button`](/reference/ui/components/actions/#button) label — defaults to `'Export'` | ### `HeaderConsumptionBox` Single-row consumption cell for the dashboard's header strip. The `1.663` style numeric is rendered in orange (the warning token) to match the reference app's visual treatment `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-consumption-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-consumption-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Additional class names | | `icon` | Optional | `React.ReactNode` | - | Icon shown next to the stat | | `unit` | Optional | `string` | `MW` | Unit label — defaults to `MW` | | `valueMw` | Optional | `number` | - | Current site-level power consumption, in megawatts | ### `HeaderEfficiencyBox` Single-row efficiency cell for the dashboard's header strip. Displays the W/TH/s metric derived from `power_w / hashrate_th` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-efficiency-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-efficiency-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Additional class names | | `icon` | Optional | `React.ReactNode` | - | Icon shown next to the stat | | `unit` | Optional | `string` | `W/TH/S` | Unit label — defaults to `W/TH/S` | | `valueWthS` | Optional | `number` | - | Efficiency in watts per TH/s | ### `HeaderHashrateBox` Two-row hashrate cell for the dashboard's header strip. Shows the app-side and pool-side aggregate hashrate side by side. Values fall back to `—` when undefined `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-hashrate-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-hashrate-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `appLabel` | Optional | `string` | `WEBAPP_SHORT_NAME ("APP")` | [`Label`](/reference/ui/components/forms/#label) for the app-side row | | `appPhs` | Optional | `number` | - | App-side aggregate hashrate in PH/s | | `className` | Optional | `string` | - | Additional class names | | `fractionDigits` | Optional | `number` | `3` | Decimal places shown for both values — defaults to `3` | | `icon` | Optional | `React.ReactNode` | - | Icon shown next to the stat | | `poolPhs` | Optional | `number` | - | Pool-side aggregate hashrate in PH/s | | `unit` | Optional | `string` | `PH/s` | [`Hashrate`](/reference/ui/components/charts/#hashrate) unit label — defaults to `PH/s` | ### `HeaderMinersBox` Two-row miner-count cell for the dashboard's header strip. Top row carries the app-side `online / error / offline` breakdown; the bottom row shows the pool-side equivalent. Numbers fall back to `—` when undefined `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-miners-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-miners-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `appLabel` | Optional | `string` | `WEBAPP_SHORT_NAME ("APP")` | [`Label`](/reference/ui/components/forms/#label) for the app-side row | | `appTotal` | Optional | `number` | - | Optional app-side meta line — total miners reporting to the app | | `className` | Optional | `string` | - | Additional class names | | `error` | Optional | `number` | - | Miners flagged in warning (the small amber count) | | `icon` | Optional | `React.ReactNode` | - | Icon shown next to the "Miners" label. Caller-provided so the package stays icon-agnostic | | `offline` | Optional | `number` | - | Miners offline (the small red count) | | `online` | Optional | `number` | - | Online miners (the `158` numerator) | | `poolMismatch` | Optional | `number` | - | Optional pool-side mismatch count (red) | | `poolOnline` | Optional | `number` | - | Optional pool-side online count (green) | | `poolTotal` | Optional | `number` | - | Optional pool-side meta — total miners as reported by upstream pools | | `total` | Optional | `number` | - | Total miners across the site (denominator of the `158 / 2,188` ratio) | ### `HeaderStatsBar` Horizontal flex strip that hosts the dashboard's stat boxes ([`HeaderMinersBox`](/reference/ui/components/dashboard/#headerminersbox), [`HeaderHashrateBox`](/reference/ui/components/dashboard/#headerhashratebox), [`HeaderConsumptionBox`](/reference/ui/components/dashboard/#headerconsumptionbox), [`HeaderEfficiencyBox`](/reference/ui/components/dashboard/#headerefficiencybox)). Lives inside [``](/reference/ui/components/navigation/#appheader) as the middle slot. Slot-based: the caller decides which boxes to render and in which order. The bar interleaves an angled chevron divider between adjacent children to match the reference app visual treatment `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-stats-bar.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-stats/header-stats-bar.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Required | `React.ReactNode` | - | Stat boxes to render in order, left-to-right | | `className` | Optional | `string` | - | Optional class hook | ### `ProfileMenu` Top-bar profile dropdown. Wraps the core DropdownMenu primitive with the user-avatar icon as the trigger. Items are caller-provided so the menu surface stays application-driven `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-actions/profile-menu.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/header-actions/profile-menu.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `items` | Required | `ProfileMenuItem[]` | - | Items rendered in the dropdown, top-to-bottom | | `className` | Optional | `string` | - | Additional class names | | `icon` | Optional | `React.ReactNode` | `` | Override the trigger icon — defaults to the user-avatar icon | | `label` | Optional | `string` | `"Profile menu"` | Accessible label for the trigger button | | `user` | Optional | `React.ReactNode` | - | Optional user label rendered at the top of the dropdown (e.g. an email) | ### `SiteStatsBar` Site-level summary strip composed from [`WidgetTopRow`](/reference/ui/components/widgets/#widgettoprow) (title + power) and [`GenericDataBox`](/reference/ui/components/widgets/#genericdatabox) (hashrate / miner-count / container-count). Designed to sit at the top of a dashboard page above the chart cards `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/site-stats-bar/site-stats-bar.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/site-stats-bar/site-stats-bar.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `title` | Required | `string` | - | Site label rendered in the header row | | `className` | Optional | `string` | - | Optional class hook | | `containerCount` | Optional | `number` | - | Total container count across the site | | `hashrateUnit` | Optional | `string` | `"TH/s"` | [`Hashrate`](/reference/ui/components/charts/#hashrate) display unit — defaults to `TH/s` | | `isLoading` | Optional | `boolean` | `false` | Render a skeleton bar while data is loading | | `minerCount` | Optional | `number` | - | Total miner count across the site | | `power` | Optional | `number` | - | Current site-level power consumption, in watts (or whatever `powerUnit` says) | | `powerUnit` | Optional | `string` | `"kW"` | Display unit for `power` — defaults to `kW` | | `totalHashrate` | Optional | `number` | - | Aggregate hashrate, in TH/s | ### `TimelineSelector` Dropdown for picking the dashboard time range. Wraps `core/Select` and the canonical option list from `getTimelineOptions`. Pair with the `useDashboardTimeRange` hook in `@tetherto/mdk-react-adapter` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/timeline-selector/timeline-selector.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/dashboard/timeline-selector/timeline-selector.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onChange` | Required | `(next: string) => void` | - | Called whenever the user picks a new option | | `value` | Required | `string` | - | Currently selected timeline value (e.g. `'1m'`, `'5m'`) | | `className` | Optional | `string` | - | Tailwind/BEM class hook on the trigger | | `label` | Optional | `string` | `"Time range"` | ARIA label / placeholder for the trigger | | `options` | Optional | `TimelineOption[]` | `getTimelineOptions()` | Available options — defaults to `getTimelineOptions`. Pass a custom list to localise labels or restrict the range | # Dashboard compositions (/reference/ui/components/dashboards) Pre-composed dashboard layouts and templates. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ActionsSidebar` Full-height side panel for the reference app voting/approval workflow. Three sections (only rendered when non-empty): - Draft — locally-staged actions not yet sent to the server. - In review — actions this user submitted, awaiting votes. - Requested — other users' voting actions this user can approve/reject (only shown when the current token has `actions:w`). Open/close state is driven by `actionsStore.sidebarOpen` so the header [`PendingActionsButton`](/reference/ui/components/dashboards/#pendingactionsbutton) and any in-page code can open it without prop-drilling. Mount this once at the app root — it renders nothing when closed `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/pool-manager/actions-sidebar/actions-sidebar.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/pool-manager/actions-sidebar/actions-sidebar.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Extra class names merged onto the sidebar root element | ### `Cost` [`Cost`](/reference/ui/components/dashboards/#cost) Summary - composite reporting page (single-site). Reads cost-summary view model fields (from [`useCostSummary`](/reference/ui/hooks/utility/#usecostsummary)) and renders: - page header with "[`Cost`](/reference/ui/components/dashboards/#cost) Summary" title and an optional action slot (`setCostAction`) pinned to the opposite edge - period selector slot (`controls`) - pass [``](/reference/ui/components/filters/#timeframecontrols) for the OSS-style Year/Month picker or any other date selector element - shared [`CostContent`](/reference/ui/components/dashboards/#costcontent) 2x2 grid (charts + metric tiles) Multi-site is intentionally out of scope for this extraction wave `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/cost.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/cost.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `btcPriceLog` | Required | `readonly BtcPriceTimeSeriesEntry[]` | - | BTC price time series aligned to `costLog` buckets | | `controls` | Required | `React.ReactElement>` | - | Period selector element. Pass [``](/reference/ui/components/filters/#timeframecontrols) for the OSS-style year/month picker | | `costLog` | Required | `readonly CostTimeSeriesEntry[]` | - | Monthly/weekly production-cost time series for the Production [`Cost`](/reference/ui/components/dashboards/#cost) / Price chart | | `dateRange` | Required | `FinancialDateRange \| null` | - | Active date range; drives x-axis labels across all charts | | `metrics` | Required | `CostSummaryDisplayMetrics \| null` | - | Headline $/MWh tiles (all-in, energy, operations). Pass `null` while loading | | `totals` | Required | `CostSummaryMonetaryTotals \| null` | - | Period totals (energy + operations USD) for the Operations vs Energy doughnut | | `avgAllInCostData` | Optional | `readonly AvgAllInCostDataPoint[]` | - | Optional revenue/cost time-series for the Avg All-in [`Cost`](/reference/ui/components/dashboards/#cost) panel | | `error` | Optional | `unknown` | - | When truthy, renders an error message in place of the chart grid | | `isLoading` | Optional | `boolean` | `false` | Shows a loading spinner overlay over the chart grid | | `setCostAction` | Optional | `React.ReactElement>` | - | Optional "Set Monthly [`Cost`](/reference/ui/components/dashboards/#cost)" header action slot. A `ReactElement` slot (rather than an href string) so consumers can hand in router-aware components like `` or ` setIsOpen(false)} partTypes={PART_TYPES} defaultPartTypeId={activePartType} modelOptions={modelOptions} minerModelOptions={MINER_MODEL_OPTIONS} statusOptions={STATUS_OPTIONS} locationOptions={LOCATION_OPTIONS} isControllerPartTypeSelected={isController} onPartTypeChange={(id) => setActivePartType(id)} onSubmit={async () => { setIsOpen(false); }} /> ); }; ``` #### Related API - [`SparePartSubTypesModal`](/reference/ui/components/dialogs/#sparepartsubtypesmodal) @tetherto/mdk-react-devkit ### Manage spare part subtypes ```tsx ``` Modal for viewing and adding spare part subtypes (part models) per part type. Presents a part-type tab strip, a table of existing subtypes for the active type, and an inline add form. #### When to use Use this to manage the list of allowed part models for each part type. It can be opened standalone or embedded from `AddSparePartModal`'s "View Subtypes" button so users can add a missing model without losing their in-progress form. #### Notes - The active part type is controlled by the parent: change `activePartTypeId` and supply the matching `subTypes` in `onPartTypeChange` - The add form validates a non-empty name and clears on successful add #### Example [#spare-part-sub-types-modal-example] ```tsx const PART_TYPES = [ { value: "inventory-miner_part-controller", label: "Controller" }, { value: "inventory-miner_part-psu", label: "PSU" }, { value: "inventory-miner_part-hashboard", label: "Hashboard" }, ]; const INITIAL_SUB_TYPES: Record = { "inventory-miner_part-controller": ["CT-S19", "CT-S19j"], "inventory-miner_part-psu": ["PSU-3000W"], "inventory-miner_part-hashboard": ["HB-S19", "HB-S19j", "HB-S19XP"], }; const [isOpen, setIsOpen] = useState(false); const [activeId, setActiveId] = useState(PART_TYPES[0]?.value ?? ""); const [subTypesMap, setSubTypesMap] = useState(INITIAL_SUB_TYPES); const handleAddSubType = async (name: string): Promise<{ error: string } | void> => { const existing = subTypesMap[activeId] ?? []; if (existing.includes(name)) return { error: "Subtype already exists" }; setSubTypesMap((prev) => ({ ...prev, [activeId]: [...existing, name] })); }; return (
setIsOpen(false)} partTypes={PART_TYPES} activePartTypeId={activeId} onPartTypeChange={setActiveId} subTypes={subTypesMap[activeId] ?? []} onAddSubType={handleAddSubType} />
); }; ``` #### Related API - [`AddSparePartModal`](/reference/ui/components/dialogs/#addsparepartmodal) @tetherto/mdk-react-devkit ### Bulk-add spare parts ```tsx ``` Modal for bulk-adding spare parts from a CSV file. Provides a CSV template download, file selection with client-side parsing, and submits the parsed records. CSV parsing and validation helpers (`parseCsvText`, `validateCSVRecords`, `mapRawRowToRecord`, `downloadCsvTemplate`, `CSVRecord`) are exported alongside the component for use in the consuming submit handler. #### When to use Use this when operators need to register many spare parts at once. Validate the parsed records in your `onSubmit` with `validateCSVRecords` (location/status/model checks, duplicate detection) and return an `{ error }` to surface a message in the modal. #### CSV format Template headers (downloadable from the modal): `part, model, miner model, serial num, mac, status, location, comment`. Max `MAX_CSV_ITEMS` (50) rows per upload. `validateCSVRecords` enforces valid part types, miner models, statuses, locations, per-part-type model subtypes, and duplicate serial/MAC detection (the latter only for controllers). #### Example [#bulk-add-spare-parts-modal-example] ```tsx const [isOpen, setIsOpen] = useState(false); return (
setIsOpen(false)} onSubmit={async () => { setIsOpen(false); }} />
); }; ``` @tetherto/mdk-react-devkit ### Move a spare part ```tsx ``` Two-step modal for moving a single spare part. Step one shows the part details (`SparePartDetails`) alongside its current location and status, and lets the user pick a new location, status, and an observation. Step two previews the before → after transition with color-coded badges for confirmation before submitting. #### When to use Use this from a spare-parts inventory row action when an operator moves one part and you want an explicit confirm step showing exactly what changes. For moving many parts at once, use `BatchMoveSparePartsModal` instead. #### Data shape ```ts const sparePart: MoveSparePartModalSparePart = { id: 'sp-001', code: 'CB-AM-CB5_V10-01', // shown via SparePartDetails type: 'CB5_V10', site: 'Site A', serialNum: 'test-miner', macAddress: 'aa:bb:cc:dd:ee:ff', location: 'site.warehouse', // dot-separated location key status: 'ok_repaired', // spare part status key } ``` #### Label & color resolution - Location/status labels are resolved from the passed option lists (`getOptionLabel`) - The current/new badges are colored from `SPARE_PART_LOCATION_BG_COLORS` / `SPARE_PART_STATUS_BG_COLORS`; an unknown location key renders with no background - The footer shows "No Changes made" until the target location or status differs from the current values, at which point "Save Changes" advances to the confirmation step #### Example [#move-spare-part-modal-example] ```tsx Button, MoveSparePartModal, SPARE_PART_LOCATION_LABELS, SPARE_PART_LOCATIONS, SPARE_PART_STATUS_NAMES, SPARE_PART_STATUSES, } from "@tetherto/mdk-react-devkit"; const locationOptions = Object.values(SPARE_PART_LOCATIONS) .filter((value) => value !== SPARE_PART_LOCATIONS.SITE_CONTAINER) .map((value) => ({ value, label: SPARE_PART_LOCATION_LABELS[value] ?? value })); const statusOptions = Object.values(SPARE_PART_STATUSES).map((value) => ({ value, label: SPARE_PART_STATUS_NAMES[value as keyof typeof SPARE_PART_STATUS_NAMES] ?? value, })); const mockSparePart = { id: "sp-001", code: "HB-A001", type: "HB-S19", site: "Site A", serialNum: "SN123456", location: SPARE_PART_LOCATIONS.SITE_WAREHOUSE, status: SPARE_PART_STATUSES.OK_BRAND_NEW, }; const [isOpen, setIsOpen] = useState(false); return (
setIsOpen(false)} sparePart={mockSparePart} locationOptions={locationOptions} statusOptions={statusOptions} onSubmit={async () => { setIsOpen(false); }} />
); }; ``` #### Related API - [`BatchMoveSparePartsModal`](/reference/ui/components/dialogs/#batchmovesparepartsmodal) @tetherto/mdk-react-devkit ### Batch-move spare parts ```tsx ``` Modal for moving multiple spare parts at once. Shows the selected parts in a table (code, current location, current status) and lets the user choose a new location and/or status plus an observation, applied to every selected part in one submit. #### When to use Use this when an operator multi-selects spare-part rows and wants to relocate or re-status them together. At least one of location or status must be chosen. For a single part with a confirm step, use `MoveSparePartModal`. #### Data shape ```ts const spareParts: BatchMoveSparePart[] = [ { id: 'sp-001', code: 'HB-A001', location: 'site.warehouse', status: 'ok_brand_new' }, { id: 'sp-002', code: 'HB-A002', location: 'workshop.lab', status: 'faulty' }, ] ``` #### Notes - The form validates that either a location or a status is selected before submit - Table location/status cells are resolved to display labels from the passed option lists #### Example [#batch-move-spare-parts-modal-example] ```tsx BatchMoveSparePartsModal, Button, SPARE_PART_LOCATION_LABELS, SPARE_PART_LOCATIONS, SPARE_PART_STATUS_NAMES, SPARE_PART_STATUSES, } from "@tetherto/mdk-react-devkit"; const locationOptions = Object.values(SPARE_PART_LOCATIONS) .filter((value) => value !== SPARE_PART_LOCATIONS.SITE_CONTAINER) .map((value) => ({ value, label: SPARE_PART_LOCATION_LABELS[value] ?? value })); const statusOptions = Object.values(SPARE_PART_STATUSES).map((value) => ({ value, label: SPARE_PART_STATUS_NAMES[value as keyof typeof SPARE_PART_STATUS_NAMES] ?? value, })); const mockSpareParts = [ { id: "sp-001", code: "HB-A001", location: SPARE_PART_LOCATIONS.SITE_WAREHOUSE, status: SPARE_PART_STATUSES.OK_BRAND_NEW }, { id: "sp-002", code: "HB-A002", location: SPARE_PART_LOCATIONS.WORKSHOP_LAB, status: SPARE_PART_STATUSES.FAULTY }, { id: "sp-003", code: "CB-B001", location: SPARE_PART_LOCATIONS.SITE_WAREHOUSE, status: SPARE_PART_STATUSES.OK_RECOVERED }, ]; const [isOpen, setIsOpen] = useState(false); return (
setIsOpen(false)} spareParts={mockSpareParts} locationOptions={locationOptions} statusOptions={statusOptions} onSubmit={async () => { setIsOpen(false); }} />
); }; ``` #### Related API - [`MoveSparePartModal`](/reference/ui/components/dialogs/#movesparepartmodal) @tetherto/mdk-react-devkit ### View a device movement ```tsx ``` Modal that shows the details of a single historical device movement: a device summary (code, model, site, container, serial number, MAC) and the origin → destination transition of both location and status, with color-coded badges. #### When to use Use this in an inventory "Historical Movements" view when a user selects a movement row and you want to show the full before/after detail of where a device moved and how its status changed. #### Data shape ```ts const movement: MovementData = { origin: 'site.warehouse', // dot-separated location key destination: 'workshop.lab', previousStatus: 'ok_brand_new', // miner status key newStatus: 'faulty', device: { // raw device record (miner / spare part) code: 'M-123', tags: ['code-M-123'], type: 'antminer', info: { site: 'Site A', container: 'C1', serialNum: 'SN-9', macAddress: 'AA:BB' }, }, comments: 'Moved for repair', // optional ReactNode } ``` #### Label & color resolution The component renders data only — all resolution happens in `buildMovementDetailsViewModel`: - Location labels come from `getLocationLabel` (`'site.warehouse'` → `Site Warehouse`) - Location/status badge colors come from `MINER_LOCATION_` / `MINER_STATUS_` constants, falling back to a neutral border when a key is unknown - Status labels come from `MINER_STATUS_NAMES` (`'ok_brand_new'` → `Brand New`) - The device `code` is resolved with `getMinerShortCode`, and `model` falls back from `info.subType` → `type` → `-` #### Example [#movement-details-modal-example] ```tsx /** * Runnable example for MovementDetailsModal. / const exampleMovement: MovementData = { origin: 'site.warehouse', destination: 'workshop.lab', previousStatus: 'ok_brand_new', newStatus: 'faulty', device: { code: 'M-1042', tags: ['code-M-1042'], type: 'antminer', info: { site: 'Site A', container: 'C-12', serialNum: 'SN-9981', macAddress: 'AA:BB:CC:DD:EE:FF', }, }, comments: 'Moved to workshop lab for diagnostics.', }
{ console.warn('modal closed') }} />
) ``` @tetherto/mdk-react-devkit ### Delete a spare part ```tsx ``` Confirmation modal for deleting a spare part. Warns that the action is irreversible and surfaces the part code so the user can verify before confirming. #### When to use Use this as the confirm step for a destructive "Delete" row action in a spare-parts inventory view. #### Example [#confirm-delete-spare-part-modal-example] ```tsx const [isOpen, setIsOpen] = useState(false); return (
setIsOpen(false)} onConfirm={async () => setIsOpen(false)} sparePart={{ id: "sp-001", code: "HB-A001" }} />
); }; ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `AddSparePartModal` Modal for registering a new spare part. Presents a part-type tab strip and a form for miner model, part model, serial number, MAC address (controllers only), status, location, tags, and a comment. Validation is controller-aware: controllers require a MAC address, other parts require a serial number. Receives option lists and the submit handler as props `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/add-spare-part-modal/add-spare-part-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/add-spare-part-modal/add-spare-part-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isOpen` | Required | `boolean` | - | Whether the modal is open | | `locationOptions` | Required | `FormSelectOption[]` | - | Location options | | `minerModelOptions` | Required | `FormSelectOption[]` | - | Parent miner model options | | `modelOptions` | Required | `FormSelectOption[]` | - | Part model options for the active part type | | `onClose` | Required | `VoidFunction` | - | Called when the modal requests to close | | `onPartTypeChange` | Required | `(partTypeId: string) => void` | - | Called when the active part type changes (refetch model options here) | | `onSubmit` | Required | `(values: AddSparePartFormValues) => Promise` | - | Submit handler; return `fieldErrors` to surface server-side validation | | `partTypes` | Required | `SparePartSubTypesModalPartType[]` | - | Part-type tabs | | `statusOptions` | Required | `FormSelectOption[]` | - | Status options | | `defaultPartTypeId` | Optional | `string` | - | Initially selected part type | | `isControllerPartTypeSelected` | Optional | `boolean` | - | When true, the MAC address field is shown and required | | `isLoading` | Optional | `boolean` | - | Renders a loader instead of the form | | `isModelOptionsLoading` | Optional | `boolean` | - | Disables the model select while options load | | `isSubTypesLoading` | Optional | `boolean` | - | Loading state for the embedded subtypes modal | | `onAddSubType` | Optional | `((name: string) => Promise)` | - | Add handler for the embedded subtypes modal; return `{ error }` to surface a field error | | `onSubTypesPartTypeChange` | Optional | `((id: string) => void)` | - | Called when the active tab changes in the embedded subtypes modal | | `subTypes` | Optional | `string[]` | - | Subtype names for the active part type in the embedded modal | | `subTypesActivePartTypeId` | Optional | `string` | - | Active part type for the embedded subtypes modal | | `subTypesPartTypes` | Optional | `SparePartSubTypesModalPartType[]` | - | Part types for the embedded "View Subtypes" modal | ### `AlertDialogAction` Primary confirmation button inside an ``; clicking dismisses the dialog and runs the action handler `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx)
### `AlertDialogCancel` Secondary dismiss button inside an ``; closes the dialog without invoking the destructive action `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx)
### `AlertDialogContent` Modal content surface for an `` — renders the centered panel above the overlay with focus trap `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx)
### `AlertDialogDescription` Supporting body text inside an ``; conveys the consequences of the action being confirmed `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx)
### `AlertDialogFooter` Right-aligned action row inside an `` — hosts the cancel and confirm buttons `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx)
### `AlertDialogHeader` Top section of an `` that groups the title and description above the action row `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx)
### `AlertDialogOverlay` Full-viewport scrim rendered behind an `` to block interaction with the page `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx)
### `AlertDialogTitle` Prominent title text inside an `` summarising the action that requires confirmation `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert-dialog/index.tsx)
### `AssignPoolModal` Modal dialog for bulk-assigning a set of selected miners to a pool config. Displays the miner list, a pool selector with metadata (unit/miner counts, last-updated time), an endpoints preview, and an optional credential template preview. Submission is async; the modal stays open with a loading state until the parent resolves `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/pool-manager/assign-pool-modal/assign-pool-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/pool-manager/assign-pool-modal/assign-pool-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isOpen` | Required | `boolean` | - | Controls modal visibility | | `miners` | Required | `Device[]` | - | Miners to display in the selection table | | `onClose` | Required | `() => void` | - | Called when the modal is dismissed (× button or backdrop) | | `onSubmit` | Required | `(values: { pool: PoolSummary; }) => Promise` | - | Called with the selected pool when the form is submitted | | `poolConfig` | Required | `PoolConfigEntry[]` | - | Available pool configurations to populate the pool selector | ### `BatchMoveSparePartsModal` Modal for moving multiple spare parts at once. Shows the selected parts in a table and lets the user choose a new location and/or status plus an observation, applied to every part. Receives the parts, option lists, and submit handler as props `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/batch-move-spare-parts-modal/batch-move-spare-parts-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/batch-move-spare-parts-modal/batch-move-spare-parts-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isOpen` | Required | `boolean` | - | Whether the modal is open | | `locationOptions` | Required | `FormSelectOption[]` | - | New-location options | | `onClose` | Required | `VoidFunction` | - | Called when the modal requests to close | | `onSubmit` | Required | `(values: { location: string \| null; status: string \| null; observation: string \| null; }) => void \| Promise` | - | Submit handler; unselected fields are `null` | | `spareParts` | Required | `BatchMoveSparePart[]` | - | The parts to move, rendered in the table | | `statusOptions` | Required | `FormSelectOption[]` | - | New-status options | ### `BulkAddSparePartsModal` Modal for bulk-adding spare parts from a CSV file. Provides a CSV template download, file selection with client-side parsing, and submits the parsed records. Receives the submit handler as a prop; CSV parsing and validation helpers are exported alongside the component `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/bulk-add-spare-parts-modal/bulk-add-spare-parts-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/bulk-add-spare-parts-modal/bulk-add-spare-parts-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isOpen` | Required | `boolean` | - | Whether the modal is open | | `onClose` | Required | `VoidFunction` | - | Called when the modal requests to close | | `onSubmit` | Required | `(records: CSVRecord[]) => Promise` | - | Submit handler; return `{ error }` to show an inline error | | `isLoading` | Optional | `boolean` | - | Renders a loader instead of the form | ### `ConfirmDeleteSparePartModal` Confirmation modal for deleting a spare part. Warns that the action is irreversible and surfaces the part code so the user can verify before confirming. Receives the part and confirm handler as props `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/confirm-delete-spare-part-modal/confirm-delete-spare-part-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/confirm-delete-spare-part-modal/confirm-delete-spare-part-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isLoading` | Optional | `boolean` | - | Disables the action buttons while the delete is in flight | | `isOpen` | Optional | `boolean` | - | Whether the modal is open | | `onClose` | Optional | `VoidFunction` | - | Called when the modal requests to close | | `onConfirm` | Optional | `((sparePart: ConfirmDeleteSparePartModalSparePart) => void \| Promise)` | - | Called with the part when the user confirms | | `sparePart` | Optional | `ConfirmDeleteSparePartModalSparePart` | - | The part to delete; when omitted the modal renders nothing | ### `DialogContent` Centered modal surface for a `` — renders above the overlay with focus trap and Escape-to-close `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `bare` | Optional | `boolean` | `false` | Applies `mdk-dialogheader--bare` to the header | | `closable` | Optional | `boolean` | - | Shows an ✕ close button in the header | | `closeOnClickOutside` | Optional | `boolean` | `true` | Whether clicking the overlay closes the dialog | | `closeOnEscape` | Optional | `boolean` | `true` | Whether pressing Escape closes the dialog | | `description` | Optional | `string` | - | Renders [`DialogDescription`](/reference/ui/components/dialogs/#dialogdescription) below the title | | `onClose` | Optional | `VoidFunction` | - | Fired when the ✕ button is clicked | | `title` | Optional | `string` | - | Renders [`DialogTitle`](/reference/ui/components/dialogs/#dialogtitle) (and optional [`DialogDescription`](/reference/ui/components/dialogs/#dialogdescription)) inside the header | ### `DialogDescription` Supporting body copy inside a `` rendered below the title `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx)
### `DialogFooter` Action row at the bottom of a `` — typically primary/secondary buttons `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx)
### `DialogHeader` Top region of a `` that groups the title and description `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `bare` | Optional | `boolean` | `false` | Applies `mdk-dialogheader--bare` to the header | | `closable` | Optional | `boolean` | - | Shows an ✕ close button in the header | | `onClose` | Optional | `VoidFunction` | - | Fired when the ✕ button is clicked | ### `DialogOverlay` Full-viewport scrim rendered behind an open `` to block background interaction `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx)
### `DialogTitle` Prominent title text at the top of a `` summarising the modal's purpose `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/dialog/index.tsx)
### `MovementDetailsModal` Modal showing the details of a historical device movement — the device summary plus the origin → destination transition of location and status. Receives the selected movement as a prop — no internal data fetching `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/movement-details-modal/movement-details-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/movement-details-modal/movement-details-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isOpen` | Optional | `boolean` | `false` | Whether the modal is open | | `movement` | Optional | `MovementData` | - | The selected movement; when omitted the modal renders nothing | | `onClose` | Optional | `() => void` | - | Called when the modal requests to close (overlay click, escape, or close button) | ### `MoveSparePartModal` Two-step modal for moving a single spare part. Step one shows the part details with its current location and status and lets the user pick a new location, status, and observation; step two previews the before → after transition for confirmation. Receives the part, option lists, and submit handler as props `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/move-spare-part-modal/move-spare-part-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/move-spare-part-modal/move-spare-part-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `locationOptions` | Required | `FormSelectOption[]` | - | Location options | | `onSubmit` | Required | `(values: { location: string; status: string; observation: string; }, sparePart: MoveSparePartModalSparePart) => void \| Promise` | - | Submit handler with the new `{ location, status, observation }` and the original part | | `statusOptions` | Required | `FormSelectOption[]` | - | Status options | | `isOpen` | Optional | `boolean` | - | Whether the modal is open | | `onClose` | Optional | `VoidFunction` | - | Called when the modal requests to close | | `requestedValues` | Optional | `{ location?: string \| undefined; status?: string \| undefined; }` | - | Pre-seeds the target location/status | | `sparePart` | Optional | `MoveSparePartModalSparePart` | - | The part to move; when omitted the modal renders nothing | ### `SparePartSubTypesModal` Modal for viewing and adding spare part subtypes per part type. Presents a part-type tab strip, a table of existing subtypes for the active type, and an inline add form. Receives the active part type, subtype list, and add handler as props `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/spare-part-sub-types-modal/spare-part-sub-types-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/spare-part-sub-types-modal/spare-part-sub-types-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `activePartTypeId` | Required | `string` | - | The selected part type (controlled by the parent) | | `isOpen` | Required | `boolean` | - | Whether the modal is open | | `onAddSubType` | Required | `(name: string) => Promise` | - | Add handler; return `{ error }` to surface a field error | | `onClose` | Required | `VoidFunction` | - | Called when the modal requests to close | | `onPartTypeChange` | Required | `(id: string) => void` | - | Called when the active tab changes (fetch that type's subtypes here) | | `partTypes` | Required | `SparePartSubTypesModalPartType[]` | - | Part-type tabs | | `subTypes` | Required | `string[]` | - | Subtype names for the active part type | | `isLoading` | Optional | `boolean` | - | Renders a loader instead of the body | # Display (/reference/ui/components/display) Components for displaying and formatting data. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `Avatar` Circular avatar surface that shows a profile image with a graceful text fallback when the image fails to load `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/avatar/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/avatar/index.tsx)
### `AvatarFallback` Initials or icon placeholder shown inside [``](/reference/ui/components/display/#avatar) while the image loads or when no image is available `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/avatar/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/avatar/index.tsx)
### `AvatarImage` Profile image slot inside [``](/reference/ui/components/display/#avatar) — renders `src` and triggers the fallback on load failure `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/avatar/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/avatar/index.tsx)
### `Badge` [`Badge`](/reference/ui/components/display/#badge) component - Display badge with number or dot `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/badge/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/badge/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Optional | `React.ReactNode` | - | [`Badge`](/reference/ui/components/display/#badge) content (wraps children with badge) | | `className` | Optional | `string` | - | Custom className for badge | | `color` | Optional | `"success" \| "info" \| "warning" \| "error" \| "primary" \| "secondary" \| "default"` | `"primary"` | Color variant | | `count` | Optional | `number` | `0` | Number to display in badge If > overflowCount, will show "overflowCount+" | | `dot` | Optional | `boolean` | `false` | Show badge as a dot | | `offset` | Optional | `[number, number]` | `[0, 0]` | Offset position [x, y] in pixels | | `overflowCount` | Optional | `number` | `99` | Maximum count to display | | `showZero` | Optional | `boolean` | `false` | Whether to show badge when count is 0 | | `size` | Optional | `"sm" \| "md" \| "lg"` | `"md"` | [`Badge`](/reference/ui/components/display/#badge) size | | `square` | Optional | `boolean` | `false` | Square badge (no border-radius) | | `status` | Optional | `"success" \| "warning" \| "error" \| "default" \| "processing"` | - | Status badge (small dot badge with text) | | `text` | Optional | `string` | - | Custom badge content (overrides count) | | `title` | Optional | `string` | - | [`Badge`](/reference/ui/components/display/#badge) title for accessibility | | `wrapperClassName` | Optional | `string` | - | Custom className for wrapper | ### `BtcAveragePrice` Read-only BTC average price label for reporting toolbars `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/btc-average-price/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/btc-average-price/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `label` | Optional | `string` | `"BTC Average Price"` | [`Label`](/reference/ui/components/forms/#label) for the BTC average price | | `price` | Optional | `number \| null` | - | BTC price in USD; formatted with grouping and no decimal places. When `null`, `undefined`, non-finite, or negative, the value shows `-` (`FALLBACK` from format utils) | ### `DataLabel` Read-only period label (`PERIOD: start - end`) with timezone-aware dates `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/data-label/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/data-label/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `endDate` | Optional | `Date \| null` | - | Range end; formatted in the active timezone (`dd/MM/yy`) | | `label` | Optional | `string` | `"PERIOD"` | [`Label`](/reference/ui/components/forms/#label) text; defaults to `PERIOD` | | `startDate` | Optional | `Date \| null` | - | Range start; formatted in the active timezone (`dd/MM/yy`) | ### `Indicator` [`Indicator`](/reference/ui/components/display/#indicator) component - display status with colored background and label `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/indicator/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/indicator/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Optional | `React.ReactNode` | - | Children content (can include text, icons, multiple elements) | | `className` | Optional | `string` | - | Custom className for the root element | | `color` | Optional | `"red" \| "gray" \| "blue" \| "yellow" \| "green" \| "purple" \| "amber" \| "slate"` | `"gray"` | Color variant of the indicator | | `onClick` | Optional | `(VoidFunction & React.MouseEventHandler)` | - | Click handler | | `size` | Optional | `"sm" \| "md" \| "lg"` | `"md"` | Size variant of the indicator | | `vertical` | Optional | `boolean` | `false` | When true, adds extra spacing between child elements and stacks them vertically. Useful for displaying multiple pieces of information (e.g. status + count) in a clear way | ### `Tag` [`Tag`](/reference/ui/components/display/#tag) component - display labels, categories, or status `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/tag/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/tag/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Optional | `React.ReactNode` | - | Children content | | `className` | Optional | `string` | - | Custom className for the root element | | `color` | Optional | `"red" \| "blue" \| "green" \| "amber" \| "dark"` | `"dark"` | Color variant of the tag | ### `Typography` [`Typography`](/reference/ui/components/display/#typography) component for consistent text styling `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/typography/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/typography/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `align` | Optional | `"center" \| "left" \| "right" \| "justify"` | - | Text alignment | | `className` | Optional | `string` | - | Custom className | | `color` | Optional | `"success" \| "warning" \| "error" \| "primary" \| "default" \| "muted"` | `"default"` | Token-based text color | | `size` | Optional | `"sm" \| "md" \| "lg" \| "xs" \| "xl" \| "2xl" \| "3xl" \| "4xl"` | - | Text size; defaults to the variant's size when unset | | `truncate` | Optional | `boolean` | `false` | Truncate text with ellipsis | | `variant` | Optional | `"body" \| "caption" \| "secondary" \| "heading1" \| "heading2" \| "heading3"` | `"body"` | Determines the rendered HTML element and base style | | `weight` | Optional | `"medium" \| "normal" \| "light" \| "semibold" \| "bold"` | - | Font weight; defaults to the variant's weight when unset | # Feature (/reference/ui/components/features) Composite components for specific application features. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ContainerDetail` Container detail page shell: a back link, the container name, and a per-model tab strip. Purely presentational — the page resolves the tab list (via the foundation tab matrix), owns the active tab / routing, and supplies the tab body as `children`. This is the frame every container detail tab mounts into `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/container-detail/container-detail.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/container-detail/container-detail.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `activeTab` | Required | `string` | - | Currently active tab key | | `onBack` | Required | `() => void` | - | Fired when the back link is clicked (the page decides where to go) | | `onTabChange` | Required | `(tab: string) => void` | - | Fired with the next tab key when the operator switches tabs | | `tabs` | Required | `ContainerDetailTab[]` | - | Ordered tabs for this container model (already resolved by the page) | | `backLabel` | Optional | `React.ReactNode` | `"Explorer"` | Back-link label. Defaults to "Explorer" | | `children` | Optional | `React.ReactNode` | - | The active tab's body — supplied by the page (real content or a placeholder) | | `className` | Optional | `string` | - | Additional class for the root element | | `name` | Optional | `React.ReactNode` | - | Container display name shown in the header. Optional — omit it when the host already renders the container name as the page title (e.g. the shell's `PageLayout`), so the name is not shown twice | ### `ContainerWidgets` Site Overview → Container Widgets: the read-only grid of per-container summary cards. Purely presentational — the shell page feeds it the shaped `containers` array (from the container-widgets data hook) and handles navigation via `onContainerClick` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/site-overview/container-widgets/container-widgets.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/site-overview/container-widgets/container-widgets.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `containers` | Required | `ContainerWidgetItem[]` | - | Card-ready data for every container, shaped by the data hook | | `className` | Optional | `string` | - | Additional class for the root element | | `errorMessage` | Optional | `string` | - | Error message shown in place of the grid | | `isLoading` | Optional | `boolean` | `false` | Shows a spinner while the first load is in flight | | `onContainerClick` | Optional | `((id: string) => void)` | - | Invoked with the container id when a card is clicked | | `title` | Optional | `string` | - | Section heading | ### `ExplorerLayout` Explorer split-view shell: a header, a scrollable list column, and a sticky detail column that appears when a row is selected (stacking on narrow viewports). Purely presentational — the page supplies the list (tabs + table) and the detail panel, and owns selection/routing state `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/explorer/explorer-layout.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/explorer/explorer-layout.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `list` | Required | `React.ReactNode` | - | The list column — typically a tab switch plus the device/container table | | `className` | Optional | `string` | - | Additional class for the root element | | `detail` | Optional | `React.ReactNode` | - | The detail column content (shown in the sticky panel when `hasSelection`) | | `hasSelection` | Optional | `boolean` | `false` | When true the layout splits into list (70%) + a sticky detail column (30%); otherwise the list fills the width. Driven by whether a row is selected | | `headerActions` | Optional | `React.ReactNode` | - | Optional header controls (export button, etc.) shown next to the title | | `title` | Optional | `string` | - | Page heading; nothing renders when omitted | # Feedback (/reference/ui/components/feedback) Components for providing feedback and notifications to users. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit ### Core alert ```tsx ``` Contextual feedback banner for success, info, warning, and error messages. Supports icons, close button, an action slot, and an optional full-width banner mode. #### Notes - Once closed via the ✕ button, the component returns `null` and cannot be reopened without unmounting/remounting - Setting `description` automatically adds the `mdk-alert--with-description` modifier for extra spacing #### Example [#core-alert-example] ```tsx /** * Runnable example for Alert. /

) ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `AlarmContents` Body region of an alarm card listing the alert details and recommended next actions `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alarm/alarm-contents/alarm-contents.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alarm/alarm-contents/alarm-contents.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `alarmsData` | Required | `unknown` | - | Alert entries to render. Falls back to [`EmptyState`](/reference/ui/components/feedback/#emptystate) when empty or falsy | | `onNavigate` | Required | `(path: string) => void` | - | Navigation callback forwarded to each [`AlarmRow`](/reference/ui/components/feedback/#alarmrow) for click-through routing | ### `AlarmRow` Single alarm-feed row with severity dot, timestamp, source device, and the alert message `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alarm/alarm-row/alarm-row.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alarm/alarm-row/alarm-row.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `TimelineItemData` | - | The alarm entry to render | | `onNavigate` | Required | `(path: string) => void` | - | Called when the row is clicked; receives the alarm `uuid` as the path segment | ### `CoreAlert` Inline alert banner with type-based icon, optional description, dismissible close button, and trailing action slot `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/alert/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `action` | Optional | `React.ReactNode` | - | Action element rendered to the right | | `banner` | Optional | `boolean` | `false` | Display as full-width banner (no border radius, no margin) | | `className` | Optional | `string` | - | Custom className | | `closable` | Optional | `boolean` | `false` | Shows an ✕ button; clicking it hides the alert | | `description` | Optional | `React.ReactNode` | - | Secondary/detail content shown below the title | | `icon` | Optional | `React.ReactNode` | - | Custom icon (used when showIcon is true) | | `onClose` | Optional | `React.MouseEventHandler` | - | Called when close button is clicked | | `showIcon` | Optional | `boolean` | `false` | Renders the type icon (or the `icon` override) before the content | | `style` | Optional | `React.CSSProperties` | - | Custom styles | | `title` | Optional | `React.ReactNode` | - | Main message | | `type` | Optional | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Controls the color scheme and default icon | ### `EmptyState` Empty state component for displaying placeholder content when no data is available `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/empty-state/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/empty-state/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `description` | Required | `React.ReactNode` | - | Description text or ReactNode displayed below the image | | `className` | Optional | `string` | - | Additional CSS class name | | `image` | Optional | `EmptyStateImage` | `"default"` | Image to display. Use "default" for the standard illustration, "simple" for a minimal icon, or pass a custom ReactNode | | `size` | Optional | `"sm" \| "md" \| "lg"` | `"md"` | Size variant controlling spacing and icon dimensions | ### `ErrorCard` Error card component for displaying error messages `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/error-card/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/error-card/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `error` | Required | `string` | - | Error message string. Supports `\\n` for line breaks | | `className` | Optional | `string` | - | Additional CSS class name | | `title` | Optional | `string` | `"Errors"` | Title displayed above the error message | | `variant` | Optional | `"inline" \| "card"` | `"card"` | Display variant. "card" shows a bordered container, "inline" shows flat text | ### `Loader` [`Loader`](/reference/ui/components/feedback/#loader) component - display pulsing dots animation `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/loader/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/loader/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Custom className for the root element | | `color` | Optional | `"red" \| "gray" \| "blue" \| "amber" \| "orange"` | `"orange"` | Color variant of the loader | | `count` | Optional | `3 \| 5 \| 7` | `5` | Number of dots to display | | `inline` | Optional | `boolean` | `false` | Render as an inline activity indicator instead of a block loading state. The default reserves a fixed 200px so a panel standing in for absent content does not collapse and then jump. Inline, that height is wrong: it strands the dots ~100px below the thing they belong to and centers them against surrounding text, which reads as frozen | | `size` | Optional | `number` | `10` | Size of each dot in pixels | ### `SkeletonBlock` Rectangular shimmer placeholder used to hint at content shape while data is loading `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/skeleton/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/skeleton/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `borderRadius` | Optional | `string \| number` | - | Border radius; ignored when `circle` is true | | `circle` | Optional | `boolean` | `false` | Renders a perfect circle using `height` as the diameter | | `className` | Optional | `string` | - | Additional class for the element | | `height` | Optional | `string \| number` | - | Height in pixels (number) or any CSS value (string) | | `width` | Optional | `string \| number` | - | Width in pixels (number) or any CSS value (string) | ### `Spinner` [`Spinner`](/reference/ui/components/feedback/#spinner) component - display loading state with rotating squares `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/spinner/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/spinner/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Custom className for the root element | | `color` | Optional | `"primary" \| "secondary"` | `"primary"` | Color variant of the spinner | | `fullScreen` | Optional | `boolean` | `false` | Whether to display in fullscreen mode | | `label` | Optional | `string` | - | Optional label text to display below the spinner | | `size` | Optional | `"sm" \| "md" \| "lg"` | `"md"` | Size variant of the spinner | | `speed` | Optional | `"slow" \| "normal" \| "fast"` | `"normal"` | Speed of the animation | | `type` | Optional | `"circle" \| "square"` | `"square"` | Type of spinner animation | ### `Toast` Single transient notification rendered inside the [``](/reference/ui/components/feedback/#toaster) viewport. Use `variant` to convey intent (`success`, `info`, `warning`, `error`); pair with `` and `` for structured content, or wrap a `` for a single inline call-to-action. Most apps will trigger toasts imperatively via the `useToast` hook rather than mounting [``](/reference/ui/components/feedback/#toast) directly `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/toast/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/toast/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `title` | Required | `string` | - | Title shown at the top of the toast | | `description` | Optional | `string` | - | Body text | | `duration` | Optional | `number` | - | Auto-dismiss after N ms | | `icon` | Optional | `React.JSX.Element` | - | Override the default variant icon | | `onOpenChange` | Optional | `((open: boolean) => void)` | - | Open-state change handler | | `open` | Optional | `boolean` | - | Controlled open state | | `variant` | Optional | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Determines the icon and accent | ### `Toaster` Top-level provider + viewport that hosts every toast triggered via `useToast`. Mount once near the root of your app (typically inside ``). Without a [``](/reference/ui/components/feedback/#toaster) in the tree, `useToast` calls are no-ops. Position and visual stacking are controlled by CSS tokens; no props are required for the default top-left placement `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/toast/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/toast/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Required | `React.ReactNode` | - | The [``](/reference/ui/components/feedback/#toast) elements to render | | `position` | Optional | `"top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| "top-center" \| "bottom-center"` | `"top-left"` | Where the viewport is anchored | # Filter (/reference/ui/components/filters) Components for filtering and searching data. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ListViewFilter` Toolbar of dropdown/checkbox filters that drive a list view; emits the active filter set to the parent `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/list-view-filter/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/list-view-filter/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onChange` | Required | `(selections: CascaderValue[]) => void` | - | Callback when filters change | | `options` | Required | `CascaderOption[]` | - | [`Cascader`](/reference/ui/components/forms/#cascader) options for filtering | | `className` | Optional | `string` | - | Custom className for the filter button | | `filterKey` | Optional | `string` | `"default"` | Optional key to force re-mounting the [`Cascader`](/reference/ui/components/forms/#cascader) when filters change Useful if you want to reset the internal state of the [`Cascader`](/reference/ui/components/forms/#cascader) when filters change | | `localFilters` | Optional | `LocalFilters` | - | Current filter values as key-value pairs Example: { type: 'Antminer S19XP H', status: ['active', 'pending'] } | ### `ReportTimeFrameSelector` Reporting-period selector with preset windows (1d / 7d / 30d / custom range) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/report-time-frame-selector/report-time-frame-selector.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/report-time-frame-selector/report-time-frame-selector.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `dateRange` | Required | `[Date, Date]` | - | Custom date range as a `[start, end]` tuple | | `presetTimeFrame` | Required | `number \| null` | - | Selected preset in days (`1`, `7`, `30`); `null` means the custom range is active | | `setDateRange` | Required | `(value: [Date, Date]) => void` | - | Update the custom date range | | `setPresetTimeFrame` | Required | `(value: number \| null) => void` | - | Update the preset selection | ### `TimeframeControls` Date-range picker for financial reporting pages — supports year, month, and week granularity via connected selects `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/timeframe-controls/timeframe-controls.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/timeframe-controls/timeframe-controls.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `dateRange` | Optional | `TimeframeControlsDateRange` | - | Current date range | | `hint` | Optional | `string` | - | Helper text below the controls | | `isMonthSelectVisible` | Optional | `boolean` | `true` | Show month selector | | `isWeekSelectVisible` | Optional | `boolean` | `true` | Show week selector | | `layout` | Optional | `"horizontal" \| "stacked"` | `"horizontal"` | Layout direction | | `onRangeChange` | Optional | `TimeframeControlsOnRangeChange` | - | Called when the range changes | | `onReset` | Optional | `VoidFunction` | - | Called when the Reset button is clicked | | `onTimeframeTypeChange` | Optional | `(type: TimeframeTypeValue) => void` | - | Called when timeframe type changes | | `showResetButton` | Optional | `boolean` | `false` | Shows the Reset button | | `timeframeType` | Optional | `null \| "month" \| "week" \| "year"` | - | Active timeframe type | ### `TimeframeWeekFlatContent` Flat list of selectable week items for the [`TimeframeControls`](/reference/ui/components/filters/#timeframecontrols) week selector `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/timeframe-controls/timeframe-controls-week-content.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/timeframe-controls/timeframe-controls-week-content.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `visibleWeeks` | Required | `Week[]` | - | - | ### `TimeframeWeekTreeContent` Hierarchical year → month → week tree for the [`TimeframeControls`](/reference/ui/components/filters/#timeframecontrols) week selector `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/timeframe-controls/timeframe-controls-week-content.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/timeframe-controls/timeframe-controls-week-content.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `selectedMonth` | Required | `number` | - | - | | `selectedYear` | Required | `number` | - | - | | `timezone` | Required | `string` | - | - | # Form (/reference/ui/components/forms) Form components for building data entry interfaces. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit ### Core form workflow ```tsx ``` Form primitives built on [`react-hook-form`](https://react-hook-form.com/). Use with a `useForm()` instance. #### Pieces - `Form` — wraps a `
` and provides `FormProvider` context. - `FormField` — wraps [`react-hook-form`](https://react-hook-form.com/)'s `Controller` and provides field context. - `FormItem` — layout wrapper that generates IDs for accessibility linking. - `FormLabel`, `FormControl`, `FormDescription`, `FormMessage` — slots. #### Notes - Pre-built field helpers (`FormInput`, `FormSelect`, `FormCheckbox`, `FormDatePicker`, `FormCascader`, etc.) live in [`form-fields.tsx`](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx). - See the directory's [`README.md`](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/README.md) and [`QUICK_REFERENCE.md`](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/QUICK_REFERENCE.md) for the full pattern catalog. #### Example [#core-workflow-example] ```tsx /** * Runnable example for Form (react-hook-form + zod). */ Button, Form, FormControl, FormField, FormItem, FormLabel, FormMessage, Input, } from '@tetherto/mdk-react-devkit' const schema = z.object({ name: z.string().min(2, 'At least 2 characters'), email: z.string().email('Must be a valid email'), }) type FormValues = z.infer const form = useForm({ resolver: zodResolver(schema), defaultValues: { name: '', email: '' }, }) const onSubmit = (values: FormValues) => { // eslint-disable-next-line no-console console.log('submit', values) } return ( ( Name )} /> ( Email )} /> ) } ``` #### Related API - [`useFormField`](/reference/ui/hooks/forms/#useformfield) @tetherto/mdk-react-devkit ### Pre-built input field ```tsx ``` #### Related API - [`FormField`](/reference/ui/components/forms/#formfield) - [`useFormField`](/reference/ui/hooks/forms/#useformfield) @tetherto/mdk-react-devkit ### Date range picker ```tsx ``` Single-date and range-date pickers built on `react-day-picker`. The range picker includes presets and a modal-style popover with Clear / Apply actions. #### Data contracts ```ts type DateRange = { from: Date | undefined; to?: Date | undefined }; type PresetItem = { label: string; value: DateRange }; ``` #### Example [#date-range-picker-example] ```tsx /** * Runnable example for DatePicker and DateRangePicker. / const [date, setDate] = useState() const [range, setRange] = useState() return (

) } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `Cascader` Two-panel hierarchical selector for picking a leaf value from a nested tree (categories → subcategories → leaf). Features: - Two-column layout: categories on left, options on right - Single or multiple selection modes - Search/filter functionality via [`TagInput`](/reference/ui/components/forms/#taginput) - Category-level selection (select/deselect all children) - Indeterminate state for partial selections - [`Tag`](/reference/ui/components/display/#tag) display for multiple selections - Keyboard navigation support - Disabled state support `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/cascader/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/cascader/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `options` | Required | `CascaderOption[]` | - | Hierarchical options to display in the cascader Parent options with children appear in the left panel Child options appear in the right panel when parent is selected | | `className` | Optional | `string` | - | Custom className for the root cascader element | | `disabled` | Optional | `boolean` | `false` | Disable the entire cascader (input and all options) | | `dropdownClassName` | Optional | `string` | - | Custom className for the dropdown panels container | | `multiple` | Optional | `boolean` | `false` | Enable multiple selection mode - true: Shows checkboxes, allows multiple selections, displays selected items as tags - false: Shows radio buttons, allows single selection | | `onChange` | Optional | `((value: CascaderValue \| CascaderValue[] \| null) => void)` | - | Callback when selection changes - For single select: receives CascaderValue or null - For multiple select: receives CascaderValue[] or null | | `placeholder` | Optional | `string` | `"Select..."` | Placeholder text shown in the input when no selections are made | | `value` | Optional | `CascaderValue \| CascaderValue[]` | - | Current selected value(s) - For single select: CascaderValue (e.g., ['category', 'option']) - For multiple select: CascaderValue[] (e.g., [['cat1', 'opt1'], ['cat2', 'opt2']]) | ### `Checkbox` [`Checkbox`](/reference/ui/components/forms/#checkbox) component with full customization `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/checkbox/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/checkbox/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `checked` | Optional | `CheckedState` | - | Controlled checked state | | `className` | Optional | `string` | - | Custom className for the root element | | `color` | Optional | `"success" \| "warning" \| "error" \| "primary" \| "default"` | `"primary"` | Color variant when checked | | `defaultChecked` | Optional | `CheckedState` | - | Uncontrolled initial checked state | | `disabled` | Optional | `boolean` | `false` | Disable the input | | `indicatorClassName` | Optional | `string` | - | Custom className for the indicator element | | `onCheckedChange` | Optional | `(((checked: CheckedState) => void) & ((checked: CheckedState) => void))` | - | Callback when the checked state changes | | `radius` | Optional | `"small" \| "none" \| "medium" \| "large" \| "full"` | `"none"` | Border radius variant | | `size` | Optional | `"sm" \| "md" \| "lg" \| "xs"` | `"md"` | Size variant of the checkbox | ### `CurrencyToggler` [`CurrencyToggler`](/reference/ui/components/forms/#currencytoggler) component for switching between currencies `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/currency-toggler/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/currency-toggler/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `currencies` | Required | `(string \| CurrencyItem)[]` | - | List of currency options | | `onChange` | Required | `(currency: string) => void` | - | Fired with the selected currency value when a button is clicked | | `value` | Required | `string` | - | Currently selected currency value | | `className` | Optional | `string` | - | Additional class for the root element | ### `DatePicker` Single-date selection component built on react-day-picker with the MDK dark theme. Controlled via `selected` / `onSelect` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/date-picker/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/date-picker/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `calendarClassName` | Optional | `string` | - | Custom className for the calendar | | `dateFormat` | Optional | `string` | `"MM/dd/yyyy"` | Date format for display | | `disabled` | Optional | `(boolean & (Matcher \| Matcher[]))` | `false` | Whether the picker is disabled | | `onSelect` | Optional | `((date: Date \| undefined) => void)` | - | Callback when date changes | | `placeholder` | Optional | `string` | `"Pick a date"` | Placeholder text when no date is selected | | `selected` | Optional | `Date` | - | Currently selected date | | `triggerClassName` | Optional | `string` | - | Custom className for the trigger button | ### `DateRangePicker` Date-range selection component with preset shortcuts (last 7/14/30/90 days) and a modal interface. Controlled via `selected` / `onSelect` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/date-picker/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/date-picker/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `allowFutureDates` | Optional | `boolean` | `false` | Whether to allow future dates | | `calendarClassName` | Optional | `string` | - | Custom className for the calendar | | `dateFormat` | Optional | `string` | `"MM/dd/yyyy"` | Date format for display | | `disabled` | Optional | `(boolean & (Matcher \| Matcher[]))` | `false` | Whether the picker is disabled | | `modalClassName` | Optional | `string` | - | Custom className for the modal | | `onSelect` | Optional | `((range: DateRange \| undefined) => void)` | - | Callback when date range changes | | `placeholder` | Optional | `string` | `"Pick a date range"` | Placeholder text when no range is selected | | `presets` | Optional | `PresetItem[]` | - | Custom preset items | | `selected` | Optional | `DateRange` | - | Selected date range | | `showPresets` | Optional | `boolean` | `true` | Whether to show preset buttons | | `triggerClassName` | Optional | `string` | - | Custom className for the trigger button | ### `Form` React Hook [`Form`](/reference/ui/components/forms/#form) provider wrapper. Pass the result of `useForm()` as `form` and render fields via [`FormField`](/reference/ui/components/forms/#formfield) / [`FormItem`](/reference/ui/components/forms/#formitem) / [`FormLabel`](/reference/ui/components/forms/#formlabel) / [`FormControl`](/reference/ui/components/forms/#formcontrol) / [`FormMessage`](/reference/ui/components/forms/#formmessage) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Required | `React.ReactNode` | - | - | | `form` | Required | `UseFormReturn` | - | - | ### `FormCascader` Pre-built [`Cascader`](/reference/ui/components/forms/#cascader) field component with integrated form state. Perfect for hierarchical selections like categories and subcategories `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `options` | Required | `CascaderOption[]` | - | - | | `cascaderProps` | Optional | `Omit, "onChange" \| "value" \| "options" \| "placeholder">` | - | - | | `description` | Optional | `string` | - | - | | `label` | Optional | `string` | - | - | | `multiple` | Optional | `boolean` | - | - | | `placeholder` | Optional | `string` | - | - | ### `FormCheckbox` Pre-built [`Checkbox`](/reference/ui/components/forms/#checkbox) field component with integrated form state `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `checkboxProps` | Optional | `({ checked?: CheckedState \| undefined; defaultChecked?: CheckedState \| undefined; disabled?: boolean \| undefined; size?: CheckboxSize \| undefined; color?: ComponentColor \| undefined; radius?: BorderRadius \| undefined; className?: string \| u… / see source /` | - | - | | `description` | Optional | `string` | - | - | | `label` | Optional | `string` | - | - | | `layout` | Optional | `"row" \| "column"` | - | - | | `placeholder` | Optional | `string` | - | - | ### `FormControl` Slot-based wrapper that injects ARIA attributes onto its child input element without adding an extra DOM wrapper `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx)
### `FormDatePicker` Pre-built [`DatePicker`](/reference/ui/components/forms/#datepicker) field component with integrated form state `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `datePickerProps` | Optional | `object` | - | - | | `description` | Optional | `string` | - | - | | `label` | Optional | `string` | - | - | | `placeholder` | Optional | `string` | - | - | ### `FormDescription` Optional helper text displayed below the input `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx)
### `FormField` Wraps react-hook-form's Controller and provides field context to descendants `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx)
### `FormInput` Pre-built [`Input`](/reference/ui/components/forms/#input) field component with integrated form state. Reduces boilerplate by combining [`FormField`](/reference/ui/components/forms/#formfield), [`FormItem`](/reference/ui/components/forms/#formitem), [`FormLabel`](/reference/ui/components/forms/#formlabel), [`FormControl`](/reference/ui/components/forms/#formcontrol), and [`FormMessage`](/reference/ui/components/forms/#formmessage) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `description` | Optional | `string` | - | - | | `inputProps` | Optional | `Omit & React.RefAttributes, "type" \| "variant">` | - | - | | `label` | Optional | `string` | - | - | | `placeholder` | Optional | `string` | - | - | | `type` | Optional | `React.HTMLInputTypeAttribute` | - | - | | `variant` | Optional | `"search" \| "default"` | - | - | ### `FormItem` Layout wrapper for a form field. Generates a unique ID for accessibility linking `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx)
### `FormLabel` [`Label`](/reference/ui/components/forms/#label) that auto-links to the form field input via generated IDs. Applies error styling when the field has a validation error `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `htmlFor` | Optional | `string` | - | Id of the input being labelled | ### `FormMessage` Displays the validation error message from react-hook-form field state. Falls back to children if no error is present. Always renders to prevent layout shift when errors appear `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/index.tsx)
### `FormRadioGroup` Pre-built [`RadioGroup`](/reference/ui/components/forms/#radiogroup) field component with integrated form state `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `options` | Required | `FormRadioOption[]` | - | - | | `description` | Optional | `string` | - | - | | `label` | Optional | `string` | - | - | | `orientation` | Optional | `"horizontal" \| "vertical"` | - | - | | `placeholder` | Optional | `string` | - | - | | `radioGroupProps` | Optional | `object` | - | - | ### `FormSelect` Pre-built [`Select`](/reference/ui/components/forms/#select) field component with integrated form state `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `options` | Required | `FormSelectOption[]` | - | - | | `description` | Optional | `string` | - | - | | `label` | Optional | `string` | - | - | | `placeholder` | Optional | `string` | - | - | | `selectProps` | Optional | `object` | - | - | ### `FormSwitch` Pre-built [`Switch`](/reference/ui/components/forms/#switch) field component with integrated form state `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `description` | Optional | `string` | - | - | | `label` | Optional | `string` | - | - | | `layout` | Optional | `"row" \| "column"` | - | - | | `placeholder` | Optional | `string` | - | - | | `switchProps` | Optional | `object` | - | - | ### `FormTagInput` Pre-built [`TagInput`](/reference/ui/components/forms/#taginput) field component with integrated form state. Perfect for multi-select with search and tag display `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `allowCustomTags` | Optional | `boolean` | - | - | | `description` | Optional | `string` | - | - | | `label` | Optional | `string` | - | - | | `options` | Optional | `TagInputOption[]` | - | - | | `placeholder` | Optional | `string` | - | - | | `tagInputProps` | Optional | `object` | - | - | | `variant` | Optional | `"search" \| "default"` | - | - | ### `FormTextArea` Pre-built [`TextArea`](/reference/ui/components/forms/#textarea) field component with integrated form state `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/form/form-fields.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `description` | Optional | `string` | - | - | | `label` | Optional | `string` | - | - | | `placeholder` | Optional | `string` | - | - | | `textAreaProps` | Optional | `(Omit & React.RefAttributes)` | - | - | ### `Input` Text input with optional label, prefix/suffix slots, and a `search` variant. Forwards refs and all native `` attributes `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/input/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/input/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `error` | Optional | `string` | - | Validation error message. When provided, displays error styling (red border) and the message below the input | | `id` | Optional | `string` | `auto-generated` | HTML id for the input. Required when using label for accessibility | | `label` | Optional | `string` | - | Optional label displayed above the input | | `prefix` | Optional | `React.ReactNode` | - | Prefix element displayed before the input (left side) | | `size` | Optional | `"default" \| "medium"` | `"default"` | Size of the input - `default`: padding 10px 12px, icon 16px - `medium`: padding 6px 12px, icon 12px | | `suffix` | Optional | `React.ReactNode` | - | Suffix element displayed after the input (right side) | | `variant` | Optional | `"search" \| "default"` | `"default"` | Variant of the input - `default`: Standard text input - `search`: [`Input`](/reference/ui/components/forms/#input) with magnifying glass icon on the right | | `wrapperClassName` | Optional | `string` | - | Custom className for the root wrapper | ### `Label` Accessible text label for form controls. Associates with an input via `htmlFor` and supports a required-mark indicator. Built on Radix [`Label`](/reference/ui/components/forms/#label) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/label/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/label/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `htmlFor` | Optional | `string` | - | Id of the input being labelled | ### `MultiLevelSelect` Multi-level select component with collapsible sections `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/multi-level-select/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/multi-level-select/index.tsx)
### `MultiSelect` Multi-select picker built on Radix [`Popover`](/reference/ui/components/overlays/#popover) + [`Checkbox`](/reference/ui/components/forms/#checkbox). Sibling to [``](/reference/ui/components/forms/#select) sizes | | `value` | Optional | `string[]` | - | Controlled selected values. Omit to use `defaultValue` for uncontrolled mode | | `variant` | Optional | `"default" \| "colored"` | `"default"` | `'colored'` paints the trigger in the primary tint (matches [`` | | `disabled` | Optional | `boolean` | `false` | Disabled state | | `dropdownMaxHeight` | Optional | `string` | `"12rem"` | Maximum height of the dropdown (CSS value, e.g. '300px', '20rem') | | `dropdownMinHeight` | Optional | `string` | - | Minimum height of the dropdown (CSS value, e.g. '100px', '6rem') | | `filterOptions` | Optional | `((options: TagInputOption[], query: string) => TagInputOption[])` | `case-insensitive includes` | Filter options by input value. Receives options and query, returns filtered options. When undefined, filters by case-insensitive includes | | `id` | Optional | `string` | `auto-generated` | HTML id for the input | | `label` | Optional | `string` | - | [`Label`](/reference/ui/components/forms/#label) for the input | | `onInputChange` | Optional | `((value: string) => void)` | - | Callback when input value changes (typing). Receives current input value. Useful for async option loading or custom filtering | | `onSubmit` | Optional | `((tags: string[]) => void)` | - | Callback when user presses Enter (submit). Receives current tags. Called after adding a tag from selection or typed text, if applicable | | `onTagsChange` | Optional | `((tags: string[]) => void)` | - | Callback when tags change (add/remove) | | `options` | Optional | `TagInputOption[]` | `[]` | Options to show in the dropdown when input is focused | | `placeholder` | Optional | `string` | `"Search..."` | Placeholder when input is empty | | `renderDropdown` | Optional | `((props: TagInputDropdownProps) => React.ReactNode)` | - | Render custom dropdown content. When provided, replaces the default dropdown. Use this to apply your own styling or structure | | `size` | Optional | `"sm" \| "md" \| "lg"` | `"lg"` | Size of the tag input — matches [`Select`](/reference/ui/components/forms/#select) sizes - `sm`: 24px height - `md`: 32px height - `lg`: 40px height | | `value` | Optional | `string[]` | `[]` | Controlled tags (array of tag values) | | `variant` | Optional | `"search" \| "default"` | `"search"` | [`Input`](/reference/ui/components/forms/#input) variant; `'search'` shows a magnifying-glass icon that doubles as a clear-all button | | `wrapperClassName` | Optional | `string` | - | Custom className for the wrapper | ### `TextArea` [`TextArea`](/reference/ui/components/forms/#textarea) component with label support and error handling `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/textarea/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/textarea/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `error` | Optional | `string` | - | Validation error message. When provided, displays error styling (red border) and the message below the textarea | | `id` | Optional | `string` | `auto-generated` | HTML id for the textarea. Required when using label for accessibility | | `label` | Optional | `string` | - | Optional label displayed above the textarea | | `wrapperClassName` | Optional | `string` | - | Custom className for the root wrapper | # Layout (/reference/ui/components/layout) Components for page structure and layout. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit ### Accordion ```tsx ``` Collapsible panel with a title trigger and animated content area. Exports both a high-level `Accordion` wrapper and composable primitives (`AccordionRoot`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`). #### Notes - `Accordion` wraps the primitives with `type="multiple"` and a single hard-coded item value; use `AccordionRoot` directly when you need multi-item control - `toggleIconPosition="right"` swaps to `PlusIcon`/`MinusIcon` style; `"left"` uses `ChevronDown`/`ChevronRight` #### Example [#accordion-example] ```tsx /** * Runnable example for Accordion. / Accordion, AccordionContent, AccordionItem, AccordionRoot, AccordionTrigger, } from '@tetherto/mdk-react-devkit'

Collapsed/expanded content goes here. Supports any React node as children.

This variant uses a solid background for the accordion panel.
Custom trigger position
Content for item 1 using low-level Accordion primitives.
Another section
Content for item 2.

) ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `Accordion` Vertically stacked, collapsible content panels with optional toggle icon. Renders a styled wrapper around Radix [`Accordion`](/reference/ui/components/layout/#accordion): pass `title` for the default header or compose [``](/reference/ui/components/layout/#accordionitem)s as children for full control `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/accordion/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/accordion/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `customLabel` | Optional | `React.ReactNode` | - | Extra content (e.g. a badge) rendered in the trigger header | | `isOpened` | Optional | `boolean` | `false` | Whether the panel starts expanded | | `isRow` | Optional | `boolean` | `false` | Lays out the content area as a flex row instead of column | | `noBorder` | Optional | `boolean` | `false` | Removes the bottom border from the trigger | | `onValueChange` | Optional | `((value: string \| string[]) => void)` | - | Fired when the open/close state changes | | `showToggleIcon` | Optional | `boolean` | `true` | Shows/hides the expand/collapse chevron icon | | `solidBackground` | Optional | `boolean` | `false` | Applies a solid background to the accordion container | | `title` | Optional | `string` | `""` | Header label shown in the trigger button | | `toggleIconPosition` | Optional | `"left" \| "right"` | `"left"` | Side on which the toggle icon appears | | `unpadded` | Optional | `boolean` | `false` | Removes the default inner padding from the content area | ### `AccordionContent` [`Accordion`](/reference/ui/components/layout/#accordion) Content component (collapsible content area) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/accordion/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/accordion/index.tsx)
### `AccordionItem` Single collapsible row within an [``](/reference/ui/components/layout/#accordion). Pass a unique `value` so Radix can track open/closed state; wrap an [``](/reference/ui/components/layout/#accordiontrigger) and an [``](/reference/ui/components/layout/#accordioncontent) as children `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/accordion/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/accordion/index.tsx)
### `AccordionTrigger` [`Accordion`](/reference/ui/components/layout/#accordion) Trigger component (header/button) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/accordion/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/accordion/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `customLabel` | Optional | `React.ReactNode` | - | Slot for extra content in the trigger header | | `showToggleIcon` | Optional | `boolean` | `true` | Shows/hides the toggle icon | | `timestamp` | Optional | `string` | - | Forwarded to the underlying Radix trigger element; not rendered by the component | | `toggleIconPosition` | Optional | `"left" \| "right"` | `"left"` | Side on which the toggle icon appears | ### `CardBody` Main content region of a `` — applies the standard inner padding and vertical rhythm `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/card/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/card/index.tsx)
### `CardFooter` Bottom action/metadata row of a ``, typically used for buttons, timestamps, or secondary info `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/card/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/card/index.tsx)
### `CardHeader` Top region of a `` that groups the title, optional subtitle, and an action slot `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/card/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/card/index.tsx)
### `ChartWrapper` [`ChartWrapper`](/reference/ui/components/layout/#chartwrapper) - Wrapper component for charts with loading and empty states Handles three states: - Loading: Shows skeleton loader - No data: Shows empty state placeholder - Has data: Shows chart content `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/chart-wrapper/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/chart-wrapper/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Optional | `React.ReactNode` | - | Chart content to render | | `className` | Optional | `string` | - | Custom className for the container | | `customLoader` | Optional | `React.ReactNode` | `` | Custom loader component to show when loading (overrides default spinner) | | `customNoDataMessage` | Optional | `React.ReactNode` | - | Custom message or component to show when no data | | `data` | Optional | `unknown[] \| Record` | - | Chart data object (for [`LineChart`](/reference/ui/components/charts/#linechart) with datasets) | | `dataset` | Optional | `unknown[] \| Record` | - | Chart dataset (for [`BarChart`](/reference/ui/components/charts/#barchart) with direct dataset) | | `isLoading` | Optional | `boolean` | `false` | Loading state | | `loadingMinHeight` | Optional | `number` | `minHeight` | Minimum height for the loading skeleton (in pixels) Falls back to minHeight if not provided | | `minHeight` | Optional | `number` | `400` | Minimum height for the container (in pixels) | | `showNoDataPlaceholder` | Optional | `boolean` | `true` | Whether to show "no data" placeholder when data is empty | ### `Divider` Thin horizontal or vertical rule used to separate logical sections of a layout `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/divider/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/divider/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `align` | Optional | `"center" \| "left" \| "right"` | `"center"` | Horizontal alignment of the label | | `children` | Optional | `React.ReactNode` | - | Text or node rendered in the middle of the divider | | `className` | Optional | `string` | - | Custom className | | `dashed` | Optional | `boolean` | `false` | Line style | | `dotted` | Optional | `boolean` | `false` | Renders a dotted line (takes precedence over `dashed`) | | `orientation` | Optional | `"horizontal" \| "vertical"` | `"horizontal"` | Line orientation | | `plain` | Optional | `boolean` | `false` | Plain text style — no border around label | ### `LabeledCard` Card variant that pairs a tiny label above the body — used for compact stat or metadata blocks `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/labeled-card/labeled-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/labeled-card/labeled-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Optional | `React.ReactNode` | - | Card body content | | `className` | Optional | `string` | - | Additional class for the root element | | `getNavigateOptions` | Optional | `(label: string) => Partial<{ href: string; target: string; }>` | - | Returns a link `href`/`target` for the label when provided | | `hasNoBorder` | Optional | `boolean` | `false` | Removes the card border | | `hasNoMargin` | Optional | `boolean` | `false` | Removes default margin | | `hasNoWrap` | Optional | `boolean` | `false` | Prevents content from wrapping | | `isDark` | Optional | `boolean` | `false` | Applies a dark background modifier | | `isFullHeight` | Optional | `boolean` | `false` | Stretches the card to full container height | | `isFullWidth` | Optional | `boolean` | `false` | Stretches the card to full container width | | `isRelative` | Optional | `boolean` | `false` | Sets `position: relative` on the container | | `isScrollable` | Optional | `boolean` | `false` | Enables vertical scroll on the card body | | `label` | Optional | `React.ReactNode` | - | Header content shown above the card body | ### `LazyTabWrapper` [`LazyTabWrapper`](/reference/ui/components/layout/#lazytabwrapper) - Wrapper for lazy-loaded tab components with Suspense Handles lazy loading with a fallback spinner while the component loads. Useful for code-splitting large tab components `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/lazy-tab-wrapper/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/lazy-tab-wrapper/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `Component` | Required | `React.ComponentType<{ data?: T \| undefined; }>` | - | Lazy-loaded component to render | | `data` | Optional | `T` | - | Data to pass to the component | | `fallback` | Optional | `React.ReactNode` | `` | Custom fallback component while loading | | `spinnerType` | Optional | `"circle" \| "square"` | `"circle"` | [`Spinner`](/reference/ui/components/feedback/#spinner) type when using default fallback | ### `Mosaic` [`Mosaic`](/reference/ui/components/layout/#mosaic) - Grid layout component with named areas Features: - Named grid areas for layout - Responsive: stacks on mobile, grid on desktop - Auto-generates column tracks - Validates column count vs template `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/mosaic/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/mosaic/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Required | `React.ReactNode` | - | `Mosaic.Item` elements | | `template` | Required | `string[] \| string[][]` | - | Grid area layout. 1D: each string is a row of space-separated area names. 2D: each inner array is a row | | `className` | Optional | `string` | - | Additional class for the grid element | | `columns` | Optional | `string \| string[]` | - | Custom `grid-template-columns` value or array of track sizes. Defaults to equal-width fractional tracks | | `gap` | Optional | `string` | `"12px"` | CSS gap between grid cells | | `rowHeight` | Optional | `string` | `"auto"` | CSS height for each row | ### `Tabs` [`Tabs`](/reference/ui/components/layout/#tabs) component for organizing content into panels `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/tabs/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/tabs/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `defaultValue` | Optional | `string` | - | Uncontrolled initial active value | | `onValueChange` | Optional | `((value: string) => void)` | - | Fired when the active tab changes | | `orientation` | Optional | `"horizontal" \| "vertical"` | `"horizontal"` | Keyboard navigation orientation | | `value` | Optional | `string` | - | Controlled active tab value | | `variant` | Optional | `"default" \| "side" \| "underline"` | - | - | # Media (/reference/ui/components/media) Components for displaying images, icons, and other media. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ArrowIcon` Directional arrow glyph (up / down / left / right) used by sortable headers, breadcrumbs, and toggles `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/icons/arrow-icon.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/icons/arrow-icon.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Optional | `undefined` | - | - | | `color` | Optional | `string` | `"currentColor"` | Only affects single-color icons (default: 'currentColor') | | `isOpen` | Optional | `boolean` | - | - | | `size` | Optional | `string \| number` | - | Sets both width and height | # Miscellaneous (/reference/ui/components/misc) General-purpose and utility components. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `SparePartDetails` Presentational key-value list of a spare part's attributes (code, model, site, serial number, MAC). Renders data only; used inside the move/confirm spare-part dialogs but safe to compose standalone `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/move-spare-part-modal/spare-part-details.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/inventory/spare-parts/move-spare-part-modal/spare-part-details.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `sparePart` | Optional | `SparePartDetailsRecord` | - | - | # Monitoring (/reference/ui/components/monitoring) Components for system monitoring and status displays. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `LogActivityIcon` Status icon used inside [``](/reference/ui/components/monitoring/#logrow) to indicate event severity (info / warning / error / success) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/activity-log-icon.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/activity-log-icon.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `status` | Required | `string` | - | - | ### `LogDot` Coloured dot used to mark a log event's severity or category inline with the row `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/log-dot.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/log-dot.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `status` | Required | `string` | - | Severity string for color mapping | | `type` | Required | `string` | - | `'Incidents'` renders a colored circle; `'Activity'` renders an activity icon | ### `LogItem` Compact log-line element rendering a single event with optional icon, timestamp, and message `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/log-item.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/log-item.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `LogData` | - | - | | `onLogClicked` | Optional | `((uuid: string) => void)` | - | - | ### `LogRow` Single row of a logs feed — composes the dot/icon, timestamp, and message into one entry `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/log-row.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/log-row.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `log` | Required | `LogData` | - | Log entry data | | `type` | Required | `string` | - | Log type (controls dot appearance) | | `onLogClicked` | Optional | `((uuid: string) => void)` | - | Click handler | | `style` | Optional | `React.CSSProperties` | - | Inline style for the row container | ### `LogsCard` Card wrapper for a vertically scrolling logs feed with a sticky header `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/logs-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/logs/logs-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `emptyMessage` | Optional | `string` | `"No active incidents"` | Message shown when `logsData` is empty | | `isDark` | Optional | `boolean` | `false` | Applies dark card theme | | `isLoading` | Optional | `boolean` | `false` | Shows skeleton rows while loading | | `label` | Optional | `string` | - | Card header label | | `logsData` | Optional | `LogData[]` | `[]` | Array of log entries to display | | `onLogClicked` | Optional | `(uuid: string) => void` | - | Fired with the log UUID when a row is clicked | | `pagination` | Optional | `LogPagination` | - | [`Pagination`](/reference/ui/components/navigation/#pagination) config; hides pagination when on page 1 or data is empty | | `skeletonRows` | Optional | `number` | `4` | Number of skeleton rows shown during loading | | `type` | Optional | `string` | - | Log type (`'Incidents'` or `'Activity'`); controls the [`LogDot`](/reference/ui/components/monitoring/#logdot) appearance | # Navigation (/reference/ui/components/navigation) Components for application navigation. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit ### Breadcrumbs ```tsx ``` Horizontal breadcrumb navigation. Renders an ordered trail of links / buttons / plain labels with an optional "Back" button on the left. #### Notes - The last item is rendered as the current page (`aria-current="page"`) - Items without `href` or `onClick` render as plain text #### Example [#breadcrumbs-example] ```tsx /** * Runnable example for Breadcrumbs. / undefined} items={[ { label: 'Dashboard', href: '/' }, { label: 'Devices', onClick: () => undefined }, { label: 'Miner #42' }, ]} /> ) ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `AppHeader` Generic top-bar shell with three slots: `start`, `children` (middle), and `actions` (end). Renders a sticky dark surface; consumers compose any content into the slots. The sidebar collapse toggle, brand logo, stats strip, and action buttons are all caller-provided — this component owns no domain `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/app-header/app-header.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/app-header/app-header.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `actions` | Optional | `React.ReactNode` | - | Right-edge action cluster — e.g. alarms bell, profile menu, or sign-out | | `children` | Optional | `React.ReactNode` | - | Middle slot — e.g. the dashboard stats strip or page title | | `className` | Optional | `string` | - | Optional class hook for the outer `
` element | | `logo` | Optional | `React.ReactNode` | - | Left-most slot — typically the app's brand lockup / logo | | `start` | Optional | `React.ReactNode` | - | Left-edge content — e.g. a sidebar collapse toggle or brand wordmark | | `sticky` | Optional | `boolean` | `true` | Render the header sticky to the top of its scroll container | ### `Breadcrumbs` Hierarchical navigation trail that renders the path of pages leading to the current view. Each item can be a link (`href` or `onClick`) or plain text; the last item is rendered as the current page. Pass `showBack` to prepend a "back" affordance for mobile/touch layouts. The separator between items is customisable via `separator` (defaults to `/`) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/breadcrumbs/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/breadcrumbs/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `items` | Required | `BreadcrumbItem[]` | - | Ordered trail; the last item is rendered as current | | `backClassName` | Optional | `string` | - | Class names applied to the back button | | `backLabel` | Optional | `string` | `"Back"` | [`Label`](/reference/ui/components/forms/#label) for the back button | | `className` | Optional | `string` | - | Root class names | | `itemClassName` | Optional | `string` | - | Class names applied to each item | | `onBackClick` | Optional | `VoidFunction` | - | Callback fired when the back button is clicked | | `separator` | Optional | `React.ReactNode` | `"/"` | Custom separator between items | | `showBack` | Optional | `boolean` | `false` | Show a leading "Back" button | ### `Pagination` [`Pagination`](/reference/ui/components/navigation/#pagination) component for navigating through pages `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/pagination/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/pagination/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Custom className for the root element | | `current` | Optional | `number` | `1` | Current active page number | | `disabled` | Optional | `boolean` | `false` | Disable pagination | | `onChange` | Optional | `((page: number, pageSize: number) => void)` | - | Callback when page number or page size changes | | `onSizeChange` | Optional | `((current: number, size: number) => void)` | - | Callback when page size changes | | `pageSize` | Optional | `number` | `20` | Number of items per page | | `pageSizeOptions` | Optional | `number[]` | `[10, 20, 50, 100]` | Page size options for the select dropdown | | `showSizeChanger` | Optional | `boolean` | `true` | Show page size changer | | `showTotal` | Optional | `boolean` | `false` | Show total count text | | `size` | Optional | `"sm" \| "md" \| "lg"` | `"sm"` | Size variant | | `total` | Optional | `number` | `0` | Total number of items | ### `Sidebar` Application sidebar with collapsible state, persistent expansion (via `localStorage`), optional overlay mode, and item-click + active-item highlighting `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/sidebar/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/sidebar/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `items` | Required | `SidebarMenuItem[]` | - | Menu items (supports nested `items`) | | `activeId` | Optional | `string` | - | Currently active item id | | `className` | Optional | `string` | - | Additional class names | | `defaultExpanded` | Optional | `boolean` | `false` | Initial expanded state | | `expanded` | Optional | `boolean` | - | Controlled expanded state | | `header` | Optional | `React.ReactNode` | - | Header content (e.g. logo, app name) | | `onClose` | Optional | `VoidFunction` | - | Called when the backdrop or ESC closes | | `onExpandedChange` | Optional | `((expanded: boolean) => void)` | - | Setter for the expanded state | | `onItemClick` | Optional | `((item: SidebarMenuItem) => void)` | - | Item-click handler | | `overlay` | Optional | `boolean` | `false` | Show as fixed overlay with backdrop | | `visible` | Optional | `boolean` | `true` | Hide entirely without unmounting | # Overlay (/reference/ui/components/overlays) Components for overlays and floating UI elements. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `Popover` [`Popover`](/reference/ui/components/overlays/#popover) Root - Container for a single popover `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/popover/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/popover/index.tsx)
### `SimplePopover` One-line convenience wrapper that pairs a trigger with floating content — no provider boilerplate `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/popover/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/popover/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `content` | Required | `React.ReactNode` | - | [`Popover`](/reference/ui/components/overlays/#popover) content | | `trigger` | Required | `React.ReactNode` | - | Element that triggers the popover | | `align` | Optional | `"center" \| "start" \| "end"` | `"center"` | Alignment of the popover | | `className` | Optional | `string` | - | Additional class for content | | `onOpenChange` | Optional | `((open: boolean) => void)` | - | Callback when open state changes | | `open` | Optional | `boolean` | - | Controlled open state | | `showArrow` | Optional | `boolean` | `false` | Whether to show the arrow | | `showClose` | Optional | `boolean` | `false` | Whether to show a close button | | `side` | Optional | `"left" \| "right" \| "top" \| "bottom"` | `"bottom"` | Position of the popover relative to trigger | | `sideOffset` | Optional | `number` | `8` | Distance from the trigger in pixels | ### `SimpleTooltip` One-line convenience wrapper around the full [``](/reference/ui/components/overlays/#tooltip) primitive set. Pass `content` (the hover text) and any single React element as `children` — [``](/reference/ui/components/overlays/#simpletooltip) handles the provider, trigger, portal and content for you. Prefer this over composing [``](/reference/ui/components/overlays/#tooltip) + `` + `` unless you need custom positioning or async content `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/tooltip/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/tooltip/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Required | `React.ReactNode` | - | Element that triggers the tooltip | | `content` | Required | `React.ReactNode` | - | [`Tooltip`](/reference/ui/components/overlays/#tooltip) content (string or JSX) | | `className` | Optional | `string` | - | Additional class for content | | `delayDuration` | Optional | `number` | `200` | Delay before showing tooltip (ms) | | `showArrow` | Optional | `boolean` | `true` | Whether to show the arrow | | `side` | Optional | `"left" \| "right" \| "top" \| "bottom"` | `"top"` | Position of the tooltip relative to trigger | | `sideOffset` | Optional | `number` | `8` | Distance from the trigger in pixels | ### `Tooltip` [`Tooltip`](/reference/ui/components/overlays/#tooltip) Root - Container for a single tooltip `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/tooltip/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/tooltip/index.tsx)
# Page (/reference/ui/components/pages) Components for full-page layouts and page structures. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `NotFoundPage` Full-page 404 view with a heading, supporting copy, and a primary call-to-action back to safety `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/not-found-page/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/not-found-page/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Additional CSS class name | | `message` | Optional | `string` | `"The page you are looking for does not exist."` | Message displayed below the title | | `onGoHome` | Optional | `VoidFunction` | - | Callback fired when the "Go Home" button is clicked | | `title` | Optional | `string` | `"404"` | Page title | # Settings (/reference/ui/components/settings) Components for settings and configuration interfaces. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `AddUserModal` Modal form for inviting a new user — captures email, role, and optional team assignment `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/add-user-modal/add-user-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/add-user-modal/add-user-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onClose` | Required | `VoidFunction` | - | Called when the user dismisses the modal (cancel or backdrop) | | `onSubmit` | Required | `(data: { name: string; email: string; role: string; }) => Promise` | - | Async handler called with validated form values on submission | | `open` | Required | `boolean` | - | Controls whether the dialog is visible | | `roles` | Required | `RoleOption[]` | - | List of assignable roles rendered in the role select drop-down | | `isSubmitting` | Optional | `boolean` | `false` | Disables the submit button and shows a loading label while the parent is saving | ### `ChangeConfirmationModal` Generic confirmation modal that shows a diff or summary of pending changes before applying them `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/change-confirmation-modal/change-confirmation-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/change-confirmation-modal/change-confirmation-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `children` | Required | `React.ReactNode` | - | Body content — use to describe the change being confirmed | | `onClose` | Required | `VoidFunction` | - | Called when the user cancels or dismisses the dialog | | `onConfirm` | Required | `VoidFunction` | - | Called when the user clicks the confirm button | | `open` | Required | `boolean` | - | Controls whether the dialog is visible | | `title` | Required | `string` | - | Dialog header title | | `confirmText` | Optional | `string` | `"Confirm"` | [`Label`](/reference/ui/components/forms/#label) for the confirm button | | `destructive` | Optional | `boolean` | `false` | When `true`, the confirm button uses the danger variant | ### `FeatureFlagsSettings` Settings panel listing every feature flag with per-flag enable/disable toggle and description `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/feature-flags/feature-flags-settings.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/feature-flags/feature-flags-settings.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `featureFlags` | Required | `Record` | - | Current flag values keyed by flag name | | `isEditingEnabled` | Required | `boolean` | - | Whether editing is permitted | | `onSave` | Required | `(flags: Record) => void` | - | Called with updated flags when saved | | `className` | Optional | `string` | - | Additional CSS class | | `isLoading` | Optional | `boolean` | `false` | Show loading state | | `isSaving` | Optional | `boolean` | `false` | Show saving spinner on save button | ### `HeaderControlsSettings` Settings panel for the global app header — toggle controls, sticky behaviour, and theme defaults `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/header-controls/header-controls-settings.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/header-controls/header-controls-settings.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onReset` | Required | `VoidFunction` | - | Reset all preferences to defaults | | `onToggle` | Required | `(key: keyof HeaderPreferences, value: boolean) => void` | - | Called when a preference toggle changes | | `preferences` | Required | `HeaderPreferences` | - | Current header preference values | | `className` | Optional | `string` | - | Additional CSS class | | `isLoading` | Optional | `boolean` | `false` | Show loading state | ### `ImportExportSettings` Settings panel for exporting site configuration as JSON and importing a previously saved snapshot `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/import-export/import-export-settings.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/import-export/import-export-settings.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onExport` | Required | `VoidFunction` | - | Trigger configuration export | | `onImport` | Required | `(data: SettingsExportData) => void` | - | Apply imported configuration | | `className` | Optional | `string` | - | Additional CSS class | | `isExporting` | Optional | `boolean` | `false` | Show export loading state | | `isImporting` | Optional | `boolean` | `false` | Show import loading state | | `onParseFile` | Optional | `((file: File) => Promise)` | - | Custom file-parsing function | ### `ManageUserModal` Modal for editing an existing user's role, status, or team membership `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/manage-user-modal/manage-user-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/manage-user-modal/manage-user-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onClose` | Required | `VoidFunction` | - | Called when the dialog closes | | `onSubmit` | Required | `(data: { id: string; name: string; email: string; role: string; }) => Promise` | - | Save handler | | `open` | Required | `boolean` | - | Controls dialog visibility | | `permissionLabels` | Required | `Record` | - | Display labels for permission keys | | `rolePermissions` | Required | `Record>` | - | Permission levels per role | | `roles` | Required | `RoleOption[]` | - | Available role options | | `user` | Required | `SettingsUser` | - | The user being edited | | `isSubmitting` | Optional | `boolean` | `false` | Show loading on submit button | ### `RBACControlSettings` Settings panel listing roles and their permissions; supports editing role-permission grants `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/rbac-control/rbac-control-settings.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/rbac-control/rbac-control-settings.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `canWrite` | Required | `boolean` | - | Whether the current user may edit access settings | | `onCreateUser` | Required | `(data: { name: string; email: string; role: string; }) => Promise` | - | Create a new user | | `onDeleteUser` | Required | `(userId: string) => Promise` | - | Delete a user | | `onUpdateUser` | Required | `(data: { id: string; name: string; email: string; role: string; }) => Promise` | - | Update an existing user's role | | `permissionLabels` | Required | `Record` | - | Display labels for permission keys | | `rolePermissions` | Required | `Record>` | - | Permission levels per role | | `roles` | Required | `RoleOption[]` | - | Available role options | | `users` | Required | `SettingsUser[]` | - | List of current users | | `className` | Optional | `string` | - | Additional CSS class | | `isLoading` | Optional | `boolean` | `false` | Show loading state | ### `SettingsDashboard` Top-level settings landing page — composes the per-section settings cards in a single grid `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/settings-dashboard/settings-dashboard.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/settings/settings-dashboard/settings-dashboard.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Additional CSS class | | `dangerActions` | Optional | `ActionButtonProps[]` | - | Danger-zone action buttons (reset, delete) | | `featureFlagsProps` | Optional | `FeatureFlagsSettingsProps` | - | Props forwarded to [`FeatureFlagsSettings`](/reference/ui/components/settings/#featureflagssettings) | | `headerControlsProps` | Optional | `HeaderControlsSettingsProps` | - | Props forwarded to [`HeaderControlsSettings`](/reference/ui/components/settings/#headercontrolssettings) | | `importExportProps` | Optional | `ImportExportSettingsProps` | - | Props forwarded to [`ImportExportSettings`](/reference/ui/components/settings/#importexportsettings) | | `rbacControlProps` | Optional | `RBACControlSettingsProps` | - | Props forwarded to [`RBACControlSettings`](/reference/ui/components/settings/#rbaccontrolsettings) | | `showFeatureFlags` | Optional | `boolean` | `false` | Whether to show the feature-flags section | # Table (/reference/ui/components/tables) Components for displaying and interacting with tabular data. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit ### Data table ```tsx ``` Sortable, paginated, optionally selectable / expandable table built on TanStack React Table. Controlled and uncontrolled modes for each piece of state. #### Props (subset) > Props are generated from this component's TypeScript types, the source of truth. The following are supplementary (object-prop shapes, allowed values, or passthrough props), not the full prop list. | Prop | Status | Type | Default | Description | | ------------------------- | -------- | ----------------------------------------- | ------- | --------------------------------------- | | `data` | Required | `I[]` | — | Rows | | `columns` | Required | `DataTableColumnDef[]` | — | TanStack column defs | | `fullWidth` | Optional | `boolean` | `true` | Stretch to container width | | `enableRowSelection` | Optional | `boolean \| ((row) => boolean)` | `false` | Checkbox column | | `enableMultiRowSelection` | Optional | `boolean` | `true` | Allow multi-select | | `selections` | Optional | `DataTableRowSelectionState` | — | Controlled row-selection state | | `onSelectionsChange` | Optional | `(s: DataTableRowSelectionState) => void` | — | Setter | | `enablePagination` | Optional | `boolean` | `true` | Show pagination footer | | `pagination` | Optional | `DataTablePaginationState` | — | Controlled pagination | | `sorting` | Optional | `DataTableSortingState` | — | Controlled sorting | | `bordered` | Optional | `boolean` | `false` | Add cell borders | | `loading` | Optional | `boolean` | `false` | Show loading overlay | | `enableRowExpansion` | Optional | `boolean` | `false` | Show row expansion column | | `renderExpandedContent` | Optional | `(row) => ReactNode` | — | Required when row expansion is enabled | | `getRowId` | Optional | `(row, index, parent?) => string` | index | Stable row ID source | | `onRowClick` | Optional | `(rowData: I) => void` | — | Makes rows interactive (see note below) | See [`data-table.tsx`](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/data-table/data-table.tsx) for the full list (16 props). > [!NOTE] > Setting `onRowClick` makes every body row `role="button"`, focusable, and keyboard-activatable > (Enter/Space). Clicks starting inside a `button`, `a`, `input`, `label`, `[role="checkbox"]`, or > anything marked `data-no-row-click` are ignored, so the selection checkbox and expand toggle keep > working independently of the row click. ### Column `meta` | Field | Applied by `DataTable` | Description | | ------- | ---------------------- | -------------------------------------- | | `align` | Yes | `left` \| `center` \| `right` on cells | #### Data contracts `DataTableColumnDef`, `DataTableRow`, `DataTableSortingState`, `DataTablePaginationState`, `DataTableRowSelectionState`, `DataTableExpandedState` are re-exported from `@tetherto/mdk-react-devkit`. #### Example [#data-table-example] ```tsx /** * Runnable example for DataTable. / type Miner = { id: string status: 'online' | 'warning' | 'offline' hashrate: number power_w: number } const data: Miner[] = [ { id: 'miner-01', status: 'online', hashrate: 102.4, power_w: 3200 }, { id: 'miner-02', status: 'warning', hashrate: 95.1, power_w: 3450 }, { id: 'miner-03', status: 'offline', hashrate: 0, power_w: 0 }, ] const columns: DataTableColumnDef[] = [ { accessorKey: 'id', header: 'Miner' }, { accessorKey: 'status', header: 'Status' }, { accessorKey: 'hashrate', header: 'Hashrate (TH/s)' }, { accessorKey: 'power_w', header: 'Power (W)' }, ] return data={data} columns={columns} getRowId={(row) => row.id} /> } ``` #### Related API - [`useExplorerData`](/reference/ui/hooks/tables/#useexplorerdata) @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `AlertConfirmationModal` Modal that confirms acknowledging or clearing one or more alerts before applying the change `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/current-alerts/alert-confirmation-modal/alert-confirmation-modal.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/current-alerts/alert-confirmation-modal/alert-confirmation-modal.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isOpen` | Required | `boolean` | - | Controls dialog visibility | | `onOk` | Required | `VoidFunction` | - | Called when the user confirms the action | ### `Alerts` Full alerts page — combines the searchable current-alerts table, an optional historical-alerts log section, severity filters, and the sound confirmation modal. Wraps [`CurrentAlerts`](/reference/ui/components/tables/#currentalerts) and [`HistoricalAlerts`](/reference/ui/components/tables/#historicalalerts) and coordinates their shared filter / date-range / selected-id state. Must be rendered inside `` — the embedded tables read tag filters from the devices store and use the timezone formatter hook `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/alerts/alerts/alerts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/alerts/alerts/alerts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Extra class on the page wrapper | | `dateRange` | Optional | `HistoricalAlertsRange` | `last 14 days` | Controlled date range for the historical alerts. Defaults to last 14 days | | `devices` | Optional | `Device[]` | - | Devices powering the "Current [`Alerts`](/reference/ui/components/tables/#alerts)" table — a flat list of rows that carry `last.alerts`. Any backend that can produce that shape works; there is no response envelope to reproduce | | `header` | Optional | `React.ReactNode` | - | Optional header (e.g. breadcrumbs) rendered above the alerts | | `historicalAlerts` | Optional | `Alert[]` | - | Pre-fetched historical alerts log entries | | `initialSeverity` | Optional | `string` | - | Initial severity selection (typically derived from `?severity=` URL param) | | `isCurrentAlertsLoading` | Optional | `boolean` | `false` | Loading flag for the "Current [`Alerts`](/reference/ui/components/tables/#alerts)" table | | `isDemoMode` | Optional | `boolean` | `false` | When true, sound notifications are skipped (e.g. demo / preview) | | `isHistoricalAlertsEnabled` | Optional | `boolean` | `false` | When true, shows the "Historical [`Alerts`](/reference/ui/components/tables/#alerts) Log" section. Mirrors the `alertsHistoricalLogEnabled` feature flag in the source app | | `isHistoricalAlertsLoading` | Optional | `boolean` | `false` | Loading flag for the historical log | | `isSoundEnabled` | Optional | `boolean` | `false` | Whether sound notifications are enabled in user preferences | | `onAlertClick` | Optional | `((id?: string \| undefined, uuid?: string \| undefined) => void)` | - | Callback invoked when the operator clicks an alert row. Receives the device id and alert uuid | | `onDateRangeChange` | Optional | `((range: HistoricalAlertsRange) => void)` | - | Called when the operator picks a new historical range | | `selectedAlertId` | Optional | `string` | - | Optional alert id used to focus on a single alert (deep-link from URL) | | `typeFiltersForSite` | Optional | `CascaderOption[]` | - | Optional site-specific overrides for the type filter | ### `AlertsTableTitle` Title strip for an alerts table with the section heading and an optional count badge `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/alerts-table-title/alerts-table-title.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/alerts-table-title/alerts-table-title.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `title` | Required | `React.ReactNode` | - | Section heading | | `className` | Optional | `string` | - | Additional CSS class | | `subtitle` | Optional | `React.ReactNode` | - | Optional subtitle or count badge | ### `CurrentAlerts` Sortable, searchable data table of currently active alerts derived from a raw devices payload. Plays an audible beep when a critical alert is present (gated by `isSoundEnabled` + user confirmation modal) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/current-alerts/current-alerts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/current-alerts/current-alerts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `filterTags` | Required | `string[]` | - | Search tags (controlled). Mirrors the redux `selectFilterTags` slice in the source app | | `localFilters` | Required | `AlertLocalFilters` | - | Filters controlled outside (typically by URL severity param) | | `onFilterTagsChange` | Required | `(tags: string[]) => void` | - | Setter for the tags above | | `onLocalFiltersChange` | Required | `(filters: AlertLocalFilters) => void` | - | Setter for the filters above | | `className` | Optional | `string` | - | Additional class names | | `devices` | Optional | `Device[]` | - | Devices carrying alerts (`last.alerts`), as a flat list. Unwrapping any backend envelope is the data layer's job, not this component's. Shape mirrors the API response from the source app | | `isDemoMode` | Optional | `boolean` | `false` | Skip sound entirely (e.g. in demo/preview environments) | | `isLoading` | Optional | `boolean` | `false` | Show [`DataTable`](/reference/ui/components/tables/#datatable) loading overlay | | `isSoundEnabled` | Optional | `boolean` | `false` | Whether sound notifications are enabled in user preferences (e.g. theme slice) | | `onAlertClick` | Optional | `((id?: string \| undefined, uuid?: string \| undefined) => void)` | - | Click handler when the user opens an alert (right arrow icon in the row) | | `selectedAlertId` | Optional | `string` | - | Optional id used to focus on a single alert (deep-link from URL) | | `typeFiltersForSite` | Optional | `CascaderOption[]` | - | Optional site-specific overrides for the type filter | ### `DataTable` Generic typed data table built on TanStack React Table. Supports pagination, sorting, expansion, row selection and custom column renderers `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/data-table/data-table.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/primitives/components/data-table/data-table.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `columns` | Required | `ColumnDef[]` | - | The column configuration table. See https://tanstack.com/table/v8/docs/guide/column-defs | | `data` | Required | `I[]` | - | The data to be shown in the table. See https://tanstack.com/table/v8/docs/guide/data | | `bordered` | Optional | `boolean` | `false` | Add borders to all cells | | `canRowExpand` | Optional | `((row: Row) => boolean)` | `false` | Callback to check if a row can be expanded | | `contentClassName` | Optional | `string` | - | Classname of the content element | | `defaultSorting` | Optional | `SortingState` | `[]` | Default sorting applied when the table is first mounted (uncontrolled mode). Ignored when `sorting` is provided | | `enableMultiRowSelection` | Optional | `boolean` | `true` | Enables selection of multiple rows | | `enablePagination` | Optional | `boolean` | `true` | Show pagination | | `enableRowExpansion` | Optional | `boolean` | `false` | Show a columns with a button which can expand the row | | `enableRowSelection` | Optional | `boolean \| ((row: Row) => boolean)` | `false` | Show a checkbox column and enables selection | | `expandedRows` | Optional | `ExpandedState` | - | Specify the expanded rows If `undefined`, the expansions are managed internally Object with the key of row ID and a boolean specifying if the row is selected. The default row ID is the index. This can be changed using `getRowId` prop | | `fullWidth` | Optional | `boolean` | `true` | Is table full width | | `getRowId` | Optional | `((row: I, index: number, parent?: Row \| undefined) => string)` | `index` | Get the row ID for a row. If not specified index is the default row ID | | `loading` | Optional | `boolean` | `false` | Show a loading indicator overlay | | `onExpandedRowsChange` | Optional | `((expandedRows: ExpandedState) => void)` | - | Callback to be called when the rows are expanded or collapsed | | `onPaginationChange` | Optional | `((pagination: PaginationState) => void)` | - | Callback to be called when the pagination params change | | `onRowClick` | Optional | `((rowData: I) => void)` | - | Called when a body row is clicked. When set, rows become interactive (pointer cursor, `role="button"`, keyboard-activatable with Enter/Space). Clicks originating from an interactive control in the row (button, link, input, checkbox, or anything marked `data-no-row-click`) are ignored, so the selection checkbox and expand toggle keep working independently | | `onSelectionsChange` | Optional | `((selections: RowSelectionState) => void)` | - | Callback to be called when the row are selected / unselected | | `onSortingChange` | Optional | `((sorting: SortingState) => void)` | - | Callback to be called when the sorting changes | | `pagination` | Optional | `PaginationState` | `undefined` | Specify the pagination params. Object of shape { pageIndex: number, pageSize: number }. If `undefined` then the pagination is managed internally | | `renderExpandedContent` | Optional | `((row: Row) => React.ReactNode)` | - | Render the content of the expanded row. Required when `enableRowExpansion` is `true` | | `selections` | Optional | `RowSelectionState` | `undefined` | Specify the selected rows. If `undefined`, the selections are managed internally Object with the key of row ID and a boolean specifying if the row is selected. The default row ID is the index. This can be changed using `getRowId` prop | | `sorting` | Optional | `SortingState` | `undefined` | Specify the sorting params. If `undefined` then the sorting is managed internally | | `tableClassName` | Optional | `string` | - | Classname of the table element | | `wrapperClassName` | Optional | `string` | - | Classname of the wrapper element | ### `DeviceExplorer` Top-level device explorer: filter toolbar + searchable, sortable table of miners, containers, or cabinets. Designed to be controlled by URL state in the host app `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/device-explorer/device-explorer.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/device-explorer/device-explorer.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `Device[]` | - | Rows | | `deviceType` | Required | `"container" \| "miner" \| "cabinet"` | - | Active device-type tab | | `filterOptions` | Required | `DeviceExplorerFilterOption[]` | - | Filter category definitions | | `getFormattedDate` | Required | `(date: Date) => string` | - | Date formatter from the host's timezone setup | | `onDeviceTypeChange` | Required | `(type: DeviceExplorerDeviceType) => void` | - | Setter for the device type | | `onFiltersChange` | Required | `(value: LocalFilters) => void` | - | Setter for filters | | `onSearchTagsChange` | Required | `(tags: string[]) => void` | - | Setter for search tags | | `renderAction` | Required | `(device: Device) => React.ReactNode` | - | Renderer for the per-row action cell | | `searchOptions` | Required | `DeviceExplorerSearchOption[]` | - | Searchable column definitions | | `searchTags` | Required | `string[]` | - | Active search-tag chips | | `className` | Optional | `string` | - | Additional class names | | `filters` | Optional | `LocalFilters` | - | Controlled filter values | | `onRowClick` | Optional | `((device: Device) => void)` | - | Called when a row is clicked (e.g. to open the device's detail page) | | `onSelectedDevicesChange` | Optional | `((selections: RowSelectionState) => void)` | - | Setter for row selection | | `onSortingChange` | Optional | `((sorting: SortingState) => void)` | - | - | | `selectedDevices` | Optional | `RowSelectionState` | - | Controlled row-selection state | ### `EfficiencyMinerTypeView` Efficiency drilldown grouped by miner model — J/TH and uptime for each model in the fleet `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/efficiency/tabs/miner-type-view/miner-type-view.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/efficiency/tabs/miner-type-view/miner-type-view.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartInput` | Optional | `ToBarChartDataInput` | `{ series: [] }` | Bar chart series data | | `isEmpty` | Optional | `boolean` | `false` | Shows the empty state instead of the chart | | `isLoading` | Optional | `boolean` | `false` | Loading state | | `onTimeFrameChange` | Optional | `((start: Date, end: Date) => void)` | - | Fired when the time-frame selector changes | ### `EfficiencyMinerUnitView` Efficiency drilldown by individual miner serial — outliers and worst-performers surface here `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/efficiency/tabs/miner-unit-view/miner-unit-view.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/efficiency/tabs/miner-unit-view/miner-unit-view.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartInput` | Optional | `ToBarChartDataInput` | `{ series: [] }` | Bar chart series data | | `isEmpty` | Optional | `boolean` | `false` | Shows the empty state instead of the chart | | `isLoading` | Optional | `boolean` | `false` | Loading state | | `onTimeFrameChange` | Optional | `((start: Date, end: Date) => void)` | - | Fired when the time-frame selector changes | ### `EfficiencySiteView` Site-level efficiency view — site-aggregate J/TH, uptime, and capacity utilisation cards `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/efficiency/tabs/site-view/site-view.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/efficiency/tabs/site-view/site-view.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `avgEfficiency` | Optional | `number \| null` | `null` | Average efficiency value | | `dateRange` | Optional | `EfficiencyDateRange` | - | Selected date range | | `isLoading` | Optional | `boolean` | `false` | Loading state | | `log` | Optional | `MetricsEfficiencyLogEntry[]` | `[]` | Efficiency log entries | | `nominalValue` | Optional | `number \| null` | `null` | Nominal target efficiency | | `onDateRangeChange` | Optional | `((range: EfficiencyDateRange) => void)` | - | Date range change handler | | `onReset` | Optional | `VoidFunction` | - | Reset handler | ### `HistoricalAlerts` Sortable data table of historical alerts within a controlled date range. Renders a header with title + [`DateRangePicker`](/reference/ui/components/forms/#daterangepicker), then the table `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/historical-alerts/historical-alerts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/historical-alerts/historical-alerts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `dateRange` | Required | `HistoricalAlertsRange` | - | Selected date range for the historical query (controlled) | | `filterTags` | Required | `string[]` | - | Shared with [`CurrentAlerts`](/reference/ui/components/tables/#currentalerts) | | `localFilters` | Required | `AlertLocalFilters` | - | Filters and search tags coming from the parent (typically shared with [`CurrentAlerts`](/reference/ui/components/tables/#currentalerts)) | | `onDateRangeChange` | Required | `(range: HistoricalAlertsRange) => void` | - | Setter for the date range | | `alerts` | Optional | `Alert[]` | `[]` | Pre-fetched historical alerts log entries (each with a `thing` device payload) | | `className` | Optional | `string` | - | Additional class names | | `isLoading` | Optional | `boolean` | `false` | Show [`DataTable`](/reference/ui/components/tables/#datatable) loading overlay | | `onAlertClick` | Optional | `((id?: string \| undefined, uuid?: string \| undefined) => void)` | - | Called when the user opens an alert | ### `OperationsEfficiency` Top-level operations-efficiency section of the report — composes the site/type/unit views `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/efficiency/efficiency.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/operational/efficiency/efficiency.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `defaultTab` | Optional | `"site-view" \| "miner-type-view" \| "mining-unit-view"` | `"site-view"` | Initially selected tab | | `minerTypeView` | Optional | `EfficiencyMinerTypeViewProps` | - | Props forwarded to [`EfficiencyMinerTypeView`](/reference/ui/components/tables/#efficiencyminertypeview) | | `minerUnitView` | Optional | `EfficiencyMinerUnitViewProps` | - | Props forwarded to [`EfficiencyMinerUnitView`](/reference/ui/components/tables/#efficiencyminerunitview) | | `siteView` | Optional | `EfficiencySiteViewProps` | - | Props forwarded to [`EfficiencySiteView`](/reference/ui/components/tables/#efficiencysiteview) | ### `PoolManagerMinerExplorer` Pool-manager miner explorer page — searchable / filterable table of miners with multi-select and an "Assign Pool" bulk action. Submits the chosen pool change as a pending action via the adapter actions store, then opens a confirmation modal. Must be rendered inside `` — the page uses `useActions`, `useCheckPerm`, and `useContextualModal` from `@tetherto/mdk-react-adapter` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/pool-manager/miner-explorer/pool-manager-miner-explorer.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/pool-manager/miner-explorer/pool-manager-miner-explorer.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `backButtonClick` | Required | `VoidFunction` | - | Called when the operator clicks the "Pool Manager" back link | | `miners` | Required | `ListThingsDevice[]` | - | Miners to render in the explorer table | | `poolConfig` | Required | `PoolConfigEntry[]` | - | Pool configurations powering the "Assign Pool" dropdown | ### `PoolManagerPools` Pool-manager pools page — accordion list of every configured pool with header summary (name, status, priority) and an expandable body (per-pool stats, edit, delete). Optional "Add Pool" CTA is gated by the `ADD_POOL_ENABLED` feature flag. Must be rendered inside `` — the embedded "Add Pool" modal uses the contextual-modal adapter hook `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/pool-manager/pools/pool-manager-pools.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/pool-manager/pools/pool-manager-pools.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `backButtonClick` | Required | `VoidFunction` | - | Called when the operator clicks the "Pool Manager" back link | | `poolConfig` | Required | `PoolConfigEntry[]` | - | Array of pool configurations to render | ### `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. Device data is fetched by the parent and passed in via props — the component does no data fetching itself `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/repairs/repair-log-changes-sub-row.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/repairs/repair-log-changes-sub-row.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `batchAction` | Required | `object` | - | The repair batch action whose part changes should be displayed | | `devices` | Required | `Partial<{ id: string; rack: string; info: Partial<{ serialNum: string; macAddress: string; }>; }>[]` | - | Devices referenced by the batch action, pre-fetched by the parent | | `isLoading` | Optional | `boolean` | `false` | Show a spinner while the parent is still fetching `devices` | ### `TagFilterBar` Horizontal strip of removable tag chips that narrow a list view; clicking a chip removes the filter `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/tag-filter-bar/tag-filter-bar.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/alerts/tag-filter-bar/tag-filter-bar.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `filterTags` | Required | `string[]` | - | Active tag filter values | | `localFilters` | Required | `AlertLocalFilters` | - | Current local filter state | | `onLocalFiltersChange` | Required | `(filters: AlertLocalFilters) => void` | - | Called when any local filter changes | | `onSearchTagsChange` | Required | `(tags: string[]) => void` | - | Called when tag filter changes | | `className` | Optional | `string` | - | Additional CSS class | | `placeholder` | Optional | `string` | - | Search input placeholder | | `typeFiltersForSite` | Optional | `CascaderOption[]` | - | Site-specific overrides for the "type" filter children. If provided, the "Type" filter group will use these instead of the defaults | # Widget (/reference/ui/components/widgets) Widget components for dashboards and data displays. ## 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. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `AddReplaceMinerDialog` Modal for adding a new miner to a slot or swapping the existing one with a replacement unit `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/add-replace-miner-dialog/add-replace-miner-dialog.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/add-replace-miner-dialog/add-replace-miner-dialog.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onClose` | Required | `VoidFunction` | - | Called when the dialog should close | | `open` | Required | `boolean` | - | Controls dialog visibility | | `currentDialogFlow` | Optional | `string` | - | Active flow identifier | | `isDirectToMaintenanceMode` | Optional | `boolean` | `false` | Skip add/replace and go directly to maintenance | | `minersType` | Optional | `string` | - | Miner hardware type filter | | `selectedEditSocket` | Optional | `UnknownRecord` | - | [`Socket`](/reference/ui/components/widgets/#socket) being edited | | `selectedSocketToReplace` | Optional | `UnknownRecord` | - | [`Socket`](/reference/ui/components/widgets/#socket) being replaced | ### `BatchContainerControlsCard` Bulk-controls card that applies start/stop/mode changes to multiple selected containers at once `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/batch-container-controls-card/batch-container-controls-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/batch-container-controls-card/batch-container-controls-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `alarmsDataItems` | Optional | `TimelineItemData[]` | - | Alarm timeline entries to display | | `connectedMiners` | Optional | `unknown` | - | Array of currently connected miners | | `isBatch` | Optional | `boolean` | `true` | Whether in batch (multi-select) mode | | `isCompact` | Optional | `boolean` | - | Compact layout for tighter spaces | | `onNavigate` | Optional | `(path: string) => void` | - | Navigation callback for alarm deep-links | ### `BitdeerOptions` Options panel for a Bitdeer container — exposes vendor-specific operating modes and thresholds. Main container for Bitdeer cooling system options. Displays dry cooler and pumps components `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/bitdeer-options.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/bitdeer-options.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `UnknownRecord` | - | Container settings payload; both components derive state from `cooling_system` fields | ### `BitdeerPumps` Pump telemetry panel for a Bitdeer container showing per-pump RPM, flow, and alert states. Displays exhaust fan status using an indicator `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/bitdeer-pumps.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/bitdeer-pumps.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `UnknownRecord` | - | - | ### `BitdeerSettings` Settings tab for a Bitdeer container — vendor-specific configuration controls and limits. Displays container parameter settings and editable threshold forms for Bitdeer containers with oil temperature and tank pressure monitoring. Includes: - Container parameter display (MAC address, serial number, etc.) - Editable threshold forms for oil temperature and tank pressure - Color-coded alerts and flash indicators - Sound alert configuration `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/bitdeer-settings.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/bitdeer-settings.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `UnknownRecord` | `{}` | Container settings payload from the API | ### `BitdeerTankPressureCharts` Stacked time-series of dielectric tank pressure for a Bitdeer immersion container `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/charts/bitdeer-tank-pressure-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/charts/bitdeer-tank-pressure-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartDataPayload` | Optional | `ChartDataPayload` | - | Declarative chart configuration | | `chartTitle` | Optional | `string` | - | Title shown in the chart header | | `data` | Optional | `UnknownRecord[]` | `[]` | Raw container telemetry entries (with `ts` + nested stats group) | | `dateRange` | Optional | `{ start?: number \| undefined; end?: number \| undefined; }` | - | Custom date range as Unix epoch seconds. Currently unused — accepted by the shared props type but not read by the chart components | | `fixedTimezone` | Optional | `string` | - | IANA timezone for x-axis ticks | | `footer` | Optional | `React.ReactNode` | - | Footer (e.g. min/max/avg stats) | | `height` | Optional | `number` | - | Chart pixel height | | `rangeOptions` | Optional | `{ label: string; value: string; }[]` | `5m/30m/3h/1D` | Override the default range selector options | | `showLegend` | Optional | `boolean` | `true` | Show the toggleable legend | | `showRangeSelector` | Optional | `boolean` | `true` | Show the range selector buttons | | `tag` | Optional | `string` | - | Container tag (any leading prefix is stripped) | | `timeline` | Optional | `string` | `"24h"` | Initial / controlled timeline value | ### `BitdeerTankTempCharts` Tank Temperature Charts for Bitdeer containers Displays oil and water temperature readings (hot and cold) for a specific tank. Features: - Tank Oil TempL (Cold) - Yellow line (4px) - Tank Oil TempH (Hot) - Violet line - Tank Water TempL (Cold) - Blue line - Tank Water TempH (Hot) - Sky Blue line `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/charts/bitdeer-tank-temp-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/charts/bitdeer-tank-temp-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartDataPayload` | Optional | `ChartDataPayload` | - | Declarative chart configuration | | `chartTitle` | Optional | `string` | - | Title shown in the chart header | | `data` | Optional | `UnknownRecord[]` | `[]` | Raw container telemetry entries (with `ts` + nested stats group) | | `dateRange` | Optional | `{ start?: number \| undefined; end?: number \| undefined; }` | - | Custom date range as Unix epoch seconds. Currently unused — accepted by the shared props type but not read by the chart components | | `fixedTimezone` | Optional | `string` | - | IANA timezone for x-axis ticks | | `footer` | Optional | `React.ReactNode` | - | Footer (e.g. min/max/avg stats) | | `height` | Optional | `number` | - | Chart pixel height | | `rangeOptions` | Optional | `{ label: string; value: string; }[]` | `5m/30m/3h/1D` | Override the default range selector options | | `showLegend` | Optional | `boolean` | `true` | Show the toggleable legend | | `showRangeSelector` | Optional | `boolean` | `true` | Show the range selector buttons | | `tag` | Optional | `string` | - | Container tag (any leading prefix is stripped) | | `tankNumber` | Optional | `string \| number` | `1` | Tank number (1 or 2) | | `timeline` | Optional | `string` | `"24h"` | Initial / controlled timeline value | ### `BitMainBasicSettings` General settings form for a BitMain container — naming, location, and power limits. Main settings view displaying: - Cooling system status (pumps and fans) - Power distribution - GPS positioning `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/status-item/settings/bitmain-basic-settings.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/status-item/settings/bitmain-basic-settings.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `Device` | - | Container data | ### `BitMainControlsTab` Read-only status tab for a BitMain container: fan status, tank levels, and GPS location. Displays container controls including: - Container fan status - Tank levels (A, B, C, D) - GPS location (latitude/longitude) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/controls-tab/bitmain-immersion-controls-tab.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/controls-tab/bitmain-immersion-controls-tab.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `Device` | - | Device data | ### `BitMainCoolingSystem` Cooling subsystem panel for a BitMain container — pumps, fans, and dry-cooler status. Displays the status of cooling system components including: - Circulating pump - Fluid infusion pump - Fans (1-2) - Cooling tower fans (1-3) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/status-item/settings/cooling-system/bitmain-cooling-system.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/status-item/settings/cooling-system/bitmain-cooling-system.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `Device` | - | Container data | ### `BitMainHydroLiquidTemperatureCharts` Time-series charts of dielectric liquid temperature for a BitMain hydro-cooled container. Displays secondary liquid supply temperature readings (Temp1 and Temp2) for Bitmain Hydro containers. Features: - Sec. Liquid supply Temp1 - Sky Blue line - Sec. Liquid supply Temp2 - Violet line - Interactive legend for toggling series - Timeline selector (1h, 6h, 24h, 7d, 30d) - Current temperature display `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-hydro-liquid-temperature-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-hydro-liquid-temperature-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartDataPayload` | Optional | `ChartDataPayload` | - | Declarative chart configuration | | `chartTitle` | Optional | `string` | - | Title shown in the chart header | | `data` | Optional | `UnknownRecord[]` | `[]` | Raw container telemetry entries (with `ts` + nested stats group) | | `dateRange` | Optional | `{ start?: number \| undefined; end?: number \| undefined; }` | - | Custom date range as Unix epoch seconds. Currently unused — accepted by the shared props type but not read by the chart components | | `fixedTimezone` | Optional | `string` | - | IANA timezone for x-axis ticks | | `footer` | Optional | `React.ReactNode` | - | Footer (e.g. min/max/avg stats) | | `height` | Optional | `number` | - | Chart pixel height | | `rangeOptions` | Optional | `{ label: string; value: string; }[]` | `5m/30m/3h/1D` | Override the default range selector options | | `showLegend` | Optional | `boolean` | `true` | Show the toggleable legend | | `showRangeSelector` | Optional | `boolean` | `true` | Show the range selector buttons | | `tag` | Optional | `string` | - | Container tag (any leading prefix is stripped) | | `timeline` | Optional | `string` | `"24h"` | Initial / controlled timeline value | ### `BitMainHydroSettings` Settings form for a BitMain hydro-cooled container; flow, temperature, and pump configuration. Main settings view for BitMain Hydro containers displaying: - Basic settings (cooling system, power, positioning) - Threshold configuration forms (water temperature, pressure) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/bitmain-hydro-settings.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/bitmain-hydro-settings.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `Device` | - | Device data | ### `BitMainImmersionControlBox` Control box for a BitMain immersion container exposing tank, pump, and unit-level actions. A flexible container component with configurable columns and optional bottom content. Used for displaying control information in a structured layout `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/control-box/bitmain-immersion-control-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/control-box/bitmain-immersion-control-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `bottomContent` | Optional | `React.ReactNode` | - | Content for bottom row | | `className` | Optional | `string` | - | Custom className | | `leftContent` | Optional | `React.ReactNode` | - | Content for left column | | `rightContent` | Optional | `React.ReactNode` | - | Content for right column | | `secondary` | Optional | `boolean` | `false` | Secondary variant (no border) | | `title` | Optional | `string` | - | Box title | ### `BitMainImmersionPumpStationControlBox` Pump-station control card for a BitMain immersion container with per-pump enable/disable. Displays pump station status including: - Alarm/Normal status - Ready state - Operating state - Started state `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/pump-station/bitmain-immersion-pump-station-control-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/pump-station/bitmain-immersion-pump-station-control-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `alarmStatus` | Optional | `boolean` | `false` | Alarm/fault status | | `className` | Optional | `string` | - | Custom className | | `operation` | Optional | `boolean` | - | Operation status | | `ready` | Optional | `boolean` | - | Ready status | | `start` | Optional | `boolean` | - | Start status | | `title` | Optional | `string` | - | Box title | ### `BitMainImmersionSettings` Settings form for a BitMain immersion container — tank thresholds, pump curves, and limits. Settings form for BitMain immersion containers with temperature threshold configuration `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/bitmain-immersion-settings.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/bitmain-immersion-settings.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `containerSettings` | Optional | `{ thresholds?: Record \| undefined; } \| null` | `null` | Container settings with custom thresholds | | `data` | Optional | `Device` | - | Device data | ### `BitMainImmersionSummaryBox` Summary card for a BitMain immersion-cooled container: temps, pumps, power, and overall status `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/bitmain-immersion-summary-box/bitmain-immersion-summary-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/bitmain-immersion-summary-box/bitmain-immersion-summary-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `containerSettings` | Optional | `BitMainImmersionSummaryBoxContainerSettings \| null` | `null` | Optional threshold configuration that drives colour/flash states on temperature stats | | `data` | Optional | `Device` | - | Live device object from the devices store. Returns `null` when omitted | ### `BitMainImmersionSystemStatus` Aggregated system-status card for a BitMain immersion container; rolls up subsystem health. Displays system status information including: - Server start permission - Connection status `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/system-status/bitmain-immersion-system-status.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/system-status/bitmain-immersion-system-status.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `Device` | - | Device data | ### `BitMainImmersionUnitControlBox` Per-unit control card inside a BitMain immersion container with start/stop and reset actions `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/unit-control-box/bitmain-immersion-unit-control-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain-immersion/unit-control-box/bitmain-immersion-unit-control-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `alarmStatus` | Optional | `boolean` | `false` | Alarm/fault status | | `className` | Optional | `string` | - | Custom className | | `frequency` | Optional | `number` | - | Frequency value in Hz | | `isDryCooler` | Optional | `boolean` | `false` | Whether this is a dry cooler unit | | `running` | Optional | `boolean` | `false` | Whether the unit is running | | `secondary` | Optional | `boolean` | `false` | Secondary variant (no border) | | `showFrequencyInLeftColumn` | Optional | `boolean` | `false` | Show frequency in left column instead of right | | `title` | Optional | `string` | - | Box title | ### `BitMainLiquidPressureCharts` Time-series charts of dielectric liquid pressure across a BitMain immersion container. Displays supply and return liquid pressure readings for Bitmain containers. Converts pressure values from MPa to bar for display. Features: - Supply Liquid Pressure - Sky Blue line - Return Liquid Pressure - Violet line - Automatic MPa to bar conversion - Interactive legend for toggling series - Timeline selector (1h, 6h, 24h, 7d, 30d) - Current pressure display `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-liquid-pressure-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-liquid-pressure-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartDataPayload` | Optional | `ChartDataPayload` | - | Declarative chart configuration | | `chartTitle` | Optional | `string` | - | Title shown in the chart header | | `data` | Optional | `UnknownRecord[]` | `[]` | Raw container telemetry entries (with `ts` + nested stats group) | | `dateRange` | Optional | `{ start?: number \| undefined; end?: number \| undefined; }` | - | Custom date range as Unix epoch seconds. Currently unused — accepted by the shared props type but not read by the chart components | | `fixedTimezone` | Optional | `string` | - | IANA timezone for x-axis ticks | | `footer` | Optional | `React.ReactNode` | - | Footer (e.g. min/max/avg stats) | | `height` | Optional | `number` | - | Chart pixel height | | `rangeOptions` | Optional | `{ label: string; value: string; }[]` | `5m/30m/3h/1D` | Override the default range selector options | | `showLegend` | Optional | `boolean` | `true` | Show the toggleable legend | | `showRangeSelector` | Optional | `boolean` | `true` | Show the range selector buttons | | `tag` | Optional | `string` | - | Container tag (any leading prefix is stripped) | | `timeline` | Optional | `string` | `"24h"` | Initial / controlled timeline value | ### `BitMainLiquidTempCharts` Time-series charts of dielectric liquid temperature across a BitMain immersion container. Displays supply and return liquid temperature readings for Bitmain containers. Features: - Supply Liquid Temp - Sky Blue line - Return Liquid Temp - Violet line - Interactive legend for toggling series - Timeline selector (1h, 6h, 24h, 7d, 30d) - Current temperature display `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-liquid-temp-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-liquid-temp-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartDataPayload` | Optional | `ChartDataPayload` | - | Declarative chart configuration | | `chartTitle` | Optional | `string` | - | Title shown in the chart header | | `data` | Optional | `UnknownRecord[]` | `[]` | Raw container telemetry entries (with `ts` + nested stats group) | | `dateRange` | Optional | `{ start?: number \| undefined; end?: number \| undefined; }` | - | Custom date range as Unix epoch seconds. Currently unused — accepted by the shared props type but not read by the chart components | | `fixedTimezone` | Optional | `string` | - | IANA timezone for x-axis ticks | | `footer` | Optional | `React.ReactNode` | - | Footer (e.g. min/max/avg stats) | | `height` | Optional | `number` | - | Chart pixel height | | `rangeOptions` | Optional | `{ label: string; value: string; }[]` | `5m/30m/3h/1D` | Override the default range selector options | | `showLegend` | Optional | `boolean` | `true` | Show the toggleable legend | | `showRangeSelector` | Optional | `boolean` | `true` | Show the range selector buttons | | `tag` | Optional | `string` | - | Container tag (any leading prefix is stripped) | | `timeline` | Optional | `string` | `"24h"` | Initial / controlled timeline value | ### `BitMainPowerAndPositioning` Power and physical-positioning settings for a BitMain container — circuits, phases, and rack slots. Displays power distribution and GPS location information: - Distribution box #1 and #2 power consumption - Latitude and longitude coordinates with direction `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/status-item/settings/power-and-positioning/bitmain-power-and-positioning.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/status-item/settings/power-and-positioning/bitmain-power-and-positioning.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `Device` | - | Container data | ### `BitMainPowerCharts` Time-series charts of per-phase power, voltage, and current draw for a BitMain container. Displays power consumption for Bitmain containers with distribution boxes. Shows total power and individual power for each distribution box. Automatically calculates total power from the sum of both boxes and formats the display units (kW/MW) based on the power magnitude. Features: - Total Power - Sky Blue line (sum of both boxes) - Dist. Box 1 Power - Violet line - Dist. Box 2 Power - Red line - Interactive legend for toggling series - Timeline selector (1h, 6h, 24h, 7d, 30d) - Current power consumption display with auto unit (W/kW/MW) - Automatic kW to W conversion for chart display `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-power-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-power-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartDataPayload` | Optional | `ChartDataPayload` | - | Declarative chart configuration | | `chartTitle` | Optional | `string` | - | Title shown in the chart header | | `data` | Optional | `UnknownRecord[]` | `[]` | Raw container telemetry entries (with `ts` + nested stats group) | | `dateRange` | Optional | `{ start?: number \| undefined; end?: number \| undefined; }` | - | Custom date range as Unix epoch seconds. Currently unused — accepted by the shared props type but not read by the chart components | | `fixedTimezone` | Optional | `string` | - | IANA timezone for x-axis ticks | | `footer` | Optional | `React.ReactNode` | - | Footer (e.g. min/max/avg stats) | | `height` | Optional | `number` | - | Chart pixel height | | `rangeOptions` | Optional | `{ label: string; value: string; }[]` | `5m/30m/3h/1D` | Override the default range selector options | | `showLegend` | Optional | `boolean` | `true` | Show the toggleable legend | | `showRangeSelector` | Optional | `boolean` | `true` | Show the range selector buttons | | `tag` | Optional | `string` | - | Container tag (any leading prefix is stripped) | | `timeline` | Optional | `string` | `"24h"` | Initial / controlled timeline value | ### `BitMainSupplyLiquidFlowCharts` Time-series charts of supply-side coolant flow rates for a BitMain immersion container. Displays supply liquid flow rate for Bitmain containers in cubic meters per hour (m³/h). Features: - Supply Liquid Flow - Sky Blue line - Interactive timeline selector (1h, 6h, 24h, 7d, 30d) - Current flow rate display - Optional legend and range selector `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-supply-liquid-flow-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/charts/bitmain-supply-liquid-flow-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `chartDataPayload` | Optional | `ChartDataPayload` | - | Declarative chart configuration | | `chartTitle` | Optional | `string` | - | Title shown in the chart header | | `data` | Optional | `UnknownRecord[]` | `[]` | Raw container telemetry entries (with `ts` + nested stats group) | | `dateRange` | Optional | `{ start?: number \| undefined; end?: number \| undefined; }` | - | Custom date range as Unix epoch seconds. Currently unused — accepted by the shared props type but not read by the chart components | | `fixedTimezone` | Optional | `string` | - | IANA timezone for x-axis ticks | | `footer` | Optional | `React.ReactNode` | - | Footer (e.g. min/max/avg stats) | | `height` | Optional | `number` | - | Chart pixel height | | `rangeOptions` | Optional | `{ label: string; value: string; }[]` | `5m/30m/3h/1D` | Override the default range selector options | | `showLegend` | Optional | `boolean` | `true` | Show the toggleable legend | | `showRangeSelector` | Optional | `boolean` | `true` | Show the range selector buttons | | `tag` | Optional | `string` | - | Container tag (any leading prefix is stripped) | | `timeline` | Optional | `string` | `"24h"` | Initial / controlled timeline value | ### `ContainerCharts` Tabbed chart panel showing per-container hashrate, power, and temperature time series `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/container-charts/container-charts.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/container-charts/container-charts.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `combinations` | Required | `ContainerChartCombinationOption[]` | - | Options for the combination selector | | `chartRawData` | Optional | `ChartEntry[] \| null` | `null` | Raw overview stats rows passed to chart adapters | | `defaultSelectedCombination` | Optional | `string \| null` | `null` | Initial selection when uncontrolled | | `disabledMessage` | Optional | `string` | `"Container Charts feature is not enabled"` | Message when `featureEnabled` is false | | `featureEnabled` | Optional | `boolean` | `true` | When false, shows an empty state (feature gate) | | `getDatasetBorderColor` | Optional | `ContainerChartsDatasetBorderColorResolver` | - | Optional per-dataset line colors after adapters run (e.g. demo or host branding) | | `isLoadingCharts` | Optional | `boolean` | `false` | Loading state for the chart panels | | `isLoadingCombinations` | Optional | `boolean` | `false` | Loading state for combination options | | `onSelectedCombinationChange` | Optional | `((value: string \| null) => void)` | - | Called when the selected combination changes | | `selectedCombination` | Optional | `string \| null` | - | Controlled selected combination value | | `title` | Optional | `string` | `"Container Charts"` | Section heading | ### `ContainerControlsBox` Control panel for a single container — start/stop, mode select, and operator actions `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/container-controls-box/container-controls-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/container-controls-box/container-controls-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onNavigate` | Required | `(path: string) => void` | - | Navigation callback used by alarm row click-throughs | | `alarmsDataItems` | Optional | `TimelineItemData[]` | `[]` | Active alarm feed items to display inline | | `data` | Optional | `Device` | - | The container device object | | `isBatch` | Optional | `boolean` | `false` | When `true`, operates on `selectedDevices` instead of a single `data` record | | `isCompact` | Optional | `boolean` | - | - | | `pendingSubmissions` | Optional | `PendingSubmission[]` | `[]` | In-flight command queue; disables conflicting actions | | `powerModesLog` | Optional | `UnknownRecord` | - | - | | `selectedDevices` | Optional | `Device[]` | `[]` | Devices included in a batch operation | | `tailLogData` | Optional | `UnknownRecord[]` | - | Recent log tail entries | ### `ContainerControlsCard` Per-socket controls card for the container detail view: powers the selected miner sockets on/off and shows their aggregate power / current. Reads the selected sockets from the devices store (populated by `deriveSelectedSockets`) and queues `switchSocket` drafts. Container-level "power all sockets" lives on [`BatchContainerControlsCard`](/reference/ui/components/widgets/#batchcontainercontrolscard); this card drives an explicit socket selection, which the flat Explorer list does not yet surface (a container-PDU grid is the follow-on) — hence `advanced` rather than `agent-ready` `advanced`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/container-controls-card/container-controls-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/container-controls-card/container-controls-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `buttonsStates` | Optional | `ButtonsStates` | - | - | | `isLoading` | Optional | `boolean` | - | - | ### `ContainerFanLegend` Legend strip describing fan states and colours used by the container fans visualisation. Displays a single fan status with number and icon `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/dry-cooler/container-fans-card/container-fans-legend.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/dry-cooler/container-fans-card/container-fans-legend.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Custom className | | `enabled` | Optional | `boolean` | `false` | Running state; controls the icon and colour class | | `index` | Optional | `number \| null` | - | Fan index/number to display | ### `ContainerFansCard` Card displaying the array of cooling fans in a container with live state per fan. Displays a grid of fan status indicators. Shows fan number and on/off state with icon `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/dry-cooler/container-fans-card/container-fans-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/dry-cooler/container-fans-card/container-fans-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `fansData` | Optional | `PumpItem[]` | - | Array of fan state objects. Renders an empty card when the array is empty; returns `null` when absent | ### `ContainerSelectionDialog` Modal that lists containers and lets the operator pick one or many for a follow-up action `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/position-change-dialog/container-selection-dialog/container-selection-dialog.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/position-change-dialog/container-selection-dialog/container-selection-dialog.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onClose` | Required | `(value?: boolean \| undefined) => void` | - | Called when dialog closes | | `open` | Required | `boolean` | - | Controls visibility | | `containers` | Optional | `Device[]` | `[]` | Available target containers | | `isLoading` | Optional | `boolean` | - | Show loading spinner | | `miner` | Optional | `Device` | - | The miner being moved | ### `ContainerWidgetCard` Presentational summary card for a single container in the Site Overview widgets grid: a header row (title / alarms / power), then either an offline / error banner or the body (optional vendor content, a miners summary, and a miner-activity chart). Fully props-driven — no data fetching, formatting, or alarm math. The owning feature/hook shapes every value (including `flash` and `summary`) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/container-widget-card/container-widget-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/container-widget-card/container-widget-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `summary` | Required | `MinersSummaryParam[]` | - | Pre-formatted miners-summary rows (label + display value incl. units) | | `title` | Required | `string` | - | Container display name shown in the header row | | `activity` | Optional | `ContainerActivityData` | `{}` | Miner-state activity counts for the embedded chart | | `activityError` | Optional | `ContainerActivityError` | `null` | Activity chart error payload | | `alarms` | Optional | `Partial>` | - | Per-category alarm badges for the header row | | `className` | Optional | `string` | - | Additional class for the root element | | `errorMessage` | Optional | `string` | - | Container-level error message; renders an error banner instead of the body | | `flash` | Optional | `boolean` | `false` | Critical-high alarm flash. Computed upstream (by the data hook) so the card stays presentational — never derive alarm state inside this component | | `isActivityError` | Optional | `boolean` | `false` | Activity chart error state | | `isActivityLoading` | Optional | `boolean` | `false` | Activity chart loading state | | `isOffline` | Optional | `boolean` | `false` | Render the offline banner instead of the body | | `onClick` | Optional | `(() => void)` | - | Invoked when the card is clicked (navigation is the caller's concern) | | `power` | Optional | `number` | - | Latest container power draw in watts (rendered in kW by the top row) | | `powerUnit` | Optional | `string` | - | Power unit label shown next to the reading | | `statsErrorMessage` | Optional | `string \| ErrorWithTimestamp[] \| null` | - | Raw stats error surfaced as a tooltip in place of the power reading | | `vendorContent` | Optional | `React.ReactNode` | - | Optional vendor-specific content (supply-liquid / tanks / immersion / MicroBT boxes) rendered above the miners summary. Kept as a slot so the generic card carries no per-model branching | ### `CostMetrics` Three "$/MWh" tiles that summarise the cost-summary period. Order mirrors the OSS [`Cost`](/reference/ui/components/dashboards/#cost) page: All-in (highlighted), Energy, Operations `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/cost-metrics.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/reporting-tool/financial/cost/cost-metrics.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `metrics` | Required | `CostSummaryDisplayMetrics` | - | - | ### `DryCooler` Dry-cooler subsystem panel showing inlet/outlet temperatures and fan-stage status. Displays dry cooler status with fans and associated pumps. Shows two cooler groups with fan status indicators and pump controls `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/dry-cooler/dry-cooler.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/dry-cooler/dry-cooler.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `UnknownRecord` | - | Container settings payload. `cooling_system.dry_cooler` is read for fan state; `cooling_system.oil_pump` and `cooling_system.water_pump` are read for pump state | ### `EnabledDisableToggle` [`Switch`](/reference/ui/components/forms/#switch) with confirmation that enables or disables a container, miner, or feature flag `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/enabled-disable-toggle/enabled-disable-toggle.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/enabled-disable-toggle/enabled-disable-toggle.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isButtonDisabled` | Required | `boolean` | - | Disables the Enable/Disable buttons when a command is in-flight | | `isOffline` | Required | `boolean` | - | Disables all controls and shows an offline tooltip | | `onToggle` | Required | `(params: EnabledDisableToggleCbParams) => void` | - | Callback fired when the user confirms a state change | | `tankNumber` | Required | `string \| number` | - | Tank identifier used in the label (`Tank {N} Circulation`). Pass an empty string for the air exhaust label | | `value` | Required | `unknown` | - | Current state. A boolean drives a switch display; non-boolean shows action buttons | ### `ExplorerDetail` Per-type Explorer detail panel. Reads the selection the [`useExplorerSelection`](/reference/ui/hooks/op-center/#useexplorerselection) bridge writes into `devicesStore` and composes the matching cards: - container: [`BatchContainerControlsCard`](/reference/ui/components/widgets/#batchcontainercontrolscard) (batch when >1 selected) with the connected-miner power-mode controls and the active-alarms box, plus [`StatsGroupCard`](/reference/ui/components/widgets/#statsgroupcard) for the connected miners and [`ContainerControlsCard`](/reference/ui/components/widgets/#containercontrolscard) when an explicit per-socket selection exists. - miner: [`MinerControlsCard`](/reference/ui/components/widgets/#minercontrolscard) write controls, [`MinerInfoCard`](/reference/ui/components/widgets/#minerinfocard) read-only info rows, [`MinerChipsCard`](/reference/ui/components/widgets/#minerchipscard) per-chip stats, [`StatsGroupCard`](/reference/ui/components/widgets/#statsgroupcard) aggregate, and the active-alarms box. - cabinet: read-only [`CabinetDetailCard`](/reference/ui/components/cards/#cabinetdetailcard) — powermeter + temperature readings and the LV-cabinet warnings timeline. Writes queue into the actions draft store; submission stays gated behind the [`ActionsSidebar`](/reference/ui/components/dashboards/#actionssidebar) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/explorer/explorer-detail/explorer-detail.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/features/explorer/explorer-detail/explorer-detail.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `deviceType` | Required | `"container" \| "miner" \| "cabinet"` | - | The active Explorer tab — selects which per-type panel renders | | `isCompact` | Optional | `boolean` | `true` | Compact layout for the narrower Explorer detail column | | `onNavigate` | Optional | `((path: string) => void)` | `no-op` | Router navigate used by alarm rows to deep-link into `/alerts/:id` | ### `FireStatusBox` Fire Status Box Component x Displays fire safety and environmental monitoring status `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/fire-status-box/fire-status-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/fire-status-box/fire-status-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `{ smokeDetector: string \| number; waterIngressDetector: string \| number; coolingFanStatus: string \| number; }` | - | Device data | ### `GaugeChartComponent` Single-needle gauge chart used inside container settings for thresholded percentage values. Displays a value as a gauge/speedometer chart with label and unit `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/gauge-chart/gauge-chart-component.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/gauge-chart/gauge-chart-component.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `max` | Required | `number` | - | Maximum value for the gauge | | `unit` | Required | `string` | - | Unit of measurement | | `value` | Required | `number` | - | Current value | | `chartStyle` | Optional | `React.CSSProperties` | `{}` | Custom chart style | | `className` | Optional | `string` | - | Custom className | | `colors` | Optional | `string[]` | `[COLOR.EMERALD, COLOR.SOFT_TEAL]` | Arc colors in HEX format | | `height` | Optional | `number` | `200` | Chart height in pixels | | `hideText` | Optional | `boolean` | `true` | Hide the percentage text inside the chart | | `label` | Optional | `string` | `""` | [`Label`](/reference/ui/components/forms/#label)/title for the chart | ### `GenericDataBox` Reusable labelled stat box used by container summary panels for one-off numeric values. Displays a table of label-value-unit rows `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/generic-data-box/generic-data-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/generic-data-box/generic-data-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `DataItem[]` | `[]` | Array of data items to display | | `fallbackValue` | Optional | `unknown` | - | Fallback value when value is undefined | ### `MaintenanceDialogContent` Body of the maintenance dialog — captures the work-order details before applying the maintenance flag `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/position-change-dialog/maintenance-dialog-content/maintenance-dialog-content.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/position-change-dialog/maintenance-dialog-content/maintenance-dialog-content.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onCancel` | Optional | `VoidFunction` | - | Called when the user cancels | | `selectedEditSocket` | Optional | `Partial` | - | The socket/slot being flagged for maintenance | ### `MicroBTCooling` Cooling subsystem panel for a MicroBT container — pumps, fans, and coolant flow telemetry. Displays cooling system status for MicroBT containers including: - Cycle pump status - Main circulation pump (status, switch, speed) - Cooling fan (status, switch, speed) - Make-up water pump (status, switch, fault) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/cooling/micro-bt-cooling.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/cooling/micro-bt-cooling.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `Device` | - | Device data | ### `MicroBTSettings` Settings form for a MicroBT container with vendor-specific operating limits. Settings form for MicroBT containers with temperature threshold configuration `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/settings/micro-bt-settings.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/settings/micro-bt-settings.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `containerSettings` | Optional | `{ thresholds?: Record \| undefined; } \| null` | `null` | Container settings with custom thresholds | | `data` | Optional | `Device` | - | Device data | ### `MicroBTWidgetBox` Summary card for a MicroBT-equipped container showing pumps, fans, and operating mode `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/micro-bt-widget-box/micro-bt-widget-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/micro-bt-widget-box/micro-bt-widget-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `Device` | - | Live device object. Returns `null` when omitted | ### `MinerChip` Chip representing a single miner; surfaces slot index, temperature, and frequency `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-chips-card/miner-chip/miner-chip.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-chips-card/miner-chip/miner-chip.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `frequency` | Required | `{ current: number; }` | - | Current frequency in MHz | | `index` | Required | `number` | - | Chip slot index | | `temperature` | Required | `{ avg: number; min: number; max: number; }` | - | Temperature readings in °C | ### `MinerChipsCard` Card listing every miner in a container as [``](/reference/ui/components/widgets/#minerchip)s for at-a-glance selection `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-chips-card/miner-chips-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-chips-card/miner-chips-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Required | `ContainerStats` | - | Container stats including chip frequency and temperature arrays | ### `MinerControlsCard` Action card for a single miner: power, reboot, mode select, and maintenance entry points `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-controls-card/miner-controls-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-controls-card/miner-controls-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `buttonsStates` | Required | `Record` | - | Map of action name → loading/disabled state | | `isLoading` | Required | `boolean` | - | Whether the card itself is in a loading state | | `showPowerModeSelector` | Optional | `boolean` | `true` | Show the power-mode selection button | ### `MinerInfoCard` Info card for one miner — serial, model, firmware, location, and recent activity summary `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-info-card/miner-info-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-info-card/miner-info-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `InfoItem[]` | - | Array of label/value pairs to display | | `label` | Optional | `string` | `"Miner info"` | Card heading label | ### `MinerMetricCard` Single-metric card (hashrate, temperature, or power) for one miner with sparkline and delta. Displays key metrics for a miner including: - Efficiency (fixed position top-right) - Hash rate, Temperature - Frequency, Consumption - Optional secondary stats in grid `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-metric-card/miner-metric-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-metric-card/miner-metric-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `primaryStats` | Optional | `StatItem[]` | - | Primary statistics (efficiency, hashrate, temperature, frequency, consumption) | | `secondaryStats` | Optional | `StatItem[]` | - | Secondary statistics to display in grid | | `showSecondaryStats` | Optional | `boolean` | `true` | Whether to show secondary stats section | ### `MinerPowerModeSelectionButtons` Segmented control letting an operator switch a miner between low / normal / turbo power modes `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-power-mode-selection-buttons/miner-power-mode-selection-buttons.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miner-power-mode-selection-buttons/miner-power-mode-selection-buttons.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `connectedMiners` | Optional | `Device[]` | - | Currently connected miners | | `disabled` | Optional | `boolean` | `false` | Disable all buttons | | `hasMargin` | Optional | `boolean` | `false` | Add margin around the button group | | `powerModesLog` | Optional | `UnknownRecord` | - | Log of previous power mode selections | | `selectedDevices` | Optional | `Device[]` | `[]` | Devices to apply the power mode to | | `setPowerMode` | Optional | `((devices: Device[], mode: string) => void)` | - | Callback to apply the selected mode | ### `MinersActivityChart` Per-status miner counts (online / offline / faulted / power-mode). Renders as coloured indicator dots (`indicators`) or tinted status tiles (`tiles`) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miners-activity-chart/miners-activity-chart.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/miners-activity-chart/miners-activity-chart.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `MinersActivityData` | `{}` | Time-series data for online/offline/faulted counts | | `error` | Optional | `MinerActivityChartErrorProp \| null` | `null` | Error details to display | | `isDemoMode` | Optional | `boolean` | `false` | Use demo/mock data | | `isError` | Optional | `boolean` | `false` | Show error state | | `isLoading` | Optional | `boolean` | `false` | Show loading state | | `large` | Optional | `boolean` | `false` | Use tall variant | | `showLabel` | Optional | `boolean` | `true` | Show axis labels | | `variant` | Optional | `"indicators" \| "tiles"` | `"indicators"` | `indicators` (default) renders coloured dots; `tiles` renders tinted status tiles | ### `MinersSummaryBox` Headline card summarising miner counts by state (online, offline, faulted) for one container. Displays mining summary parameters in a 2-column grid layout. Accepts pre-formatted values - consumers handle data formatting `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/miners-summary-box/miners-summary-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/miners-summary-box/miners-summary-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `params` | Required | `MinersSummaryParam[]` | - | Array of label-value pairs to display in a 2-column grid | | `className` | Optional | `string` | - | Additional CSS class name | ### `PositionChangeDialog` Modal that moves a miner to a different rack slot, validating the destination first `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/position-change-dialog/position-change-dialog.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/position-change-dialog/position-change-dialog.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `onClose` | Required | `(currentDialogFlow: string, isDontReset?: boolean \| undefined) => void` | - | Called when dialog closes | | `open` | Required | `boolean` | - | Controls dialog visibility | | `dialogFlow` | Optional | `string` | - | Initial dialog step/flow identifier | | `isContainerEmpty` | Optional | `boolean` | `false` | Whether the target container slot is empty | | `onChangePositionClicked` | Optional | `VoidFunction` | - | Callback when position change is triggered | | `onPositionChangedSuccess` | Optional | `VoidFunction` | - | Callback on successful position change | | `selectedEditSocket` | Optional | `UnknownRecord` | - | [`Socket`](/reference/ui/components/widgets/#socket) being edited | | `selectedSocketToReplace` | Optional | `UnknownRecord` | - | [`Socket`](/reference/ui/components/widgets/#socket) being replaced | ### `PowerMeters` Per-circuit power-meter panel showing live kW, kWh, and power-factor readings. Displays power meter readings for container devices including: - Communication status - Voltage measurements (A-B, B-C, C-A) - Power factor and frequency - Active and apparent power - Energy consumption `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/power-meters/power-meters.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/micro-bt/power-meters/power-meters.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `Device` | - | Device data | ### `PumpBox` Single-pump status card with RPM, flow, and fault state for one immersion-cooling pump `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/pump-box/pump-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitdeer/settings/container-options/pump-box/pump-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `pumpTitle` | Required | `string` | - | [`Label`](/reference/ui/components/forms/#label) prefix for the pump (e.g. `"Circulation"`) | | `pumpItem` | Optional | `PumpItem` | - | Pump data. `index` is 0-based; displayed as `index + 1` | ### `RemoveMinerDialog` Confirmation modal for removing a miner from a slot. Renders nothing when `isRemoveMinerFlow` is `false` `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/position-change-dialog/remove-miner-dialog/remove-miner-dialog.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/dialogs/position-change-dialog/remove-miner-dialog/remove-miner-dialog.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isRemoveMinerFlow` | Required | `boolean` | - | Controls whether the dialog is open; `false` renders nothing | | `onCancel` | Required | `VoidFunction` | - | Called when the action is cancelled | | `headDevice` | Optional | `Device` | `{}` | The miner being removed | ### `SecondaryStatCard` Compact stat tile rendered alongside a primary stat to provide supporting context. Displays a secondary statistic with a name and value in a card format `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/secondary-stat-card/secondary-stat-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/secondary-stat-card/secondary-stat-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `className` | Optional | `string` | - | Custom className | | `name` | Optional | `string` | `""` | Stat name/label | | `value` | Optional | `string \| number` | `""` | Stat value | ### `SingleStatCard` Hero stat tile rendering one big number with a label and optional delta indicator. Displays a single statistic with optional animations and variants `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/single-stat-card/single-stat-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/single-stat-card/single-stat-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `color` | Optional | `string` | `"inherit"` | Color for flash/border | | `flash` | Optional | `boolean` | `false` | Enable flash animation | | `name` | Optional | `string` | - | Stat name/label | | `row` | Optional | `boolean` | `false` | Row layout | | `subtitle` | Optional | `string` | `""` | Subtitle text | | `superflash` | Optional | `boolean` | `false` | Enable superflash animation (faster) | | `unit` | Optional | `string` | `""` | Unit of measurement | | `value` | Optional | `string \| number \| null` | `null` | Stat value | | `variant` | Optional | `"primary" \| "secondary" \| "tertiary" \| "highlighted"` | `"primary"` | Card variant | ### `Socket` Per-socket panel showing the miner slotted into a container slot, its state, and quick actions. Displays a socket in a PDU with power/current info, miner status, and heatmap visualization Features: - Power and current display - Miner status indicators - [`Heatmap`](/reference/ui/components/charts/#heatmap) mode with temperature/hashrate - Cooling fan indicator - [`Socket`](/reference/ui/components/widgets/#socket) enable/disable states - Add miner flow `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/socket/socket.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/socket/socket.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `clickDisabled` | Optional | `boolean` | `false` | Whether click is disabled | | `cooling` | Optional | `boolean` | `undefined` | Cooling status | | `current_a` | Optional | `number \| null` | `null` | Current in amperes | | `enabled` | Optional | `boolean` | `false` | Whether socket is enabled | | `heatmap` | Optional | `Heatmap \| null` | `null` | [`Heatmap`](/reference/ui/components/charts/#heatmap) configuration | | `innerRef` | Optional | `React.ForwardedRef` | - | Forwarded ref for the container | | `isContainerControlSupported` | Optional | `boolean` | `false` | Whether container control is supported | | `isEditFlow` | Optional | `boolean` | `false` | Whether in edit flow mode | | `isEmptyPowerDashed` | Optional | `boolean` | `false` | Whether to show dashed border for empty power | | `miner` | Optional | `Miner \| null` | `null` | Miner data | | `pdu` | Optional | `Pdu` | - | PDU information | | `power_w` | Optional | `number \| null` | `null` | Power in watts | | `selected` | Optional | `boolean` | `false` | Whether socket is selected | | `socket` | Optional | `number \| null` | `null` | [`Socket`](/reference/ui/components/widgets/#socket) number/index | ### `StatsGroupCard` Card grouping multiple [``](/reference/ui/components/widgets/#singlestatcard)s or [``](/reference/ui/components/widgets/#secondarystatcard)s under a shared title. Displays aggregated statistics for selected miners: - Hash rate, Temperature, Frequency, Consumption - Optional: Power mode, Uptime, LED, Status (for single miner) Can render in two modes: - Miner Metrics: Uses [`MinerMetricCard`](/reference/ui/components/widgets/#minermetriccard) layout - Stats Grid: Uses [`SingleStatCard`](/reference/ui/components/widgets/#singlestatcard) and [`SecondaryStatCard`](/reference/ui/components/widgets/#secondarystatcard) in rows `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/stats-group-card/stats-group-card.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/details-view/stats-group-card/stats-group-card.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `isMinerMetrics` | Optional | `boolean` | `false` | Whether to show miner metrics card layout | | `miners` | Optional | `Device[] \| DeviceData[]` | - | Array of miners to display stats for | ### `StatusItem` Compact labelled status pill used inside container panels for boolean or enum readings. Displays a label with a colored status indicator `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/status-item/status-item.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/explorer/containers/bitmain/status-item/status-item.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `label` | Optional | `string` | - | Status label text | | `status` | Optional | `"warning" \| "normal" \| "fault" \| "unavailable"` | - | Status type | ### `SupplyLiquidBox` Status card for the dielectric supply tank — level, temperature, and pressure readings `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/supply-liquid-box/supply-liquid-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/supply-liquid-box/supply-liquid-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `containerSettings` | Optional | `SupplyLiquidBoxContainerSettings \| null` | `null` | Optional threshold map that controls colour and flash states on readings | | `data` | Optional | `Device` | - | Live device object. Returns `null` when omitted | ### `TankRow` Single tank-list row used inside [``](/reference/ui/components/widgets/#tanksbox) to display per-tank temperature and pressure `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/tanks-box/tank-row.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/tanks-box/tank-row.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `color` | Required | `string` | - | CSS colour for the temperature value (threshold-driven) | | `label` | Required | `string` | - | Tank identifier label (e.g. "Tank 1") | | `oilPumpEnabled` | Required | `boolean` | - | Running state for the oil pump | | `pressure` | Required | `Partial<{ value: number; flash: boolean; color: string; tooltip: string; }>` | - | Pressure reading with optional flash/colour/tooltip | | `temperature` | Required | `number` | - | Current temperature value | | `unit` | Required | `string` | - | Temperature unit string (e.g. "°C") | | `waterPumpEnabled` | Required | `boolean` | - | Running state for the water pump | | `flash` | Optional | `boolean` | - | Enables flash animation on the temperature row | | `tooltip` | Optional | `string` | - | [`Tooltip`](/reference/ui/components/overlays/#tooltip) text for the temperature value | ### `TanksBox` Card listing all tanks inside an immersion container with per-tank temperature and pressure rows. Displays tank rows with temperature, pressure, and oil/water pump status `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/tanks-box/tanks-box.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/container/tanks-box/tanks-box.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `data` | Optional | `{ oil_pump: Tank[]; water_pump: WaterPump[]; pressure: TanksBoxPressure[]; }` | - | Tank telemetry arrays; returns `null` when omitted | ### `WidgetTopRow` Compact header row used at the top of container / miner widgets — shows the title, per-category alarm badges, and the current power reading (or an error tooltip) `agent-ready`

Source
[https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/widget-top-row/index.tsx](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/domain/components/widget-top-row/index.tsx)
#### Props | Prop | Status | Type / Options | Default | Description | |------|--------|----------------|---------|-------------| | `title` | Required | `string` | - | Widget title | | `alarms` | Optional | `Partial>` | - | Per-category alarm badges | | `className` | Optional | `string` | - | Additional class names | | `power` | Optional | `number` | - | Power reading; rendered in kilo-units | | `statsErrorMessage` | Optional | `string \| ErrorWithTimestamp[] \| null` | - | Error tooltip content; replaces power | | `unit` | Optional | `string` | - | Power unit (e.g. `"kW"`) | # Hooks (/reference/ui/hooks) React hooks from `@tetherto/mdk-react-devkit` and `@tetherto/mdk-react-adapter` for building mining application UIs. ## 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. ## Browse by category ### Data & state hooks | Category | Description | Package | |----------|-------------|---------| | [Auth](/reference/ui/hooks/auth) | Authentication state hooks | react-adapter | | [Dashboard](/reference/ui/hooks/dashboard) | Dashboard data and state hooks | react-adapter, react-devkit | | [Permission](/reference/ui/hooks/permission) | Permission and access control hooks | react-adapter | | [Store](/reference/ui/hooks/store) | Zustand store access hooks | react-adapter | ### UI component hooks | Category | Description | Package | |----------|-------------|---------| | [Cards](/reference/ui/hooks/cards) | Card component state hooks | react-devkit | | [Charts](/reference/ui/hooks/charts) | Chart component hooks | react-devkit | | [Device](/reference/ui/hooks/device) | Device and equipment management hooks | react-adapter | | [Feedback](/reference/ui/hooks/feedback) | Toast and notification hooks | react-devkit | | [Filters](/reference/ui/hooks/filters) | Filter state hooks | react-devkit | | [Forms](/reference/ui/hooks/forms) | Form state and validation hooks | react-devkit | | [Navigation](/reference/ui/hooks/navigation) | Navigation state hooks | react-devkit | | [Settings](/reference/ui/hooks/settings) | Settings and preferences hooks | react-devkit | | [Tables](/reference/ui/hooks/tables) | Table state and interaction hooks | react-devkit | | [Widgets](/reference/ui/hooks/widgets) | Widget state hooks | react-devkit | ### Feature hooks | Category | Description | Package | |----------|-------------|---------| | [Alerts](/reference/ui/hooks/alerts) | Alert management hooks | react-adapter | | [Op Center](/reference/ui/hooks/op-center) | Operations center hooks | react-adapter, react-devkit | ### Utility hooks | Category | Description | Package | |----------|-------------|---------| | [Example](/reference/ui/hooks/example) | Example and demo hooks | react-adapter | | [Misc](/reference/ui/hooks/misc) | Miscellaneous hooks | react-devkit | | [Utility](/reference/ui/hooks/utility) | General utility hooks | react-adapter, react-devkit | ## Import pattern ```tsx // From react-adapter (state/data hooks) // From react-devkit (UI component hooks) ``` # Alert (/reference/ui/hooks/alerts) Hooks for managing alerts and notifications. ## Package `@tetherto/mdk-react-adapter` ## Hooks @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useCurrentAlertDevices` TanStack Query hook returning a flat list of the devices that currently carry one or more alerts, ready to hand straight to the devkit `<Alerts>` / `<CurrentAlerts>` table. ```typescript (options: UseCurrentAlertDevicesOptions = {}) => UseQueryResult ``` ### `useHistoricalAlerts` TanStack Query hook for the historical-alerts log. Fetches the `[start, end]` range as successive 24-hour `history-log` windows (see `fetchHistoricalAlertsInChunks`), merges them by `uuid`, and shapes the rows for the devkit `<HistoricalAl… ```typescript ({ start, end, intervalMs, enabled, }: UseHistoricalAlertsOptions) => UseQueryResult ``` # Auth (/reference/ui/hooks/auth) Hooks for authentication flows and session management. ## Package `@tetherto/mdk-react-adapter` ## Hooks @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useAuthToken` Adopts whatever session the environment is offering, then returns the current token so callers can react to it (e.g. redirect once signed in). ```typescript () => string | null ``` ### `useCurrentUserEmail` Fetches `/auth/userinfo` and returns the current user's email. Used by `useLiveActions` to partition actions into "mine vs others". ```typescript () => string | undefined ``` ### `useTokenPolling` Keeps the session alive by calling the active `AuthProvider`'s `refresh` on an interval. When a refresh reports the session ended, the provider signs out and `onSessionEnded` fires so the host app can redirect to its sign-in page. ```typescript (options: UseTokenPollingOptions = {}) => void ``` # Card (/reference/ui/hooks/cards) Hooks for card component state management. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useCabinetDetail` Reads the selected LV cabinet from `devicesStore`, re-fetches its family of powermeters and temperature sensors by root (`useCabinetDevices`) at the realtime cadence, and shapes them into the read-only rows the [`CabinetDetailCard`](/reference/ui/components/cards/#cabinetdetailcard) renders — powermeter readings (→ kW), the root plus per-position temperature readings (severity-coloured), and the active-warnings timeline folded from every device's `last.alerts` ```typescript (onNavigate?: (path: string) => void) => UseCabinetDetailResult ``` ### `useDeviceAlarms` Shapes the active alarms of the selected devices into timeline items for the Explorer detail panel, mirroring the reference app's `getContainerFormatedAlerts` → `getAlertTimelineItems` chain: `getAlarms` reads each device's `last.alerts`, `getLogFormattedAlertData` formats each with the device's `id`/`info`/`type` and the timezone-aware date formatter, and `getAlertTimelineItems` wires the log/dot rows plus the `onNavigate` click-through to the alert detail route ```typescript (devices?: Device[], onNavigate?: (path: string) => void) => UseDeviceAlarmsResult ``` ### `useExplorerThingDetail` Explorer detail hook: fetches one thing by id (`useThingDetail`) and shapes it into display-ready rows for the Explorer detail panel. Reads the same snapshot fields the container table columns show (status, ambient temp, humidity, power → kW) so the panel and the row stay consistent. Returns a `hasSelection: false` result when no id is given ```typescript (id: string | undefined, options?: UseThingDetailOptions) => UseExplorerThingDetailResult ``` # Chart (/reference/ui/hooks/charts) Hooks for chart components and data visualization. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit ### Check chart data ```tsx ``` #### Related API - [`ChartContainer`](/reference/ui/components/charts/#chartcontainer) ### When to use `useChartDataCheck` Use `useChartDataCheck` to drive a chart's empty state after its data has been shaped for the chart component. It returns `true` when the supplied chart data contains no renderable values. ### `useChartDataCheck` workflow Pass either `dataset` for direct bar-style datasets or `data` for a Chart.js-shaped object containing `datasets` (or `dataset`). Use the returned boolean as the `empty` state for `ChartContainer` or to choose an explicit empty placeholder. ### `useChartDataCheck` data-shape caveat The `data` option expects Chart.js-shaped data such as `{ labels, datasets }`. Raw hook output such as `{ labels, series }` can be non-empty while still being unrecognisable to the checker. Convert that output with [`buildBarChartData`](/reference/ui/components/charts) before calling the hook. Supply at least one of `dataset` or `data`; omitting both is treated as empty. ### `useChartDataCheck` example ```tsx BarChart, buildBarChartData, ChartContainer, useChartDataCheck, } from '@tetherto/mdk-react-devkit' function RevenueBarChart({ hookOutput }) { const chartData = buildBarChartData(hookOutput) const isEmpty = useChartDataCheck({ data: chartData }) return ( ) } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useChartDataCheck` Hook to check if chart data is empty or unavailable Returns `true` if data is empty/unavailable (should show empty state) Returns `false` if data exists (should show chart) ```typescript ({ dataset, data }: UseChartDataCheckParams) => boolean ``` ### `useEbitda` Transforms an `EbitdaResponse` and date-range options into query params and a chart-ready EBITDA view-model ```typescript ({ ebitda, isLoading, fetchErrors, ...dateRangeOptions }?: UseEbitdaOptions) => { metrics: EbitdaDisplayMetrics | null; ebitdaChartInput: ToBarChartDataInput | null; btcProducedChartInput: ToBarChartDataInput | null; hasBtcProducedAllZeros:… / see source / ``` ### `useEnergyBalanceViewModel` Computes the full [`EnergyBalance`](/reference/ui/components/charts/#energybalance) view model from raw API data, managing tab selection and display-mode state ```typescript ({ data, isLoading, fetchErrors, dateRange, availablePowerMW, }: UseEnergyBalanceOptions) => { queryParams: EnergyBalanceQueryParams | null; viewModel: { activeTab: EnergyBalanceTab; revenueDisplayMode: DisplayMode; costDisplayMode: Display… / see source / ``` # Dashboard (/reference/ui/hooks/dashboard) Hooks for dashboard data and state management. ## From `@tetherto/mdk-react-adapter` @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useActiveIncidents` TanStack Query hook returning the list of currently-firing alerts, shaped for `<ActiveIncidentsCard items={...} />`. ```typescript (options: UseActiveIncidentsOptions = {}) => UseQueryResult ``` ### `useCancelAction` Cancels pending actions via `DELETE /auth/actions/:type/cancel?ids=…`. Invalidates the pool/miner/actions caches on success. Gated by `actions:w`. ```typescript () => UseCancelActionResult ``` ### `useConsumptionChartData` TanStack Query hook returning raw consumption tail-log samples. Most dashboards should consume the higher-level `useSiteConsumptionChartData`, which wraps this hook with the site powermeter defaults and returns a `<LineChartCard>`-ready `C… ```typescript (params: UseConsumptionChartDataParams) => UseQueryResult ``` ### `useContainerPoolStats` Fetches per-container pool override counts from `GET /auth/pools/stats/containers`. Feeds the Sites Overview cards. ```typescript (options: UseContainerPoolStatsOptions = {}) => UseContainerPoolStatsResult ``` ### `useContainerUnits` Fetches the site's container things from `GET /auth/list-things` (tag `t-container`). Returns the raw rows the Sites Overview merge needs — `id`, `type`, `info.container`, `info.poolConfig`, and the container status under `last.snap.stats.… ```typescript (options: UseContainerUnitsOptions = {}) => UseContainerUnitsResult ``` ### `useDashboardDateRange` Owns the single source of truth for the dashboard's date-range picker. Pass `start` / `end` from the return value into every data hook on the page (`useHashrateChartData`, `useConsumptionChartData`, the export, etc.) so they refetch in loc… ```typescript (options: UseDashboardDateRangeOptions = {}) => UseDashboardDateRangeReturn ``` ### `useDashboardExport` Builds CSV / JSON downloads from the dashboard's already-cached TanStack Query data. Does NOT trigger refetches — the export is exactly what the user is looking at when they click the button. ```typescript (options: UseDashboardExportOptions) => UseDashboardExportReturn ``` ### `useDashboardTimeRange` Tiny piece of shared state for the dashboard's timeline selector. Owns the current `timeline` value plus the canonical option list. The chart hooks (`useHashrateChartData`, etc.) consume `timeline` as a prop. ```typescript (opts: UseDashboardTimeRangeOptions = {}) => DashboardTimeRange ``` ### `useDeviceAction` Entry point for wiring device-control UI (reboot, power mode, LED, socket switches, ...) into the voting/approval workflow: components build a typed submission with the foundation's device-action builders and queue it here. Submission and… ```typescript () => UseDeviceActionResult ``` ### `useGetAvailableDevices` Pure projector turning a flat device list (or the `/auth/list-things` nested shape) into the two type-buckets the device-explorer toolbar needs. ```typescript ({ data, }: UseGetAvailableDevicesOptions) => AvailableDevices ``` ### `useHashrateChartData` Multi-series hashrate chart data — the app-side series (miner tail-log) plus an `Aggr Pool` rollup and one line per individual pool (drawn from the paginated `type=minerpool, key=stats-history` ext-data feed). ```typescript (params: UseHashrateChartDataParams) => HashrateChartResult ``` ### `useLiveActions` Polls `GET /auth/actions` every 5 s (`voting`, `ready`, `executing`, `done`). Partitions results into the current user's actions vs others', and gates `othersVoting` behind the `actions:w` permission. ```typescript () => LiveActionsData ``` ### `useMinerDevices` Fetches miner devices from `GET /auth/list-things` (tag `t-miner`) in the nested shape the devkit Miner Explorer expects. Prefer this over `useMiners` when feeding the devkit — only the nested `info.poolConfig` id can resolve pool na… ```typescript (options: UseMinerDevicesOptions = {}) => UseMinerDevicesResult ``` ### `useMiners` Fetches miners with their assigned `poolConfig` from `GET /auth/miners`. Unwraps the paginated response envelope and returns the page rows for the Miner Explorer table plus the site-wide `totalCount`; row shaping (status mapping, pool labe… ```typescript (options: UseMinersOptions = {}) => UseMinersResult ``` ### `usePendingActions` Fetches submitted actions from `GET /auth/actions` — the server-side voting/approval queue (distinct from the local `actionsStore` staging buffer). Vote/cancel mutations invalidate this query's key. ```typescript (options: UsePendingActionsOptions = {}) => UsePendingActionsResult ``` ### `usePoolBalanceHistory` Fetches per-pool revenue/hashrate history from `GET /auth/pools/:pool/balance-history`. The query is disabled until a non-empty `pool` is supplied. ```typescript (pool: string, options: UsePoolBalanceHistoryOptions = {}) => UsePoolBalanceHistoryResult ``` ### `usePoolConfigsData` Fetches raw pool configurations from `GET /auth/configs/pool`. Returns the untransformed rows in the `{ data, isLoading, error }` shape the devkit `usePoolConfigs` transform consumes — keeping tag/endpoint parsing in the component layer pe… ```typescript (options: UsePoolConfigsDataOptions = {}) => UsePoolConfigsDataResult ``` ### `usePoolManagerDashboard` Composes the Pool Manager dashboard view-model: ```typescript (options: UsePoolManagerDashboardOptions = {}) => UsePoolManagerDashboardResult ``` ### `usePoolRows` Returns one row per configured mining pool, ready for the `<MiningPoolsPanel />` table. Reuses the same TanStack queryKey as `usePoolStats` so subscribing here doesn't trigger an extra fetch — both hooks share the cache entry. ```typescript (options: UsePoolRowsOptions = {}) => UsePoolRowsResult ``` ### `usePools` Fetches aggregated pools from `GET /auth/pools` (hashrate / workers / balance / revenue / summary). Feeds the Dashboard pool panel — distinct from `usePoolConfigsData` (`/auth/configs/pool`), which drives the editable Pools list. ```typescript (options: UsePoolsOptions = {}) => UsePoolsResult ``` ### `usePoolStats` Aggregates per-pool worker counts and hashrate from `GET /auth/ext-data?type=minerpool&query={"key":"stats"}`. Returns the `total`, `online`, and `mismatch` triplets and the summed `hashratePhs` shaped for `<HeaderMinersBox poolTotal/poolO… ```typescript (options: UsePoolStatsOptions = {}) => PoolStats ``` ### `usePowerModeTimelineData` TanStack Query hook returning power-mode/status samples shaped for `<PowerModeTimelineChart data={...} />`. ```typescript (params: UsePowerModeTimelineDataParams) => UseQueryResult ``` ### `useSiteConsumption` Projects the freshest consumption sample out of the dashboard's existing tail-log query for the header stats strip (`<HeaderConsumptionBox />`). ```typescript (params: UseConsumptionChartDataParams) => SiteConsumption ``` ### `useSiteConsumptionChartData` Site-level power consumption time-series, shaped for `<LineChartCard />`. Reads `site_power_w` from the `t-powermeter`-tagged tail-log (same source the header's `useSitePowerMeter` snapshot uses), converts W → MW, and emits `highlightedVal… ```typescript (params: UseSiteConsumptionChartDataParams) => SiteConsumptionChartResult ``` ### `useSiteContainerCapacity` Reads the aggregated nominal miner capacity across the site's containers — i.e. the maximum number of miners the facility was designed to host. Used as the "denominator" of the `<HeaderMinersBox />` row: e.g. the `2,188` in `158 / 2,188`. ```typescript (options: UseSiteContainerCapacityOptions = {}) => SiteContainerCapacity ``` ### `useSiteDetailMiners` Resolves the container that backs `selectedUnitId`, then returns the subset of miner devices assigned to that container. Both underlying queries are already issued by the PoolManager page, so React Query deduplicates them — no extra networ… ```typescript (selectedUnitId: string | null) => UseSiteDetailMinersResult ``` ### `useSiteEfficiency` Derives W/TH/s from the latest consumption + hashrate samples. Reuses both existing tail-log queries (no extra fetch) so the header efficiency box stays in step with the corresponding chart cards. Pass `powerW` to swap the numerator in (e.… ```typescript (params: UseSiteEfficiencyParams) => SiteEfficiency ``` ### `useSiteHashrate` Projects the freshest hashrate sample from the dashboard's tail-log query. Shares the TanStack queryKey with `useHashrateChartData`, so subscribing here does NOT trigger an extra fetch — both hooks read the same cache entry. ```typescript (params: UseSiteHashrateParams) => SiteHashrate ``` ### `useSiteMinerCounts` Counts active miners by status for the header `<HeaderMinersBox />`. Hits `/auth/list-things?status=1` with a tight projection (id, type, last.status only) so the response stays small even on big sites. ```typescript (options: UseSiteMinerCountsOptions = {}) => UseQueryResult ``` ### `useSiteMinerStats` Live miner-status breakdown for the header `<HeaderMinersBox />` strip. Reads the realtime tail-log (`key=stat-rtd, type=miner, tag=t-miner`) and projects four aggregate counts. Values reflect what is reporting right now, not the full inve… ```typescript (options: UseSiteMinerStatsOptions = {}) => SiteMinerStats ``` ### `useSitePowerMeter` Site-level power reading for the header's `<HeaderConsumptionBox />`. Reads the freshest snapshot from a `t-powermeter`-tagged thing at `info.pos = 'site'`; falls back to a `t-container`-tagged thing if no powermeter is configured (matches… ```typescript (options: UseSitePowerMeterOptions = {}) => SitePowerMeter ``` ### `useSitesOverview` Composes the Sites Overview dataset from three sources: ```typescript (options: UseSitesOverviewOptions = {}) => UseSitesOverviewResult ``` ### `useSitesOverviewData` Projects raw site-overview rows into a `<PoolManagerSitesOverview />`- ready shape: each container gets its per-container hashrate (in MH/s), an attached pool-stats row keyed by container id, and a `mining` / `offline` status derived from… ```typescript ({ units: rawUnits, poolStats, isLoading, tailLogItem, }: UseSitesOverviewDataOptions) => UseSitesOverviewDataResult ``` ### `useSiteStatusLive` Polls `GET /auth/site/status/live?overwriteCache=true` every 5s for the composite site snapshot (hashrate, power, efficiency, miner / alert / pool counts). Returns the raw typed payload for a hook or component to shape into dashboard cards. ```typescript (options: UseSiteStatusLiveOptions = {}) => UseSiteStatusLiveResult ``` ### `useSubmitPendingActions` Submits the locally-staged `actionsStore` queue to the voting/approval workflow. This is the network half of the write flow: the devkit modals only enqueue* (`setAddPendingSubmissionAction`); nothing posted to `/auth/actions` until this h… ```typescript () => UseSubmitPendingActionsResult ``` ### `useSubmitSingleAction` Submits a single action from the staged queue by its local `id`. Inspects the 200 response body for embedded errors before treating the call as successful. Removes the action from the queue only on genuine success. ```typescript () => UseSubmitSingleActionResult ``` ### `useVoteOnAction` Casts an approve/reject vote on a pending action via `PUT /auth/actions/voting/:id/vote`. Invalidates the pool/miner/actions caches on success so the review tray and dashboard reflect the new state. Gated by `actions:w`. ```typescript () => UseVoteOnActionResult ``` ## From `@tetherto/mdk-react-devkit` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useContainerWidgetsData` Site Overview data hook: composes the container inventory + realtime miner aggregate (`useContainerWidgets`) with the per-model thresholds (`useContainerSettings`) and shapes them into the card-ready `ContainerWidgetItem[]` the [``](/reference/ui/components/features/#containerwidgets) grid renders. All aggregate-field slicing and alarm math lives in `@tetherto/mdk-ui-foundation`; this hook only formats display values and selects card props ```typescript (options?: UseContainerWidgetsOptions) => UseContainerWidgetsDataResult ``` ### `usePoolConfigs` Transforms raw pool-configuration rows from the host's API into `PoolSummary` objects for Pool Manager components ```typescript ({ data, isLoading, error, }: Partial) => UsePoolConfigsResult ``` ### `useSiteOverviewDetailsData` Composes the per-site overview view-model: pools, performance series, and recent activity ```typescript (unit?: UnitData | undefined, options?: SiteOverviewDetailsDataOptions) => UseSiteOverviewDetailsDataResult ``` # Device (/reference/ui/hooks/device) Hooks for device validation, facility management, and equipment operations. ## Package `@tetherto/mdk-react-adapter` ## Hooks @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useMinerDuplicateValidation` Async validation hook that flags duplicate miners against the device inventory (MAC / serial / IP / human-facing code). ```typescript () => { duplicateError: boolean; isDuplicateCheckLoading: boolean; checkDuplicate: (selectedEditSocket: { miner?: { id?: string | undefined; } | undefined; } | null, { macAddress, serialNumber, addre… ``` ### `useNominalConfig` Normalises the raw `globalConfig` payload (single object or array — APIs differ across environments) into a flat `NominalConfig` with sane zero-defaults. ```typescript ({ globalConfig }: UseNominalConfigInput) => NominalConfig ``` ### `usePduViewer` Pan/zoom controller for the PDU floor-plan viewer. ```typescript () => UsePduViewerReturn ``` ### `useStaticMinerIpAssignment` Derives the static IP address a miner should receive based on its physical position (container number + socket coordinates). ```typescript (selectedEditSocket: Partial) => { minerIp: string; setMinerIp: React.Dispatch>; isStaticIpAssignment: boolean; } ``` # Example (/reference/ui/hooks/example) Example hooks for learning and demonstration purposes. ## Package `@tetherto/mdk-react-adapter` ## Hooks @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useSystemInfo` Reference example hook. Composes three read-only Gateway endpoints into a single page-ready payload for the shell's System Info page: • `GET /auth/site` → configured site label • `GET /auth/userinfo` → signed-in user's email + roles • `GET… ```typescript () => UseSystemInfoResult ``` # Feedback (/reference/ui/hooks/feedback) Hooks for user feedback and notifications. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit ### Toast notifications ```tsx ``` #### Related API - [`useNotifications`](/reference/ui/hooks/store/#usenotifications) ### When to use `useNotification` Use `useNotification` when a React interaction must show a success, error, information, or warning message (toast). It is the styled notification surface; use [`useNotifications`](/reference/ui/hooks/store/#usenotifications) when a component only needs the headless unread counter. ### `useNotification` example ```tsx function SaveButton() { const { notifySuccess, notifyError } = useNotification() const handleSave = async () => { try { await saveData() notifySuccess('Saved', 'Your changes have been saved.') } catch { notifyError('Save failed', 'Try again.', { dontClose: true }) } } return } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useNotification` Custom hook for showing notifications backed by the headless `notificationStore`. Uses `@tetherto/mdk-react-devkit/primitives` [`Toast`](/reference/ui/components/feedback/#toast) and [`Toaster`](/reference/ui/components/feedback/#toaster) components ```typescript () => { notifySuccess: (message: string, description?: string | undefined, options?: NotificationOptions | undefined) => void; notifyError: (message: string, description?: string | undefined, options?: NotificationOptions | undefined) => vo… /* see source / ``` # Filter (/reference/ui/hooks/filters) Hooks for filter components and state management. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useListViewFilters` Persistent filter-state hook for list views — syncs the active filter set to URL search params ```typescript ({ site, selectedType, availableDevices: _availableDevices, typeFiltersForSite, }: UseListViewFiltersParams) => { onFiltersChange: (selections: CascaderValue[]) => void; listViewFilterOptions: FilterOption[]; filters: LocalFilters | undefin… / see source / ``` ### `useReportTimeFrameSelectorState` State hook backing the reporting time-frame selector — exposes the active window and setters ```typescript () => ReportTimeFrameSelectorState ``` ### `useTimeframeControls` Core state machine for [`TimeframeControls`](/reference/ui/components/filters/#timeframecontrols) — owns year / month / week selection and resolves the date-range output ```typescript ({ dateRange, timeframeType: timeframeTypeProp, onRangeChange, onTimeframeTypeChange, isWeekSelectVisible, weekTree, }: UseTimeframeControlsParams) => { timezone: string; selectedYear: number; selectedMonth: number; visibleWeeks: Week[]; ha… / see source / ``` # Form (/reference/ui/hooks/forms) Hooks for form state management and validation. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit ### Used by form primitives ```tsx ``` #### Related API - [`FormField`](/reference/ui/components/forms/#formfield) ### When to use `useFormField` Use `useFormField` inside a custom form-field child that needs the current field's ID, validation state, or ARIA attributes. Standard pre-built fields already consume this context internally. ### `useFormField` workflow `FormField` provides the field context, `FormItem` provides the generated IDs, and custom descendants read that combined context through `useFormField`. ### `useFormField` prerequisites The hook must be rendered beneath `FormField` and `FormItem`. It is not a standalone form-state hook and does not replace `react-hook-form`'s `useForm`. ### `useFormField` example ```tsx FormControl, FormField, FormItem, FormLabel, useFormField, } from '@tetherto/mdk-react-devkit' function FieldStatusDot() { const { invalid, isDirty } = useFormField() const state = invalid ? 'error' : isDirty ? 'dirty' : 'clean' return } function NamedField({ control }) { return ( ( Name )} /> ) } ``` @tetherto/mdk-react-devkit ### Reset form state ```tsx ``` #### Related API - [`Form`](/reference/ui/components/forms/#form) - [`FormInput`](/reference/ui/components/forms/#forminput) ### When to use `useFormReset` Use `useFormReset` when resetting a [`react-hook-form`](https://react-hook-form.com/) form also needs before/after callbacks or a reusable dirty-state guard. Call the form object's `reset` method directly when no lifecycle behaviour is needed. ### `useFormReset` workflow Create the form with `useForm`, pass that instance to `useFormReset`, then wire the returned `resetForm` handler to a reset or cancel action. The hook reports `isDirty` from the same form state so the action can be disabled until values change. ### `useFormReset` prerequisite The hook requires a configured `react-hook-form` instance. It composes with [`Form`](/reference/ui/components/forms/#form) and fields such as [`FormInput`](/reference/ui/components/forms/#forminput); it does not create or submit the form. ### `useFormReset` example ```tsx type MinerFields = { name: string; ip: string } function MinerEditForm({ onSubmit }: { onSubmit: (values: MinerFields) => void }) { const form = useForm({ defaultValues: { name: '', ip: '' } }) const { resetForm, isDirty } = useFormReset({ form, onAfterReset: () => console.log('Form reset'), }) return (
) } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useFormField` Read-only context hook for form field children — returns the field's id, error state, and ARIA attributes ```typescript () => UseFormFieldReturn ``` ### `useFormReset` Hook to handle form reset with callbacks ```typescript ({ form, onBeforeReset, onAfterReset, }: UseFormResetOptions) => UseFormResetReturn ``` # Miscellaneous (/reference/ui/hooks/misc) Miscellaneous and general-purpose hooks. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useEnergyReportSite` Merges site energy consumption (v2 /auth/metrics/consumption) with snapshot tail-log and container list data for the Energy report site tab ```typescript ({ dateRange: _dateRange, consumptionLog, consumptionLoading, consumptionFetching, consumptionError, nominalPowerAvailabilityMw, nominalConfigLoading, tailLog, tailLogLoading, containers, containersLoading, }: UseEnergyReportSiteInput) => U… / see source / ``` ### `useHashBalance` 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 ```typescript ({ data, log, currency, dateRange, timeframeType, }: UseHashBalanceInput) => { siteHashRevenueChartData: BarChartDataResult; networkHashpriceChartData: BarChartDataResult; combinedCostChartData: BarChartDataResult; isEmpty: boolean; periodT… / see source / ``` ### `useSubsidyFees` 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 [`SubsidyFee`](/reference/ui/components/dashboards/#subsidyfee); expose to downstream apps that need to recompose the same datasets in a custom UI ```typescript ({ data, log, dateRange }: UseSubsidyFeesInput) => { summary: SubsidyFeeSummary; filteredLog: SubsidyFeesLogEntry[]; aggregatedData: AggregatedPeriodData[]; subsidyFeesChartData: BarChartDataResult; averageFeesChartData: BarChartDataResult;… / see source / ``` ### `useUpdateExistedActions` Mutation hook that updates only the changed fields of an existing action record. Removes tags from existing pending submissions if those tags belong to the newly selected devices; if the resulting tag list is empty, the submission itself is removed. This avoids duplicate pending actions for the same device ```typescript () => { updateExistedActions: ({ actionType, pendingSubmissions, selectedDevices, }: UpdateExistedActionsParams) => void; } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useHashrate` Base hook for a single [`Hashrate`](/reference/ui/components/charts/#hashrate) tab (single-site mode). Normalizes a grouped-hashrate query result to the `{ log, isLoading, error }` shape consumed by [``](/reference/ui/components/charts/#hashratesiteview), [``](/reference/ui/components/charts/#hashrateminertypeview), and [``](/reference/ui/components/charts/#hashrateminingunitview). Call once per tab the consumer needs to render - each tab fetches independently because they use different `groupBy` axes and (typically) different date ranges ```typescript ({ query }?: UseHashrateOptions) => UseHashrateResult ``` ### `useOperationsDashboard` Shapes raw operational metric logs into chart-ready payloads for the four operational-dashboard cards. DI-style: it never fetches - wire your data layer (RTK Query, TanStack, fixtures) and pass the results in. All unit conversion and series shaping happens here so the chart components stay purely presentational ```typescript (input?: Partial<{ hashrate: Partial<{ log: readonly OperationsTrendPoint[]; nominalValue: number | null; isLoading: boolean; error: unknown; }>; consumption: Partial<{ log: readonly OperationsTrendPoint[]; nominalValue: number | null; isLo… / see source / ``` # Navigation (/reference/ui/hooks/navigation) Hooks for navigation and routing state. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit ### Persist sidebar state ```tsx ``` #### Related API - [`useSidebarSectionState`](/reference/ui/hooks/navigation/#usesidebarsectionstate) - [`useSidebarExpandedState`](/reference/ui/hooks/navigation/#usesidebarexpandedstate) ### When to use sidebar state hooks Use `useSidebarExpandedState` for the whole sidebar's expanded state and `useSidebarSectionState` for an individual section. Both persist their value in `localStorage`, so navigation choices survive a reload. ### Sidebar state example ```tsx useSidebarExpandedState, useSidebarSectionState, } from '@tetherto/mdk-react-devkit' function AppSidebar() { const [expanded, setExpanded] = useSidebarExpandedState(false) const [devicesOpen, setDevicesOpen] = useSidebarSectionState('devices', true) return (
{devicesOpen ? : null}
) } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useSidebarExpandedState` Custom hook to persist sidebar expanded state in localStorage ```typescript (defaultExpanded: boolean) => [boolean, (expanded: boolean) => void] ``` ### `useSidebarSectionState` Custom hook to persist individual section open/closed states in localStorage ```typescript (sectionId: string, defaultOpen: boolean) => [boolean, (open: boolean) => void] ``` # Operations center (/reference/ui/hooks/op-center) Hooks for operations center functionality and monitoring. ## From `@tetherto/mdk-react-adapter` @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useCabinetDevices` Fetches one LV cabinet's family of devices — the powermeters and temperature sensors whose `info.pos` sits under the cabinet `root` (`buildCabinetDetailParams`) — polled at the Op-Center realtime cadence and flattened across the per-… ```typescript (root: string, options: UseCabinetDevicesOptions = {}) => UseCabinetDevicesResult ``` ### `useCabinetGroups` Fetches the Explorer cabinet-tab devices (powermeters + temperature sensors) and groups them by their owning container (`info.container`); devices without a container assignment (site-level meters) collect under the `site` group, sorted la… ```typescript (options: UseCabinetGroupsOptions = {}) => UseCabinetGroupsResult ``` ### `useContainerSettings` Fetches per-model container thresholds/parameters from `GET /auth/global/data?type=containerSettings`. Feeds the threshold status indicators (tank pressure, oil/water temperature) on the container widgets and detail tabs. ```typescript (options: UseContainerSettingsOptions = {}) => UseContainerSettingsResult ``` ### `useContainerSnapshots` Fetches the detail snapshots for the selected containers — the richer projection (`buildContainerDetailParams`) that carries `container_specific.pdu_data` plus the tank / cooling / power-mode config the detail panel controls read. `c… ```typescript (containerKeys: string[], options: UseContainerSnapshotsOptions = {}) => UseContainerSnapshotsResult ``` ### `useContainerWidgets` Data source for the Site Overview Container Widgets grid: the container inventory (one card per container) plus the latest per-miner realtime aggregate sample the cards derive their summaries from. Card-shaped payload derivation lives with… ```typescript (options: UseContainerWidgetsOptions = {}) => UseContainerWidgetsResult ``` ### `useExplorerList` Fetches the thing list behind one Explorer tab (`container` / `miner` / `cabinet`) from `GET /auth/list-things`, tag-filtered and projected by the foundation's Explorer params builder. Rows are flattened across the per-Kernel envelope so r… ```typescript (tab: ExplorerTabValue, options: UseExplorerListOptions = {}) => UseExplorerListResult ``` ### `useFeatureFlags` Fetches the deployment feature flags from `GET /auth/featureConfig` (camelCase route — there is no `/auth/feature-config`). Static deployment config — fetched once per session, no polling. Gates optional tabs/sub-routes (`containerCharts`,… ```typescript (options: UseFeatureFlagsOptions = {}) => UseFeatureFlagsResult ``` ### `usePduLayout` Fetches a container type's static PDU socket grid from `GET /auth/pdu-layout`. The grid is provisioned in the container worker's `pduGridLayout` config keyed by the exact type string — an unprovisioned type is a backend 400 (`ERR_PDU_LAYOU… ```typescript (params: UsePduLayoutParams, options: UsePduLayoutOptions = {}) => UsePduLayoutResult ``` ### `useRackLayout` Fetches the rack structure for a worker type from `GET /auth/list-racks` (`type` is required — the backend 400s with `ERR_TYPE_INVALID` without it). Feeds the Explorer rack grouping. ```typescript (params: UseRackLayoutParams, options: UseRackLayoutOptions = {}) => UseRackLayoutResult ``` ### `useSite` Fetches the configured site label from `GET /auth/site`. Static deployment config — fetched once per session, no polling. ```typescript (options: UseSiteOptions = {}) => UseSiteResult ``` ### `useThingComment` Device-comment writes for the Explorer detail panel — add, edit, and delete against `/auth/thing/comment` (the author is stamped server-side from the session token). Comments ride on the thing rows themselves (`comments` in the list-things… ```typescript () => UseThingCommentResult ``` ### `useThingDetail` Fetches a single thing by id from `GET /auth/list-things` with the full Op Center field projection — the data source for the Explorer detail panel and the container Thing-detail view. ```typescript (id: string | undefined, options: UseThingDetailOptions = {}) => UseThingDetailResult ``` ## From `@tetherto/mdk-react-devkit` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useExplorerSelection` Bridges the Explorer table selection into the shared `devicesStore` that the write-control cards read. Given the active tab and the table's row-selection, it dispatches the matching setters — containers → `selectMultipleContainers`, miners → `setSelectDevice` + `selectDeviceTag`, cabinets → `selectLVCabinet` — and, for containers/miners, fetches the richer detail snapshots (`useContainerSnapshots`) so the controls see the full `last.snap` config (tank / cooling / power-mode) the lean list projection omits, then derives the per-socket selection into the store. Selections are reset whenever the selection or tab changes and on unmount, so a stale selection can never drive the panel ```typescript ({ deviceType, rows, selected, }: UseExplorerSelectionParams) => UseExplorerSelectionResult ``` ### `useMinerDetail` Reads the miner selection the [`useExplorerSelection`](/reference/ui/hooks/op-center/#useexplorerselection) bridge writes into `devicesStore` and shapes the head miner for the read-only cards of the miner detail panel — the info rows ([`MinerInfoCard`](/reference/ui/components/widgets/#minerinfocard)) and the per-chip frequency / temperature stats ([`MinerChipsCard`](/reference/ui/components/widgets/#minerchipscard)). The write controls ([`MinerControlsCard`](/reference/ui/components/widgets/#minercontrolscard)) and the aggregate stats ([`StatsGroupCard`](/reference/ui/components/widgets/#statsgroupcard)) read the same store directly ```typescript () => UseMinerDetailResult ``` # Permission (/reference/ui/hooks/permission) Hooks for checking permissions and managing access control. ## Package `@tetherto/mdk-react-adapter` ## Hooks @tetherto/mdk-react-adapter ### Check a permission ```tsx ``` #### Related API - [`useAuth`](/reference/ui/hooks/store/#useauth) ### When to use `useCheckPerm` Use `useCheckPerm` for a single reactive permission, write-access or capability gate in a React component. It reads the current permissions from the same auth store exposed by [`useAuth`](/reference/ui/hooks/store/#useauth). ### `useCheckPerm` example ```tsx function EditUsersButton() { const canEditUsers = useCheckPerm({ perm: 'users:write' }) return canEditUsers ? : null } ``` @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useCheckPerm` Hook to check if the current user has a specific permission. Reads `permissions` from the headless `authStore` via `@tetherto/mdk-react-adapter`. ```typescript ({ perm, write, cap }: PermissionCheck) => boolean ``` ### `useHasPerms` Hook returning a permission-check callback bound to the current `authStore.permissions`. ```typescript () => ((req: PermissionRequest) => boolean) ``` ### `useIsFeatureEditingEnabled` Hook to check if the current user has the capability to edit feature flags. ```typescript () => boolean ``` # Settings (/reference/ui/hooks/settings) Hooks for managing user settings and preferences. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit ### Header controls ```tsx ``` #### Related API - [`useNotification`](/reference/ui/hooks/feedback/#usenotification) ### When to use `useHeaderControls` Use `useHeaderControls` in settings UI that reads or changes the shared header item preferences. It exposes the current preferences together with focused toggle and reset handlers. ### `useHeaderControls` notification behaviour `handleToggle` and `handleReset` show a success notification. Avoid calling either handler from rapidly changing state or an effect that can repeat, because each invocation creates another toast. ### `useHeaderControls` example ```tsx function HeaderSettings() { const { preferences, handleToggle, handleReset } = useHeaderControls() return (
{Object.entries(preferences).map(([key, visible]) => ( handleToggle(key, event.target.checked)} /> {key} ))}
) } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useHeaderControls` Read/write hook for the global header-controls store (toggles, sticky flag, theme) ```typescript () => { preferences: { poolMiners: boolean; appMiners: boolean; poolHashrate: boolean; appHashrate: boolean; consumption: boolean; efficiency: boolean; }; isLoading: boolean; error: null; handleToggle: (key: keyof HeaderPreferences, value:… / see source / ``` # Store (/reference/ui/hooks/store) Hooks for accessing Zustand stores and managing application state. ## Package `@tetherto/mdk-react-adapter` ## Hooks @tetherto/mdk-react-adapter ### Core store hooks ```tsx ``` #### Related API - [`useNotification`](/reference/ui/hooks/feedback/#usenotification) ### When to use core store hooks Use these hooks when a React component needs a reactive view of the headless Foundation stores: `useAuth` for session state, `useTimezone` for the selected IANA timezone, `useNotifications` for the unread count and `useActions` for the pending operator-action queue. Non-React code can read the corresponding Foundation store directly. ### Core store hooks example ```tsx useActions, useAuth, useNotifications, useTimezone, } from '@tetherto/mdk-react-adapter' function ShellStatus() { const { token } = useAuth() const { timezone } = useTimezone() const { count } = useNotifications() const { pendingSubmissions } = useActions() return (

Session
{token ? 'Active' : 'Signed out'}

Timezone
{timezone}

Unread
{count}

Pending actions
{pendingSubmissions.length}

) } ``` @tetherto/mdk-react-adapter ### Device store access ```tsx ``` ### When to use `useDevices` Use `useDevices` in React components that need the headless device inventory or current device selection. It is the React-bound view of `devicesStore`; code outside React should use the foundation store directly. ### `useDevices` example ```tsx function DeviceToolbar() { const { selectedDevices, setSelectedDevices } = useDevices() return (

Selected: {selectedDevices.length}

) } ``` @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useActions` React-bound view of the headless `actionsStore` (command queue + lifecycle). ```typescript () => ActionsStore ``` ### `useAuth` React-bound view of the headless `authStore`. Equivalent of `useStore(authStore)` — exposed as a hook for ergonomic callsites. ```typescript () => AuthStore ``` ### `useDevices` React-bound view of the headless `devicesStore` (miners, containers, PDUs). ```typescript () => DevicesStore ``` ### `useNotifications` React-bound view of the headless `notificationStore` (toast queue + history). ```typescript () => NotificationStore ``` ### `useTimezone` React-bound view of the headless `timezoneStore` (selected IANA zone). ```typescript () => TimezoneStore ``` # Table (/reference/ui/hooks/tables) Hooks for table components and data management. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit ### Explorer data ```tsx ``` #### Related API - [`DataTable`](/reference/ui/components/tables/#datatable) @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useExplorerData` Explorer list data hook: fetches the things behind one tab (`useExplorerList`) and shapes them for [``](/reference/ui/components/tables/#deviceexplorer) — applying the toolbar's search + filter selections client-side and deriving the search-autocomplete and filter-cascader options from the fetched rows. The tag-based backend query lives in `@tetherto/mdk-ui-foundation`; this hook only reads snapshot fields for display filtering. Search, status-filter and (in [`DeviceExplorer`](/reference/ui/components/tables/#deviceexplorer)) column sort are all client-side, over a tag-filtered, capped fetch — this mirrors the reference app. Fine for containers/cabinets; for very large miner fleets this fetches the cap and filters in the browser (no server paging). Push status into the foundation query + wire `limit`/`offset` if that ceiling is ever hit ```typescript (options: UseExplorerDataOptions) => UseExplorerDataResult ``` # Utility (/reference/ui/hooks/utility) General-purpose utility hooks. ## From `@tetherto/mdk-react-adapter` @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useBeepSound` Plays a repeating beep sound at a configurable interval. ```typescript ({ isAllowed = DEFAULTS.IS_ALLOWED, volume = DEFAULTS.VOLUME, delayMs = DEFAULTS.DELAY_MS, }: UseBeepSoundOptions = {}) => void ``` ### `useContextualModal` Headless open/close state for a modal that needs to remember the subject it was opened against (the row being edited, the device being inspected, etc.). ```typescript ({ onOpen, onClose, }: UseContextualModalParams = {}) => { modalOpen: boolean; handleClose: () => void; handleOpen: (sub: T | null) => void; subject: T | null; setSubject: React.Dispatch DeviceResolution ``` ### `useKeyDown` Tracks whether a specific keyboard key is currently held down. ```typescript (keyName: string) => boolean ``` ### `useLocalStorage` Custom hook for type-safe localStorage access with cross-tab sync. ```typescript (key: string, defaultValue: T) => [T, (value: T | ((prev: T) => T)) => void, VoidFunction] ``` ### `usePagination` Custom hook for managing pagination state ```typescript (args: PaginationArgs = {}) => UsePaginationReturn ``` ### `usePlatform` SSR-safe React hook returning the detected client OS. ```typescript () => PlatformResult ``` ### `useSubtractedTime` Returns `Date.now() - diff`, refreshing on a fixed interval (default 5s). ```typescript (diff: number, interval = DEFAULT_INTERVAL) => number ``` ### `useTimezoneFormatter` Timezone-aware date formatting hook. ```typescript () => UseTimezoneFormatterReturn ``` ### `useWindowSize` Hook to track window size changes ```typescript () => WindowSize ``` ## From `@tetherto/mdk-react-devkit` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useCostSummary` Base hook for the cost-summary reporting page (single-site mode). Owns the date-range / period UI state and the pure transform from a v2 `/auth/finance/cost-summary` response into headline metrics and time-series. Consumers wire their own fetch (RTK Query, TanStack Query, fixtures, ...) and pass the result through `query` - the hook never fetches itself. Multi-site mode is composed at the page level (T-13) by feeding a different response shape to the same view-model primitives; this base hook stays single-site to keep the input contract narrow ```typescript ({ query, ...dateRangeOptions }?: UseCostSummaryOptions) => { queryParams: CostSummaryQueryParams | null; isLoading: boolean; error: {} | null; metrics: CostSummaryDisplayMetrics | null; costLog: readonly CostTimeSeriesEntry[]; btcPriceLog:… / see source */ ``` # Widget (/reference/ui/hooks/widgets) Hooks for dashboard widgets and data cards. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useContainerThresholds` Hook that reads and updates the temperature/pressure/power thresholds for a single container. Features: - Load and save container threshold settings - Auto-save default thresholds when none exist - Validate and auto-adjust overlapping thresholds - Handle reset to saved/default values ```typescript ({ data, onSave, }: UseContainerThresholdsProps) => UseContainerThresholdsReturn ``` ### `useFinancialDateRange` Resolves the active financial date range (start/end) used by every reporting-section query ```typescript (options?: UseFinancialDateRangeOptions | undefined) => UseFinancialDateRangeResult ``` # Query helpers (/reference/ui/query-helpers) TanStack Query helper functions for fetching API data, managing mutations, and configuring the query client. These utilities streamline integration with the MDK Gateway API. ## Package `@tetherto/mdk-ui-foundation` ## Query helpers @tetherto/mdk-ui-foundation Import the public APIs on this page from [`@tetherto/mdk-ui-foundation`](/reference/ui/#tethertomdk-ui-foundation). ### `appendQuery` Append query params to a URL. `undefined` / `null` values and empty arrays are skipped; array values serialize comma-separated (`{ ids: ['a', 'b'] }` → `?ids=a,b`), the `qs` `arrayFormat: 'comma'` convention the Gateway expects, without th… ```typescript (url: string, params: Record) => string ``` ### `buildUrl` Join a base URL and a path, tolerating a trailing slash on the base and a missing leading slash on the path. ```typescript (base: string, path: string) => string ``` ### `createBearerFetcher` Build a `Fetcher` that injects `Authorization: Bearer <token>` from the supplied token getter (defaults to `authStore`). Non-2xx responses throw an `MdkFetchError` carrying the HTTP status and parsed body. ```typescript (options: { /** Override the token source — defaults to `authStore.getState().token`. */ getToken?: () => string | null /** Override `fetch` — pass a stub in tests. */ fetchImpl?: typeof fetch } = {}… ``` ### `createGetQueryFn` Build a signal-aware GET `queryFn`. This is the single place the `AbortSignal` is threaded into the fetcher: TanStack cancels a query (firing the signal) when its last observer unmounts on navigation, or when an invalidation supersedes a r… ```typescript (fetcher: Fetcher, url: string | (() => string)) => ({ signal }?: QueryFnContext) => Promise ``` ### `createMdkQueryClient` Build a TanStack `QueryClient` carrying the data-source runtime. ```typescript (options: CreateMdkQueryClientOptions = {}) => QueryClient ``` ### `createResourceMutation` Build a write factory: `(client, ...) => { mutationKey, mutationFn, invalidates }`. ```typescript (config: ResourceMutationConfig) => (client: on, fetcher?: Fetcher) => { mutationKey: ResourceKey; invalidates: ResourceKey[]; mutationFn: (payload: TBody) => Promise; } ``` ### `createResourceQuery` Build a read factory: `(client, input) => { queryKey, queryFn }`. ```typescript (config: ResourceQueryConfig) => (client: on, input: TInput, fetcher?: Fetcher) => { queryKey: ResourceKey; queryFn: ({ signal }?: QueryFnContext) => Promise; } ``` ### `endpointUrl` Resolve a named endpoint against the client's map into an absolute URL. ```typescript (client: QueryClient, name: EndpointName, pathParams?: Record) => string ``` ### `getApiBaseUrl` Read the configured base URL back from a `QueryClient`. Falls back to the default when the client was not produced by `createMdkQueryClient`. ```typescript (client: QueryClient) => string ``` ### `getEndpoints` Read the injected endpoint map, or `undefined` when the client carries none. The mining factories fall back to the bundled mining preset. ```typescript (client: QueryClient) => EndpointMap | undefined ``` ### `getFetcher` Read the injected transport, or `undefined` when the client carries none — which is the case for a hand-built `QueryClient`. Callers decide the fallback; the mining factories fall back to the bundled bearer fetcher. ```typescript (client: QueryClient) => Fetcher | undefined ``` ### `getMdkRuntime` Read the whole runtime at once. `baseUrl` is always resolved; `fetcher` and `endpoints` are `undefined` unless injected. ```typescript (client: QueryClient) => MdkRuntime ``` ### `mdkFetch` Module-level singleton bearer fetcher reading from the global `authStore`. Used as the default by the mining query factories (`tailLogQuery`, etc.). ```typescript Fetcher ``` ### `resolveApiBaseUrl` Resolves the API base URL: ```typescript (override?: string) => string ``` ### `resolvePath` Substitute `:name` segments in a path template, URL-encoding each value. ```typescript (template: string, params: Record = {}) => string ``` ### `resourceKey` ```typescript (name: string, params?: unknown, scope: readonly string[] = []) => ResourceKey ``` ### `runtimeEndpoints` Endpoint map for a factory call: whatever the client carries, else mining. ```typescript (client: QueryClient) => EndpointMap ``` ### `runtimeFetcher` Transport for a factory call: whatever the client carries, else the bundled bearer fetcher. ```typescript (client: QueryClient) => Fetcher ``` # Stores (/reference/ui/stores) Zustand stores providing global state management for authentication, devices, actions, notifications, and timezone handling. ## Package `@tetherto/mdk-ui-foundation` ## Stores @tetherto/mdk-ui-foundation Import the public APIs on this page from [`@tetherto/mdk-ui-foundation`](/reference/ui/#tethertomdk-ui-foundation). ### `actionsStore` Module-level singleton holding the queue of pending submission actions and the sidebar open/pinned state. #### State | Field | Type | |-------|------| | `pendingSubmissions` | `-` | | `sidebarOpen` | `-` | | `sidebarPinned` | `-` | #### Actions `setPendingSubmissionActions` ```typescript (actions: PendingSubmissionAction[]) => void ``` `setAddPendingSubmissionAction` ```typescript (action: Omit) => void ``` `removeTagsFromPendingAction` ```typescript (payload: { submissionId: number; tags: string[] }) => void ``` `removePendingSubmissionAction` ```typescript (payload: { id: number }) => void ``` `updatePendingSubmissionAction` ```typescript (action: Partial & { id: number }) => void ``` `clearAllPendingSubmissions` ```typescript () => void ``` `setSidebarOpen` ```typescript (open: boolean) => void ``` `setSidebarPinned` ```typescript (pinned: boolean) => void ``` @tetherto/mdk-ui-foundation Import the public APIs on this page from [`@tetherto/mdk-ui-foundation`](/reference/ui/#tethertomdk-ui-foundation). ### `authStore` Module-level singleton store holding the current session token and resolved permissions config. React adapters bind to this through `useAuth()`; non-React callers can `authStore.getState()` directly. #### State | Field | Type | |-------|------| | `token` | `-` | | `permissions` | `-` | #### Actions `setToken` ```typescript (token: string | null) => void ``` `setPermissions` ```typescript (permissions: unknown | null) => void ``` `reset` ```typescript () => void ``` @tetherto/mdk-ui-foundation Import the public APIs on this page from [`@tetherto/mdk-ui-foundation`](/reference/ui/#tethertomdk-ui-foundation). ### `devicesStore` Module-level singleton tracking selected devices, containers, sockets, and the device-tag map across the UI. Drives bulk-action toolbars, filtering, and the device explorer. #### State | Field | Type | |-------|------| | `selectedDevices` | `-` | | `selectedSockets` | `-` | | `filterTags` | `-` | | `selectedDevicesTags` | `-` | | `selectedContainers` | `-` | | `selectedLvCabinets` | `-` | #### Actions `selectContainer` ```typescript (device: DevicePayload) => void ``` `selectLVCabinet` ```typescript (device: DevicePayload) => void ``` `removeSelectedContainer` ```typescript (device: DevicePayload) => void ``` `removeSelectedLVCabinet` ```typescript (device: DevicePayload) => void ``` `selectMultipleContainers` ```typescript (devices: DevicePayload[]) => void ``` `removeMultipleContainers` ```typescript (devices: DevicePayload[]) => void ``` `setSelectedDevices` ```typescript (devices: DevicePayload[]) => void ``` `setSelectedLvCabinets` ```typescript (devices: Record) => void ``` `setMultipleSelectedDevices` ```typescript (devices: DevicePayload[]) => void ``` `removeMultipleSelectedDevices` ```typescript (deviceIds: string[]) => void ``` `setSelectDevice` ```typescript (device: DevicePayload) => void ``` `removeSelectedDevice` ```typescript (deviceId: string) => void ``` `setFilterTags` ```typescript (tags: string[]) => void ``` `removeFilterTag` ```typescript (tag: string) => void ``` `setSelectedSockets` ```typescript (sockets: Record) => void ``` `setSelectSocket` ```typescript (socket: SocketData) => void ``` `removeSelectedSocket` ```typescript (payload: RemoveSocketPayload) => void ``` `setMultipleSelectedSockets` ```typescript (sockets: SocketData[]) => void ``` `removeMultipleSelectedSockets` ```typescript (sockets: SocketData[]) => void ``` `setResetSelections` ```typescript () => void ``` `resetSelectedDevicesTags` ```typescript () => void ``` `selectDeviceTag` ```typescript (payload: DeviceTagPayload) => void ``` `removeDeviceTag` ```typescript (payload: DeviceTagPayload) => void ``` @tetherto/mdk-ui-foundation Import the public APIs on this page from [`@tetherto/mdk-ui-foundation`](/reference/ui/#tethertomdk-ui-foundation). ### `notificationStore` Module-level singleton exposing the unread-notification counter that drives header badges and the toast viewport. Increment/decrement from anywhere; React subscribers re-render automatically. #### State | Field | Type | |-------|------| | `count` | `-` | #### Actions `increment` ```typescript () => void ``` `decrement` ```typescript () => void ``` `reset` ```typescript () => void ``` @tetherto/mdk-ui-foundation Import the public APIs on this page from [`@tetherto/mdk-ui-foundation`](/reference/ui/#tethertomdk-ui-foundation). ### `timezoneStore` Module-level singleton holding the user's currently selected IANA timezone (e.g. `'America/New_York'`). Drives every timestamp renderer in the UI and the `useTimezoneFormatter` adapter hook. #### State | Field | Type | |-------|------| | `timezone` | `-` | #### Actions `setTimezone` ```typescript (timezone: string) => void ``` # Types (/reference/ui/types) TypeScript type definitions exported from `@tetherto/mdk-react-devkit` and `@tetherto/mdk-ui-foundation`. ## Browse by category ### From `@tetherto/mdk-react-devkit` | Category | Description | |----------|-------------| | [General](/reference/ui/types/devkit-general) | Component and hook prop types | ### From `@tetherto/mdk-ui-foundation` | Category | Description | |----------|-------------| | [API](/reference/ui/types/api) | API request/response types | | [Dashboard](/reference/ui/types/foundation-dashboard) | Dashboard data types | | [General](/reference/ui/types/foundation-general) | General utility types | ## Import pattern ```tsx ``` # API (/reference/ui/types/api) Type definitions for API requests and responses. ## Package `@tetherto/mdk-ui-foundation` ## Types @tetherto/mdk-ui-foundation Import the public APIs on this page from [`@tetherto/mdk-ui-foundation`](/reference/ui/#tethertomdk-ui-foundation). ### `ActionsParams` Free-form query parameters for `GET /auth/actions`. Array values are serialized comma-separated (e.g. `?status=VOTING,APPROVED`). ```typescript type ActionsParams = Record ``` ### `ActionTypeQuery` One entry in the `queries` array sent to `GET /auth/actions?queries=…`. ```typescript type ActionTypeQuery = { type: 'voting' | 'ready' | 'executing' | 'done' | string opts?: { reverse?: boolean; limit?: number; [key: string]: unknown } } ``` ### `AggregatedPool` Aggregated pool row from `GET /auth/pools` (hashrate / workers / balance / revenue / summary). Feeds the Dashboard pool panel, not the Pools list. ```typescript type AggregatedPool = { name?: string hashrate?: number workers?: number balance?: number revenue?: number [key: string]: unknown } ``` ### `AlertSeverity` Severity literal expected by the `ActiveIncidentsCard` row component. ```typescript type AlertSeverity = 'critical' | 'high' | 'medium' ``` ### `AuthTokenRequest` Request body for `POST /auth/token`. The token endpoint refreshes the session and (optionally) downgrades the role set. ```typescript type AuthTokenRequest = { roles?: string[] ttl?: number ips?: string[] scope?: string } ``` ### `AuthTokenResponse` Response from `POST /auth/token`. ```typescript type AuthTokenResponse = { token: string } ``` ### `CancelActionsPayload` Arguments for `DELETE /auth/actions/:type/cancel?ids=<comma>`. ```typescript type CancelActionsPayload = { /** Action type URL segment (e.g. `voting`). */ type: string ids: Array } ``` ### `ContainerPoolStat` Per-container override-count row from `GET /auth/pools/stats/containers`. ```typescript type ContainerPoolStat = { container: string overriddenConfig?: number [key: string]: unknown } ``` ### `ContainerSettingsEntry` One row of `GET /auth/global/data?type=containerSettings` (verified live 2026-07-01 — the response is a flat array, not the per-Kernel envelope). `thresholds` is keyed by threshold type (`oilTemperature`, `tankPressure`, `waterTemperature`… ```typescript type ContainerSettingsEntry = { model: string site?: string parameters?: Record thresholds?: Record } ``` ### `ContainerThresholdLevels` Threshold band for one container parameter. Which levels are present varies per parameter (verified live: `oilTemperature` carries `alert`/`alarm`, `waterTemperature` carries `alarmLow`/`alarmHigh`). ```typescript type ContainerThresholdLevels = { criticalLow?: number alarmLow?: number alert?: number normal?: number alarm?: number alarmHigh?: number criticalHigh?: number } ``` ### `DeviceAlert` Single alert record carried on a device under `last.alerts`. The list-things endpoint returns alerts as nested arrays — see `getAlertsForDevices` for the canonical extractor. ```typescript type DeviceAlert = { uuid?: string name: string description: string message?: string severity: string createdAt: number | string type?: string } ``` ### `ExtDataParams` Query parameters for `GET /auth/ext-data` — a small key-value gateway the backend exposes for non-tail-log data sources (minerpool, mempool, etc.). ```typescript type ExtDataParams = { /** Provider id — e.g. `minerpool`, `mempool`. */ type: string /** JSON-stringified provider-specific filter. / query?: string } ``` ### `FeatureConfigResponse` Response from `GET /auth/featureConfig` (note the camelCase path — there is no `/auth/feature-config` route). Typed loosely: the flag set is deployment-specific. The backend may also return multi-site keys (`isMultiSiteModeEnabled`, `siteL… ```typescript type FeatureConfigResponse = { [key: string]: unknown } ``` ### `GlobalDataParams` Query parameters for `GET /auth/global/data`. `type` selects the global data set (e.g. `containerSettings`); `model` optionally narrows container settings to one settings-model (`bd`, `mbt`, `hydro`, `immersion`). ```typescript type GlobalDataParams = { type: string model?: string overwriteCache?: boolean } ``` ### `HashRateLogEntry` Narrowed variant where the hashrate aggregate is present. The dashboard chart components default to this attribute when no `powerAttribute` override is provided. ```typescript type HashRateLogEntry = TailLogEntry & { hashrate_mhs_1m_sum_aggr?: number hashrate_mhs_5m_sum_aggr?: number } ``` ### `HistoricalAlert` A single historical alert row returned by `GET /auth/history-log?logType=alerts`. ```typescript type HistoricalAlert = { uuid?: string name: string description: string message?: string severity: string createdAt: number | string code?: string | number / Owning device, when th… ``` ### `HistoryLogParams` Query parameters for `GET /auth/history-log` (alerts / info-level history). ```typescript type HistoryLogParams = { logType: 'alerts' | 'info' start?: number end?: number limit?: number offset?: number query?: string } ``` ### `ListRacksParams` Query parameters for `GET /auth/list-racks`. `type` is the worker type (e.g. `miner`, `container`) — omitting it returns `ERR_TYPE_INVALID`. ```typescript type ListRacksParams = { type: string overwriteCache?: boolean } ``` ### `ListThingsDevice` Shape returned by `GET /auth/list-things` for a single device entry. Fields are typed to the union of what the known field projections request (miner explorer, container units, dashboard). Consumers that project fewer fields still satisfy… ```typescript type ListThingsDevice = { id: string type: string status?: string tags?: string[] code?: string rack?: string containerId?: string username?: string address?: string | null err?: stri… ``` ### `ListThingsParams` Query parameters for `GET /auth/list-things`. `query` and `fields` are JSON-stringified Mongo-style selectors. ```typescript type ListThingsParams = { type?: string tag?: string status?: number | string query?: string fields?: string limit?: number offset?: number } ``` ### `LiveAction` A single live action returned by the backend voting queue. ```typescript type LiveAction = { id: string / The action verb (e.g. `setupPools`, `registerPoolConfig`). / action?: string type?: string status?: string / Email/username of the submitte… ``` ### `LiveActionsResponse` Response shape of `GET /auth/actions?queries=…` — a one-element array whose single object maps each requested type to its result list. ```typescript type LiveActionsResponse = { voting?: LiveAction[] ready?: LiveAction[] executing?: LiveAction[] done?: LiveAction[] [key: string]: LiveAction[] | undefined } ``` ### `MinerEntry` A miner row from `GET /auth/miners`, carrying its assigned `poolConfig`. Only the id is guaranteed; the rest is consumed via `lodash.get`. ```typescript type MinerEntry = { id: string [key: string]: unknown } ``` ### `MinerpoolExtDataEntry` Single minerpool ext-data envelope. Backend nests these in `Array<Array<…>>` (per-pool grouping + per-timestamp grouping), so consumers `_head(_head(…))`. ```typescript type MinerpoolExtDataEntry = { ts?: string stats?: PoolMinerStats[] } ``` ### `MinerpoolStatsHistoryEntry` Single sample from the paginated `type=minerpool, key=stats-history` ext-data feed used by the multi-series Hash Rate chart. Each entry carries a timestamp and a snapshot of every configured pool's `hashrate` at that point in time. ```typescript type MinerpoolStatsHistoryEntry = { ts: number stats: PoolMinerStats[] } ``` ### `MinersParams` Query parameters for `GET /auth/miners`. `filter`, `fields`, and `sort` are JSON-stringified Mongo-style selectors; `search` is free text matched across id / code / serial / mac. ```typescript type MinersParams = { filter?: string fields?: string sort?: string search?: string limit?: number offset?: number } ``` ### `MinersResponse` Paginated envelope returned by `GET /auth/miners` — page `data` plus site-wide pagination metadata. ```typescript type MinersResponse = { data: MinerEntry[] totalCount: number offset: number limit: number hasMore: boolean } ``` ### `PduLayoutItem` One PDU row in the static grid layout. `power_w` / `current_a` / `offline` are absent in the static layout and filled from live `pdu_data`. ```typescript type PduLayoutItem = { pdu: string sockets: PduLayoutSocket[] power_w?: number | string current_a?: number | string offline?: boolean } ``` ### `PduLayoutParams` Query parameters for `GET /auth/pdu-layout`. `type` is the full container type string (e.g. `container-bd-d40-m56`). ```typescript type PduLayoutParams = { type: string overwriteCache?: boolean } ``` ### `PduLayoutResponse` Response from `GET /auth/pdu-layout` (verified live 2026-07-01). The backend sources this from the container worker's `pduGridLayout` config, keyed by the exact container type, and 400s with `ERR_PDU_LAYOUT_NOT_FOUND` when no layout is pro… ```typescript type PduLayoutResponse = { type: string layout: PduLayoutItem[] } ``` ### `PduLayoutSocket` One socket in a PDU grid. `enabled` reflects the static layout default; live on/off state comes from the device's `pdu_data` merge. ```typescript type PduLayoutSocket = { socket: string enabled: boolean cooling?: boolean } ``` ### `PoolBalanceHistoryEntry` A single revenue/hashrate sample from `GET /auth/pools/:pool/balance-history`. ```typescript type PoolBalanceHistoryEntry = { ts?: number revenue?: number hashrate?: number / Settled balance for the bucket (equals `revenue` in the current backend). */ balance?: number [key: string… ``` ### `PoolBalanceHistoryParams` Query parameters for `GET /auth/pools/:pool/balance-history`. The backend requires both `start` and `end` (Unix ms) and rejects the request otherwise; they are typed optional only so a param object can be built incrementally. ```typescript type PoolBalanceHistoryParams = { /** Window start (Unix ms). Required by the backend. */ start?: number /** Window end (Unix ms). Required by the backend. */ end?: number range?: '1D' | '1W'… ``` ### `PoolBalanceHistoryResponse` Response envelope for `GET /auth/pools/:pool/balance-history` — the backend wraps the samples in `{ log }`. ```typescript type PoolBalanceHistoryResponse = { log: PoolBalanceHistoryEntry[] } ``` ### `PoolConfigEntry` Raw pool-configuration row from `GET /auth/configs/pool`. This is the shape the devkit `usePoolConfigs` transform consumes to build a `PoolSummary`. ```typescript type PoolConfigEntry = { id: string poolConfigName: string description: string poolUrls: PoolConfigUrl[] miners: number containers: number updatedAt: string | number } ``` ### `PoolConfigForDeviceResponse` Response for `GET /auth/pools/config/:id` — the device's assigned pool config id and the count of miners overriding their container's config. ```typescript type PoolConfigForDeviceResponse = { poolConfig: string | null overriddenConfig: number } ``` ### `PoolConfigUrl` A single pool-URL endpoint as stored on a pool configuration. `url` is a `stratum+tcp://host:port` string; the devkit `usePoolConfigs` transform parses it into host/port/role for display. ```typescript type PoolConfigUrl = { url: string pool: string workerName?: string workerPassword?: string } ``` ### `PoolMinerStats` Per-pool stats entry returned by `GET /auth/ext-data?type=minerpool`. Each configured pool (`f2pool`, `ocean`, …) contributes one row. ```typescript type PoolMinerStats = { poolType?: string /** Subaccount / user the pool worker submits shares under. */ username?: string /** * Pool-reported hashrate in H/s (raw hashes per se… ``` ### `PoolsResponse` Response envelope for `GET /auth/pools` — the aggregated `pools` list plus a site-wide `summary`. The backend wraps the array, so consumers must read `.pools` rather than treating the payload as an array. ```typescript type PoolsResponse = { pools: AggregatedPool[] summary: PoolsSummary } ``` ### `PoolsSummary` Site-wide totals returned alongside the pool list by `GET /auth/pools`. ```typescript type PoolsSummary = { poolCount: number totalHashrate: number totalWorkers: number totalBalance: number } ``` ### `PowerModeTimelineEntry` Power-mode timeline entry — carries grouped per-miner mode/status maps keyed by miner id. Consumed by `PowerModeTimelineChart`. ```typescript type PowerModeTimelineEntry = TailLogEntry & { power_mode_group_aggr?: Record status_group_aggr?: Record } ``` ### `Rack` A single rack entry from `GET /auth/list-racks`. Typed loosely — the `listRacks` RPC response shape has not been captured against a live backend yet (staging returned no rack data at verification time). ```typescript type Rack = { id?: string name?: string [key: string]: unknown } ``` ### `SiteResponse` Response from `GET /auth/site` — the configured site label. ```typescript type SiteResponse = { site: string } ``` ### `SiteStatusAlerts` Alert counts by severity from the live site-status snapshot. ```typescript type SiteStatusAlerts = { critical: number high: number medium: number total: number } ``` ### `SiteStatusLive` Composite live site-status snapshot from `GET /auth/site/status/live`. Aggregates site-wide hashrate, power, efficiency, miner/alert/pool counts, and the snapshot timestamp (`ts`, Unix ms). Polled on a short interval. ```typescript type SiteStatusLive = { hashrate: SiteStatusMetric power: SiteStatusPower efficiency: SiteStatusMetric miners: SiteStatusMiners alerts: SiteStatusAlerts pools: SiteStatusPools /** S… ``` ### `SiteStatusMetric` A `{ value, unit }` measurement, optionally annotated with a `nominal` (rated) value and a `utilization` percentage (`value / nominal * 100`). ```typescript type SiteStatusMetric = { value: number unit: string nominal?: number utilization?: number } ``` ### `SiteStatusMiners` Miner population counts from the live site-status snapshot. ```typescript type SiteStatusMiners = { online: number offline: number error: number total: number containerCapacity: number } ``` ### `SiteStatusPools` Pool-side aggregates from the live site-status snapshot. ```typescript type SiteStatusPools = { totalHashrate: { value: number; unit: string } activeWorkers: number totalWorkers: number } ``` ### `SiteStatusPower` Power metric from the live site-status snapshot. Like `SiteStatusMetric` but with an `alert` message and a hard `error` flag. ```typescript type SiteStatusPower = SiteStatusMetric & { alert?: string error?: boolean } ``` ### `SubmitBatchActionsPayload` Body for `POST /auth/actions/voting/batch` — a set of staged actions plus a client-generated `batchActionUID` the backend uses to group them. ```typescript type SubmitBatchActionsPayload = { batchActionsPayload: VotingActionPayload[] batchActionUID: string suffix?: string / Batch-level annotations (e.g. `{ isBackFromMaintenance }` on miner move… ``` ### `TailLogEntry` A single time-bucketed entry from `GET /auth/tail-log`. Backend returns `Array<Array<TailLogEntry>>` (outer wrapping is the per-worker grouping — single-site dashboards take `_head(response)`). ```typescript type TailLogEntry = { ts: number / All other fields are dynamic aggregates requested via `aggrFields`. / [key: string]: unknown } ``` ### `TailLogMultiParams` Query parameters for `GET /auth/tail-log/multi` — the batched variant of tail-log. `keys` is required (comma-separated `stat-` keys); the rest mirrors the Fastify schema in the gateway for live sites. ```typescript type TailLogMultiParams = { keys: string start?: number end?: number offset?: number limit?: number fields?: string aggrFields?: string aggrTimes?: string overwriteCache?: boolean } ``` ### `TailLogParams` Query parameters for `GET /auth/tail-log`. Mirrors the Fastify schema in the gateway for live sites. `aggrFields` is a JSON-stringified object describing which aggregate columns to include in each row. ```typescript type TailLogParams = { key: string type?: string tag?: string start?: number end?: number offset?: number limit?: number fields?: string aggrFields?: string aggrTimes?: string merg… ``` ### `ThingCommentBody` Body for `POST | PUT | DELETE /auth/thing/comment` (add / edit / delete a device comment — one Fastify schema covers all three verbs). `rackId` + `thingId` + `comment` are required; `id` and `ts` identify an existing comment for edit/delet… ```typescript type ThingCommentBody = { rackId: string thingId: string comment: string /** Existing comment id — required when editing or deleting. */ id?: string pos?: string ts?: number } ``` ### `ThingConfigParams` Query parameters for `GET /auth/thing-config` — both fields are required by the Fastify schema. ```typescript type ThingConfigParams = { type: string requestType: string } ``` ### `VoteActionPayload` Body for `PUT /auth/actions/voting/:id/vote`. ```typescript type VoteActionPayload = { id: string | number approve: boolean } ``` ### `VotingActionObjectParam` Object-shaped `params[]` entry on a voting submission. Pool create/update carry `{ type: 'pool', data }` (+ `id` for updates); assign-pool carries `{ poolConfigId, configType: 'pool' }`; `switchSocket` carries `{ pdu, socket, enabled }`; `… ```typescript type VotingActionObjectParam = { type?: string id?: string poolConfigId?: string configType?: string data?: Record [key: string]: unknown } ``` ### `VotingActionParam` A single `params[]` entry on a voting submission. Positional and action-specific: device actions carry primitives (`setPowerMode` sends `['sleep']`, `setLED` sends `[true]`, `setTankEnabled` sends `[3, true]`), pool/thing actions carry {@l… ```typescript type VotingActionParam = string | number | boolean | VotingActionObjectParam ``` ### `VotingActionPayload` Body for `POST /auth/actions/:type` (default `voting`). `type` selects the URL segment and is stripped from the JSON body before posting — the remaining fields (`query`, `action`, `params`, `rackType`, …) form the request body. ```typescript type VotingActionPayload = { /** URL segment under `/auth/actions/:type`. Defaults to `voting`. */ type?: string query?: Record action?: string params?: VotingActionPara… ``` # Devkit general (/reference/ui/types/devkit-general) General type definitions from the react-devkit package. ## Package `@tetherto/mdk-react-devkit` ## Types @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ActionButtonProps` ```typescript type ActionButtonProps = { /** Button label text */ label?: string /** Shows a spinner on the trigger button */ loading?: boolean /** Disables the trigger button */ disabled?: boolean /** Additional class for the trigger button */ className?: string /** * Visual s… ``` ### `ActualEbitdaCardProps` ```typescript type ActualEbitdaCardProps = { value: number } ``` ### `AddSparePartModalProps` Props for `AddSparePartModal`; option lists and handlers are supplied by the caller ```typescript type AddSparePartModalProps = { /** Whether the modal is open */ isOpen: boolean /** Called when the modal requests to close */ onClose: VoidFunction /** Part-type tabs */ partTypes: SparePartSubTypesModalPartType[] /** Initially selected part type */ defaultPartTypeId… ``` ### `AddUserModalProps` ```typescript type AddUserModalProps = { /** Controls whether the dialog is visible */ open: boolean /** Called when the user dismisses the modal (cancel or backdrop) */ onClose: VoidFunction /** List of assignable roles rendered in the role select drop-down */ roles: RoleOptio… ``` ### `AlarmsBellButtonProps` ```typescript type AlarmsBellButtonProps = { /** * Severity-bucketed alarm counts rendered in the stacked badge. * @default {} */ counts?: AlarmsBellButtonCounts /** Click handler — typically opens an alerts panel or routes to /alerts. */ onClick?: (event: MouseEvent['data'] /** Chart.js options - merged with defaults / options?: ChartJS<'line'>['options'] / Custom HTML tooltip configuration. When provided, replaces the default… ``` ### `ArrowIconProps` ```typescript type ArrowIconProps = { isOpen?: boolean } & IconProps ``` ### `AssignPoolModalProps` ```typescript type AssignPoolModalProps = { / Controls modal visibility / isOpen: boolean /** Called when the modal is dismissed (× button or backdrop) */ onClose: () => void /** Called with the selected pool when the form is submitted */ onSubmit: (values: { pool: PoolSummary… ``` ### `AverageDowntimeChartProps` ```typescript type AverageDowntimeChartProps = Partial<{ /** * Chart title (unit renders on its own line below) * @default "Monthly Average Downtime" */ title: string /** * Unit subtitle under the title * @default % */ unit: string /** * Chart height in pixels * @default 280 */ height:… ``` ### `AvgAllInCostChartProps` ```typescript type AvgAllInCostChartProps = { data?: ReadonlyArray dateRange: FinancialDateRange | null isLoading?: boolean } ``` ### `BadgeProps` ```typescript type BadgeProps = { /** * Badge content (wraps children with badge) */ children?: ReactNode /** * Number to display in badge * If > overflowCount, will show "overflowCount+" * @default 0 */ count?: number /** * Maximum count to display * @default 99 */ over… ``` ### `BarChartProps` ```typescript type BarChartProps = { /** Chart data - required, provided by parent. Use `as any` for mixed bar+line datasets. */ data: any /** Chart.js options - merged with defaults */ options?: ChartJS<'bar'>['options'] /** * Stack bars on top of each other * @default fal… ``` ### `BatchMoveSparePartsModalProps` Props for `BatchMoveSparePartsModal`; unselected location/status arrive as `null` on submit ```typescript type BatchMoveSparePartsModalProps = { /** Whether the modal is open */ isOpen: boolean /** Called when the modal requests to close */ onClose: VoidFunction /** The parts to move, rendered in the table */ spareParts: BatchMoveSparePart[] /** New-location options */ locationOp… ``` ### `BitcoinPriceCardProps` ```typescript type BitcoinPriceCardProps = { value: number } ``` ### `BitcoinProducedCardProps` ```typescript type BitcoinProducedCardProps = { value: number } ``` ### `BitcoinProducedChartProps` ```typescript type BitcoinProducedChartProps = { chartData: BarChartDataResult isLoading?: boolean hasAllZeros?: boolean height?: number } ``` ### `BitcoinProductionCostCardProps` ```typescript type BitcoinProductionCostCardProps = { value: number } ``` ### `BitMainControlsTabProps` ```typescript type BitMainControlsTabProps = { /** Device data */ data: Device } ``` ### `BitMainHydroSettingsProps` ```typescript type BitMainHydroSettingsProps = { /** Device data */ data?: Device } ``` ### `BitMainImmersionSummaryBoxProps` ```typescript type BitMainImmersionSummaryBoxProps = { /** Live device object from the devices store. Returns `null` when omitted. */ data?: Device /** * Optional threshold configuration that drives colour/flash states on temperature stats * @default null */ containerSettings?: BitMainImmers… ``` ### `BreadcrumbsProps` ```typescript type BreadcrumbsProps = { /** Ordered trail; the last item is rendered as current */ items: BreadcrumbItem[] /** * Show a leading "Back" button * @default false */ showBack?: boolean /** * Label for the back button * @default "Back" / backLabel?: string / Root… ``` ### `BtcAveragePriceProps` ```typescript type BtcAveragePriceProps = Partial<{ / BTC price in USD; formatted with grouping and no decimal places. * When `null`, `undefined`, non-finite, or negative, the value shows `-` (`FALLBACK` from format utils). */ price: number | null /** * Label for the BTC avera… ``` ### `BulkAddSparePartsModalProps` Props for `BulkAddSparePartsModal`; `onSubmit` receives the parsed CSV records ```typescript type BulkAddSparePartsModalProps = { /** Whether the modal is open */ isOpen: boolean /** Called when the modal requests to close */ onClose: VoidFunction /** Submit handler; return `{ error }` to show an inline error */ onSubmit: (records: CSVRecord[]) => Promise<{ error?:… ``` ### `ButtonProps` Props for `Button`. Extends all native `<button>` attributes ```typescript type ButtonProps = Partial< { /** * Show a spinner instead of the content and disable the button. * @default false */ loading: boolean /** * Make the button stretch to fill its container. * @default false / fullWidth: boolean / Icon node rendered alongsid… ``` ### `CabinetDetailCardProps` ```typescript type CabinetDetailCardProps = { / Cabinet display title (`LV Cabinet 1` / transformer title). / title: string /** Non-root powermeter reading rows. */ powerMeters: CabinetReadingRow[] /** The cabinet-root temperature reading, when present. */ rootTempSensor?: Cabine… ``` ### `CardBodyProps` Props for `CardBody` slot. Forwards all native `<div>` attributes ```typescript type CardBodyProps = HTMLAttributes ``` ### `CardFooterProps` Props for `CardFooter` slot. Forwards all native `<div>` attributes ```typescript type CardFooterProps = HTMLAttributes ``` ### `CardHeaderProps` Props for `CardHeader` slot. Forwards all native `<div>` attributes ```typescript type CardHeaderProps = HTMLAttributes ``` ### `CascaderProps` Cascader component props ```typescript type CascaderProps = { /** * Hierarchical options to display in the cascader * Parent options with children appear in the left panel * Child options appear in the right panel when parent is selected */ options: CascaderOption[] /** * Current selected value(s)… ``` ### `ChangeConfirmationModalProps` ```typescript type ChangeConfirmationModalProps = { /** Controls whether the dialog is visible */ open: boolean /** Dialog header title */ title: string /** Called when the user clicks the confirm button */ onConfirm: VoidFunction /** Called when the user cancels or dismisses the dialog *… ``` ### `ChartContainerProps` ```typescript type ChartContainerProps = { /** Chart heading (renders as `
` unless `header` is provided) */ title?: string /** * Optional node rendered immediately after the title text (e.g. an info * tooltip). Only shown when `title` is set and `header` is not. Additive - *… ``` ### `ChartExpandActionProps` ```typescript type ChartExpandActionProps = { /** Whether the parent chart is currently expanded to full width. */ isExpanded: boolean /** Toggles the expanded state. */ onToggle?: VoidFunction } ``` ### `ChartStatsFooterProps` ```typescript type ChartStatsFooterProps = Partial<{ /** Min/Max/Avg values row */ minMaxAvg: MinMaxAvgValues /** Additional stats displayed in a columnar grid */ stats: ChartStatsFooterItem[] /** * Number of stat items per column (default: 1) * @default 1 */ statsPerColumn: number… ``` ### `CheckboxProps` ```typescript type CheckboxProps = { // Key controlled-state props re-declared from the Radix root so they surface in // the generated docs (types reuse Radix's via indexed access — cannot drift). /** Controlled checked state / checked?: CheckboxRootProps['checked'] / Un… ``` ### `ConfirmDeleteSparePartModalProps` Props for `ConfirmDeleteSparePartModal` ```typescript type ConfirmDeleteSparePartModalProps = { / Whether the modal is open / isOpen?: boolean /** Called when the modal requests to close */ onClose?: VoidFunction /** Called with the part when the user confirms */ onConfirm?: (sparePart: ConfirmDeleteSparePartModalSparePart) => P… ``` ### `ContainerChartsProps` ```typescript type ContainerChartsProps = { /** When false, shows an empty state (feature gate). @default true */ featureEnabled?: boolean /** * Message when `featureEnabled` is false * @default 'Container Charts feature is not enabled' / disabledMessage?: string / Options for… ``` ### `ContainerControlsBoxProps` ```typescript type ContainerControlsBoxProps = { / The container device object / data?: Device /** * When `true`, operates on `selectedDevices` instead of a single `data` record * @default false */ isBatch?: boolean isCompact?: boolean // --- data from outside (no API calls inside)… ``` ### `ContainerDetailProps` ```typescript type ContainerDetailProps = { /** * Container display name shown in the header. Optional — omit it when the * host already renders the container name as the page title (e.g. the shell's * `PageLayout`), so the name is not shown twice. / name?: ReactNode / Ordered… ``` ### `ContainerWidgetCardProps` ```typescript type ContainerWidgetCardProps = { / Container display name shown in the header row. / title: string /** Latest container power draw in watts (rendered in kW by the top row). */ power?: number /** Power unit label shown next to the reading. / powerUnit?: string / Pe… ``` ### `ContainerWidgetsProps` ```typescript type ContainerWidgetsProps = { / Card-ready data for every container, shaped by the data hook. / containers: ContainerWidgetItem[] /** Section heading. */ title?: string /** * Shows a spinner while the first load is in flight. * @default false */ isLoading?: boolea… ``` ### `CostChartsProps` ```typescript type CostChartsProps = { costLog: ReadonlyArray btcPriceLog: ReadonlyArray totals: CostSummaryMonetaryTotals | null dateRange: FinancialDateRange | null avgAllInCostData?: ReadonlyArray isLoadi… ``` ### `CostContentProps` ```typescript type CostContentProps = CostViewModelProps & CostQueryStateProps & { /** Active date range; drives x-axis labels across all charts */ dateRange: FinancialDateRange | null /** Optional revenue/cost time-series for the Avg All-in Cost panel. */ avgAllInCostData?: R… ``` ### `CostMetricsProps` ```typescript type CostMetricsProps = { metrics: CostSummaryDisplayMetrics } ``` ### `CostProps` ```typescript type CostProps = CostContentProps & CostChromeProps ``` ### `CurrentAlertsProps` ```typescript type CurrentAlertsProps = { /** * Devices carrying alerts (`last.alerts`), as a flat list. Unwrapping any * backend envelope is the data layer's job, not this component's. * Shape mirrors the API response from the source app. */ devices?: Device[] /** * Show DataTa… ``` ### `DashboardDateRangePickerProps` ```typescript type DashboardDateRangePickerProps = { /** Current range as `{ start, end }` epoch-millisecond timestamps. */ value: DashboardDateRange /** Fires with the next `{ start, end }` window when the user applies a range. */ onChange: (next: DashboardDateRange) => void /** * Display… ``` ### `DataLabelProps` ```typescript type DataLabelProps = Partial<{ /** * Range start; formatted in the active timezone (`dd/MM/yy`). */ startDate: Date | null /** * Range end; formatted in the active timezone (`dd/MM/yy`). */ endDate: Date | null /** * Label text; defaults to `PERIOD`. * @defaul… ``` ### `DataTableProps` ```typescript type DataTableProps = { /** * The data to be shown in the table. See https://tanstack.com/table/v8/docs/guide/data */ data: I[] /** * The column configuration table. See https://tanstack.com/table/v8/docs/guide/column-defs */ columns: DataTableColumnDef… ``` ### `DatePickerProps` ```typescript type DatePickerProps = { /** * Currently selected date */ selected?: Date /** * Callback when date changes */ onSelect?: (date: Date | undefined) => void /** * Placeholder text when no date is selected * @default "Pick a date" */ placeholder?: string /** * Date… ``` ### `DateRangePickerProps` ```typescript type DateRangePickerProps = { /** * Selected date range */ selected?: DateRange /** * Callback when date range changes */ onSelect?: (range: DateRange | undefined) => void /** * Placeholder text when no range is selected * @default "Pick a date range" */ placeholder?… ``` ### `DetailLegendProps` ```typescript type DetailLegendProps = { /** Legend items to display */ items: DetailLegendItem[] /** Callback when a legend item is toggled */ onToggle?: (label: string, index: number) => void /** Custom class name */ className?: string } ``` ### `DeviceExplorerProps` ```typescript type DeviceExplorerProps = { /** Active device-type tab */ deviceType: DeviceExplorerDeviceType /** Additional class names */ className?: string /** Controlled row-selection state */ selectedDevices?: DataTableRowSelectionState /** Setter for row selection */ onSele… ``` ### `DialogContentProps` ```typescript type DialogContentProps = { /** Renders `DialogTitle` (and optional `DialogDescription`) inside the header */ title?: string /** Renders `DialogDescription` below the title */ description?: string /** * Whether clicking the overlay closes the dialog * @default true… ``` ### `DialogHeaderProps` ```typescript type DialogHeaderProps = { /** * Applies `mdk-dialogheader--bare` to the header * @default false */ bare?: boolean /** Shows an ✕ close button in the header */ closable?: boolean /** Fired when the ✕ button is clicked */ onClose?: VoidFunction } ``` ### `DividerProps` ```typescript type DividerProps = { /** * Line orientation * @default 'horizontal' */ orientation?: DividerOrientation /** * Line style * @default false */ dashed?: boolean /** * Renders a dotted line (takes precedence over `dashed`) * @default false / dotted?: boolean /… ``` ### `DoughnutChartProps` ```typescript type DoughnutChartProps = { /** Array of labelled slices */ data: DoughnutChartDataset[] /** * Unit suffix appended to values in tooltips and legends * @default '' */ unit?: string /** Chart.js options – merged with defaults */ options?: ChartJS<'doughnut'>['option… ``` ### `EbitdaChartsProps` ```typescript type EbitdaChartsProps = { showEbitdaBarChart: boolean ebitdaChartData: BarChartDataResult btcDisplayData: BarChartDataResult isLoading: boolean hasBtcProducedAllZeros: boolean } ``` ### `EbitdaHodlCardProps` ```typescript type EbitdaHodlCardProps = { value: number currentBTCPrice: number } ``` ### `EbitdaMetricsProps` ```typescript type EbitdaMetricsProps = { metrics: EbitdaDisplayMetrics currentBTCPrice: number } ``` ### `EbitdaProps` ```typescript type EbitdaProps = { /** Computed EBITDA metrics */ metrics: EbitdaDisplayMetrics | null /** Data for the EBITDA bar chart */ ebitdaChartInput: ToBarChartDataInput | null /** Data for the BTC produced chart */ btcProducedChartInput: ToBarChartDataInput | nul… ``` ### `EbitdaSellingCardProps` ```typescript type EbitdaSellingCardProps = { value: number } ``` ### `EfficiencyMinerTypeViewProps` ```typescript type EfficiencyMinerTypeViewProps = Omit ``` ### `EfficiencyMinerUnitViewProps` ```typescript type EfficiencyMinerUnitViewProps = Omit ``` ### `EfficiencySiteViewProps` ```typescript type EfficiencySiteViewProps = { /** * Efficiency log entries * @default [] */ log?: MetricsEfficiencyLogEntry[] /** * Average efficiency value * @default null */ avgEfficiency?: number | null /** * Nominal target efficiency * @default null */ nominalValue?: number | nu… ``` ### `EmptyStateProps` ```typescript type EmptyStateProps = { /** * Description text or ReactNode displayed below the image */ description: ReactNode /** * Image to display. Use "default" for the standard illustration, * "simple" for a minimal icon, or pass a custom ReactNode. * @default "default"… ``` ### `EnabledDisableToggleProps` ```typescript type EnabledDisableToggleProps = { /** Current state. A boolean drives a switch display; non-boolean shows action buttons. */ value: unknown /** Tank identifier used in the label (`Tank {N} Circulation`). Pass an empty string for the air exhaust label. / tankNumber: numb… ``` ### `EnergyBalanceCostChartsProps` ```typescript type EnergyBalanceCostChartsProps = { costChartData: BarChartDataResult btcUnit: EnergyCostChartInput['btcUnit'] powerChartInput: ThresholdLineChartInput displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => void / Sh… ``` ### `EnergyBalanceCostMetricsProps` ```typescript type EnergyBalanceCostMetricsProps = { metrics: EnergyCostMetrics } ``` ### `EnergyBalancePowerChartProps` ```typescript type EnergyBalancePowerChartProps = { / Chart height when `fillHeight` is false * @default 280 */ height?: number /** * Stretch the panel and chart to fill a mosaic cell (uses height `320` and `mdk-energy-balancepanel--fill`). Used on the revenue tab power column in `E… ``` ### `EnergyBalanceProps` ```typescript type EnergyBalanceProps = { /** All display state: chart inputs, metrics, active tab, display modes, loading/error flags. Returned directly by `useEnergyBalanceViewModel`. / viewModel: EnergyBalanceViewModel / Called when the user switches between Revenue and Co… ``` ### `EnergyBalanceRevenueChartsProps` ```typescript type EnergyBalanceRevenueChartsProps = { revenueChartData: BarChartDataResult averageDowntimeData: AverageDowntimeChartData powerChartInput: ThresholdLineChartInput displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => voi… ``` ### `EnergyBalanceRevenueMetricsProps` ```typescript type EnergyBalanceRevenueMetricsProps = { metrics: EnergyRevenueMetrics } ``` ### `EnergyCostChartProps` ```typescript type EnergyCostChartProps = { chartData: BarChartDataResult btcUnit: EnergyCostChartInput['btcUnit'] displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => void height?: number } ``` ### `EnergyMetricCardProps` ```typescript type EnergyMetricCardProps = { / Metric label shown on the card / name: string /** Metric value, formatted via `formatNumber` */ value: number /** Unit suffix shown next to the value */ unit: string /** Text shown when `value` can't be formatted */ fallback?: strin… ``` ### `EnergyReportMinerTypeViewProps` ```typescript type EnergyReportMinerTypeViewProps = EnergyReportGroupedBarViewProps ``` ### `EnergyReportMinerUnitViewProps` ```typescript type EnergyReportMinerUnitViewProps = EnergyReportGroupedBarViewProps ``` ### `EnergyReportProps` ```typescript type EnergyReportProps = { defaultTab?: EnergyReportTabValue siteView?: Omit & { dateRange?: EnergyReportDateRange } minerTypeView?: EnergyReportMinerTypeViewProps minerUnitView?: EnergyReportMinerUnitViewProps className?: s… ``` ### `EnergyReportSiteViewProps` ```typescript type EnergyReportSiteViewProps = Omit & { snapshotLoading?: boolean onRefetchSnapshot?: VoidFunction dateRange: EnergyReportDateRange onDateRangeChange?: (range: EnergyReportDateRange) => void } ``` ### `EnergyRevenueChartProps` ```typescript type EnergyRevenueChartProps = { chartData: BarChartDataResult displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => void height?: number } ``` ### `ErrorCardProps` ```typescript type ErrorCardProps = { /** * Error message string. Supports `\n` for line breaks. */ error: string /** * Title displayed above the error message * @default "Errors" */ title?: string /** * Display variant. "card" shows a bordered container, "inline" shows flat… ``` ### `ExplorerDetailProps` ```typescript type ExplorerDetailProps = { /** The active Explorer tab — selects which per-type panel renders. */ deviceType: DeviceExplorerDeviceType /** * Router navigate used by alarm rows to deep-link into `/alerts/:id`. * @default no-op */ onNavigate?: (path: string) => void… ``` ### `ExplorerLayoutProps` ```typescript type ExplorerLayoutProps = { /** Page heading; nothing renders when omitted */ title?: string /** Optional header controls (export button, etc.) shown next to the title. / headerActions?: ReactNode / The list column — typically a tab switch plus the device/contai… ``` ### `ExportButtonProps` ```typescript type ExportButtonProps = { / Fires with the chosen format when the user picks an item. / onExport: (format: ExportFormat) => void /** * Formats to offer in the dropdown — defaults to `['csv', 'json']`. * @default ['csv', 'json'] */ formats?: readonly ExportForm… ``` ### `FeatureFlagsSettingsProps` ```typescript type FeatureFlagsSettingsProps = { /** Current flag values keyed by flag name */ featureFlags: Record /** Whether editing is permitted */ isEditingEnabled: boolean /** * Show loading state * @default false */ isLoading?: boolean /** * Show saving spinner… ``` ### `FormCascaderProps` ```typescript type FormCascaderProps = BaseFormFieldProps & { options: CascaderOption[] multiple?: boolean cascaderProps?: Omit< React.ComponentProps, 'value' | 'onChange' | 'options' | 'placeholder' > } ``` ### `FormCheckboxProps` ```typescript type FormCheckboxProps = BaseFormFieldProps & { checkboxProps?: React.ComponentProps layout?: 'row' | 'column' } ``` ### `FormDatePickerProps` ```typescript type FormDatePickerProps = BaseFormFieldProps & { datePickerProps?: Omit, 'selected' | 'onSelect'> } ``` ### `FormInputProps` ```typescript type FormInputProps = BaseFormFieldProps & { type?: React.ComponentProps['type'] variant?: React.ComponentProps['variant'] inputProps?: Omit, 'type' | 'variant'> } ``` ### `FormProps` Form wrapper that provides react-hook-form context to child components ```typescript type FormProps = Omit< ComponentProps<'form'>, 'children' > & { form: UseFormReturn children: ReactNode } ``` ### `FormRadioGroupProps` ```typescript type FormRadioGroupProps = BaseFormFieldProps & { options: FormRadioOption[] orientation?: 'horizontal' | 'vertical' radioGroupProps?: Omit< React.ComponentProps, 'onValueChange' | 'defaultValue' | 'orientation' > } ``` ### `FormSelectProps` ```typescript type FormSelectProps = BaseFormFieldProps & { options: FormSelectOption[] selectProps?: Omit, 'onValueChange' | 'defaultValue'> } ``` ### `FormSwitchProps` ```typescript type FormSwitchProps = BaseFormFieldProps & { switchProps?: Omit, 'checked' | 'onCheckedChange'> layout?: 'row' | 'column' } ``` ### `FormTagInputProps` ```typescript type FormTagInputProps = BaseFormFieldProps & { options?: TagInputOption[] allowCustomTags?: boolean variant?: 'default' | 'search' tagInputProps?: Omit< React.ComponentProps, 'value' | 'onTagsChange' | 'label' | 'placeholder'… ``` ### `FormTextAreaProps` ```typescript type FormTextAreaProps = BaseFormFieldProps & { textAreaProps?: React.ComponentProps } ``` ### `GaugeChartProps` ```typescript type GaugeChartProps = { /** Value between 0 and 1 (e.g. 0.75 = 75%). Values outside the range are clamped. */ percent: number /** * Arc colours in HEX format. * @default [COLOR.GREEN, COLOR.RED] */ colors?: string[] /** * Arc thickness as a fraction of the gaug… ``` ### `HashBalanceCostPanelProps` ```typescript type HashBalanceCostPanelProps = HashBalancePanelProps ``` ### `HashBalanceProps` ```typescript type HashBalanceProps = Partial<{ /** * Show error state * @default false */ isError: boolean /** * Show loading state * @default false */ isLoading: boolean /** * Error copy when `isError` * @default 'Error loading hash balance data. Please try again later.' */… ``` ### `HashBalanceRevenuePanelProps` ```typescript type HashBalanceRevenuePanelProps = HashBalancePanelProps & { /** `USD` or `BTC` label for per-PH/day units */ currency: HashBalanceCurrency /** Currency toggle handler */ onCurrencyChange: (currency: HashBalanceCurrency) => void } ``` ### `HashrateMinerTypeViewProps` ```typescript type HashrateMinerTypeViewProps = { /** * Hashrate log grouped by miner type (groupBy=miner). * @default [] */ log?: HashrateGroupedLog /** * Drives the chart spinner * @default false */ isLoading?: boolean /** Selected date range / dateRange?: HashrateDateRange / Fires… ``` ### `HashrateMiningUnitViewProps` ```typescript type HashrateMiningUnitViewProps = { / Hashrate log grouped by container / mining unit (groupBy=container). * @default [] */ log?: HashrateGroupedLog /** * Drives the chart spinner * @default false */ isLoading?: boolean /** Selected date range */ dateRange?: HashrateDa… ``` ### `HashrateProps` ```typescript type HashrateProps = { /** * Tab selected on first render. Defaults to the Site View. * @default "site-view" */ defaultTab?: HashrateTabValue /** Props forwarded to the Site View tab. / siteView?: HashrateSiteViewProps / Props forwarded to the Miner Type Vi… ``` ### `HashrateSiteViewProps` ```typescript type HashrateSiteViewProps = { / Hashrate log grouped by miner type. * @default [] */ log?: HashrateGroupedLog /** * Loading state - drives the chart spinner. * @default false */ isLoading?: boolean /** Selected date range used by the host to drive the query. */ d… ``` ### `HeaderConsumptionBoxProps` ```typescript type HeaderConsumptionBoxProps = { /** Icon shown next to the stat */ icon?: ReactNode /** Current site-level power consumption, in megawatts. */ valueMw?: number /** * Unit label — defaults to `MW`. * @default MW */ unit?: string /** Additional class names */ className?:… ``` ### `HeaderControlsSettingsProps` ```typescript type HeaderControlsSettingsProps = { /** Current header preference values */ preferences: HeaderPreferences /** * Show loading state * @default false */ isLoading?: boolean /** Called when a preference toggle changes */ onToggle: (key: keyof HeaderPreferences, value: boolea… ``` ### `HeaderEfficiencyBoxProps` ```typescript type HeaderEfficiencyBoxProps = { /** Icon shown next to the stat */ icon?: ReactNode /** Efficiency in watts per TH/s. */ valueWthS?: number /** * Unit label — defaults to `W/TH/S`. * @default W/TH/S */ unit?: string /** Additional class names */ className?: string } ``` ### `HeaderHashrateBoxProps` ```typescript type HeaderHashrateBoxProps = { /** Icon shown next to the stat */ icon?: ReactNode /** App-side aggregate hashrate in PH/s. */ appPhs?: number /** Pool-side aggregate hashrate in PH/s. */ poolPhs?: number /** * Hashrate unit label — defaults to `PH/s`. * @default PH/s… ``` ### `HeaderMinersBoxProps` ```typescript type HeaderMinersBoxProps = { /** Icon shown next to the "Miners" label. Caller-provided so the package stays icon-agnostic. */ icon?: ReactNode /** Total miners across the site (denominator of the `158 / 2,188` ratio). / total?: number / Online miners (the `158`… ``` ### `HeaderStatsBarProps` ```typescript type HeaderStatsBarProps = { / Stat boxes to render in order, left-to-right. / children: ReactNode /** Optional class hook. */ className?: string } ``` ### `HeatmapLegendProps` ```typescript type HeatmapLegendProps = { /** Value (or pre-formatted label) at the low end of the scale. */ min: number | string /** Value (or pre-formatted label) at the high end of the scale. */ max: number | string /** Unit suffix appended to `min`/`max`. / unit?: string /… ``` ### `HeatmapProps` ```typescript type HeatmapProps = { /** Rows of cells (row-major). Rows may be ragged. */ data: HeatmapCell[][] /** * Range floor (maps to the first gradient stop); auto-derived from the finite values when omitted. * @default auto */ min?: number /** * Range ceiling (maps… ``` ### `HistoricalAlertsProps` ```typescript type HistoricalAlertsProps = { /** * Pre-fetched historical alerts log entries (each with a `thing` device payload). * @default [] */ alerts?: Alert[] /** * Show DataTable loading overlay * @default false */ isLoading?: boolean /** * Filters and search tags coming fro… ``` ### `ImportExportSettingsProps` ```typescript type ImportExportSettingsProps = { /** Trigger configuration export */ onExport: VoidFunction /** Apply imported configuration */ onImport: (data: SettingsExportData) => void /** Custom file-parsing function / onParseFile?: (file: File) => Promise /… ``` ### `IndicatorProps` ```typescript type IndicatorProps = { / Color variant of the indicator * @default 'gray' */ color?: IndicatorColor /** * Size variant of the indicator * @default 'md' */ size?: ComponentSize /** * Custom className for the root element */ className?: string /** * When tru… ``` ### `InputProps` ```typescript type InputProps = Omit, 'prefix' | 'size'> & { /** * Optional label displayed above the input */ label?: string /** * HTML id for the input. Required when using label for accessibility. * @default auto-generated */ id?: string /** *… ``` ### `LabeledCardProps` ```typescript type LabeledCardProps = Partial<{ /** * Applies a dark background modifier * @default false */ isDark: boolean /** Additional class for the root element */ className: string /** * Prevents content from wrapping * @default false */ hasNoWrap: boolean /** * Sets `p… ``` ### `LineChartCardProps` ```typescript type LineChartCardProps = Partial<{ /** Pre-adapted chart data (use this OR rawData+dataAdapter) */ data: LineChartCardData /** Raw data to be transformed by dataAdapter */ rawData: unknown /** Adapter to transform rawData into LineChartCardData */ dataAdapter: (da… ``` ### `LoaderProps` ```typescript type LoaderProps = { /** * Size of each dot in pixels * @default 10 */ size?: number /** * Number of dots to display * @default 5 */ count?: 3 | 5 | 7 /** * Color variant of the loader * @default 'orange' */ color?: 'red' | 'gray' | 'blue' | 'amber' | 'orang… ``` ### `LogActivityIconProps` ```typescript type LogActivityIconProps = { status: string } ``` ### `LogDotProps` ```typescript type LogDotProps = { /** `'Incidents'` renders a colored circle; `'Activity'` renders an activity icon */ type: string /** Severity string for color mapping */ status: string } ``` ### `LogItemProps` ```typescript type LogItemProps = { data: LogData onLogClicked?: (uuid: string) => void } ``` ### `LogRowProps` ```typescript type LogRowProps = { /** Log entry data */ log: LogData /** Log type (controls dot appearance) */ type: string /** Inline style for the row container */ style?: CSSProperties /** Click handler */ onLogClicked?: (uuid: string) => void } ``` ### `LogsCardProps` ```typescript type LogsCardProps = Partial<{ /** Log type (`'Incidents'` or `'Activity'`); controls the `LogDot` appearance */ type: string /** Card header label */ label: string /** * Applies dark card theme * @default false */ isDark: boolean /** * Shows skeleton rows whi… ``` ### `ManageUserModalProps` ```typescript type ManageUserModalProps = { /** Controls dialog visibility */ open: boolean /** Called when the dialog closes */ onClose: VoidFunction /** The user being edited */ user: SettingsUser /** Available role options */ roles: RoleOption[] /** Permission levels per role *… ``` ### `MdkWordmarkProps` ```typescript type MdkWordmarkProps = { /** * Visual size of the wordmark. `sm` ≈ 24px tall, `md` ≈ 32px, `lg` ≈ 64px * @default 'md' */ size?: MdkWordmarkSize / Optional class hook on the outer `
Foundation
Public, end-to-end but rudimentary]) it1[[Jun–Jul 2026
New release every 2 weeks]] end subgraph lab [Lab testing] p2([Jul 2026
Lab testing
Complete end-to-end, lab only]) it2[[Aug–Oct 2026
New release every 2 weeks]] end subgraph onsite [On site testing] p3([Oct 2026
On site testing
Testing at real sites]) it3[[Nov–Dec 2026
New release every 2 weeks]] end subgraph prod [Production Ready] p4([Dec 2026
Production Ready
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? See it run first These are not a sequence. Run the finished site to see the whole stack, then build your own version of it when you want your own data on your own routes. } title={Run a mining site end to end} href="/tutorials/run-a-site" description={ Run the full example: Workers, mock hardware, a Gateway API, an MCP server, and a live dashboard from one command } /> } title={Build a minimal single-page dashboard} href="/tutorials/build-a-dashboard" description={ Build from an empty directory: one Worker, one Gateway route, and one React page } /> } title={Build a dashboard with an agent} href="/tutorials/ui/react/build-any-dashboard-with-an-agent" description={ Generate it instead: wire Cursor or Claude once, then build from plain-language prompts } /> The Gateway serves only the routes its plugins provide, so getting Worker telemetry to a browser means mounting your own endpoint. Building a dashboard covers that end to end, and [building a Gateway plugin](/guides/gateway/plugins) is the reference for writing your own. ## Next steps - Learn more about the high-level [architecture](/concepts/architecture): runtime stack and deployment modes - Install and wire the [React packages](/guides/ui/install): the provider, hooks, and theming - Integrate your own hardware by [building a third-party Worker](/guides/workers/build-a-worker) - Run a site from the [deployment guides](/guides/deployment) - [Contribute](/support/community/contributing) # Build a minimal single-page dashboard (/tutorials/build-a-dashboard) 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/package.json), the same zero-dependency reference Worker that tutorial is built around. This guide builds the smallest version of [the Starter site example](https://github.com/tetherto/mdk/tree/main/examples/mvp-site) (`examples/mvp-site`): one Worker, one Gateway route, one React page. It teaches the same end-to-end shape, including its UI layer, `@tetherto/mdk-react-devkit` components driven by `@tetherto/mdk-react-adapter` hooks. However, it does so without that example's family-specific adapters, persistence, history, commands, multi-page router, or chart aggregation. This tutorial hand-assembles every piece to teach the wiring. To scaffold a real dashboard app against a stack you already have running, use `mdk create dashboard` and `mdk run dashboard` instead. ## 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 # + render OverviewPage OverviewPage.tsx # polls /overview, renders devkit components ``` No router, no charts, no hand-rolled CSS, just 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/mvp-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 install npm run setup:ui npm run build:ui ``` Running `npm run setup` from the Starter site example (`examples/mvp-site`) is also supported, but it is broader: it installs these backend and UI dependencies plus the Starter site example and UI dependencies and builds the UI packages. - Commands below assume you create a new `examples/minimal-dashboard/` directory alongside `examples/mvp-site/` ### Pick the Worker Use [`backend/workers/samples/demo-worker`](https://github.com/tetherto/mdk/blob/main/backend/workers/samples/demo-worker/package.json) 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. ### Boot Kernel and Worker in the same process The simplest of the three discovery modes ([full trade-offs here](/guides/deployment)): 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 no module of its own: it is an `mdk-contract.json` plus `src/` handler files, loaded from its own directory and instantiated per device by the Worker Runtime. The separate [`demo-worker-caller`](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js) used here owns that runtime, 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](/reference/worker) for the DHT, Local, and Same-process options to use in other deployments. ### 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, with 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", "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/lib/client.js` builds the plugin's client once: ```js 'use strict' const { config } = require('@tetherto/mdk-gateway/plugin') const { createMdkClient } = require('@tetherto/mdk-client') module.exports = createMdkClient(config) ``` `examples/minimal-dashboard/plugins/dashboard/controllers/overview.js`: ```js 'use strict' const mdkClient = require('../lib/client') module.exports = async function overview (req) { const { workers } = await mdkClient.listWorkers() const devices = await Promise.all( workers.flatMap((w) => (w.deviceIds || []).map(async (deviceId) => { const tel = await mdkClient.pullTelemetry(deviceId, 'metrics') return { deviceId, workerId: w.workerId, workerState: w.state, ...tel.metrics } })) ) return { ts: Date.now(), devices } } ``` A controller is `async (req) => value`: return a plain object, the Gateway serializes it to JSON itself; you never touch `res`. `mdkClient` is the same client used everywhere else in MDK, with no knowledge of the underlying MDK Protocol envelope required. With more than one Worker family mixed in (miners, powermeters, sensors, ...) you'd branch by `deviceFamily` instead of spreading `tel.metrics` blindly. [The Starter site's overview controller](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/backend/gateway-plugins/site/controllers/overview.js) shows that pattern once you outgrow this one. ### 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, 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) }) ``` This route accepts any caller, because the Gateway applies no authentication of its own and this controller adds none. Keep the Gateway off untrusted networks while you work. A production deployment needs TLS termination, network policy, and [authentication and authorization inside each controller](/guides/gateway/plugins#auth-and-permissions); write routes additionally need input validation, rate limits, and auditing. Serve the built page from `common.staticRootPath`, not a separate server on its own port. Gateway plugin controllers only receive `(req)`, 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/mvp-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. ### 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/mvp-site/ui` uses, so `@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/mvp-site/ui/vite.config.ts`](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/ui/vite.config.ts) uses for `/site/`: ```ts declare const process: { env: Record } 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 MDK dashboard
``` `examples/minimal-dashboard/ui/src/main.tsx`: `` wires the TanStack Query client `useQuery` needs and resolves the API base URL, exactly as it does in [`examples/mvp-site/ui/src/main.tsx`](https://github.com/tetherto/mdk/blob/main/examples/mvp-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( ) ``` With no `auth` prop, `MdkProvider` defaults to `gatewayRedirectAuth()` (the bundled mining Gateway's OAuth-redirect flow) minus a redirect target — fine for a read-only route with no `"auth": true` requirement, like this one. Pass `auth={noAuth()}` instead for a backend that needs no session at all, or `auth={gatewayRedirectAuth({ oauthBaseUrl })}` to enable sign-in. The [react-adapter auth presets](https://github.com/tetherto/mdk/blob/main/ui/packages/react-adapter/README.md#authentication) cover what each one does and its limits. Create `ui/src/OverviewPage.tsx` under your new `examples/minimal-dashboard/`: `useQuery` polls the route from Step 3 the same way [`examples/mvp-site/ui/src/SitePage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/mvp-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(base: string, path: string): Promise { return fetch(`${base}${path}`).then((res) => { if (!res.ok) throw new Error(`HTTP ${res.status}`) return res.json() as Promise }) } function stateBadgeStatus(state: string): 'success' | 'error' | 'default' { if (state === 'ready') return 'success' if (state === 'offline') return 'error' return 'default' } const columns: DataTableColumnDef[] = [ { accessorKey: 'deviceId', header: 'Device' }, { accessorKey: 'workerId', header: 'Worker' }, { id: 'workerState', header: 'Worker state', cell: ({ row }) => { const state = (row.original.workerState || 'unknown').toLowerCase() return } }, { 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(apiBaseUrl, '/overview'), refetchInterval: 3000 }) return (
data={overview.data?.devices ?? []} columns={columns} getRowId={(row) => row.deviceId} loading={overview.isLoading} enablePagination={false} />
) } ``` A controller is `async (req) => value`; a page is `useQuery` + devkit components, and neither one touches the other's plumbing. `OverviewPage` never imports `mdkClient`, and `overview.js` never imports React. ### 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/`, where 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. ## 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 `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` 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. Compare [`examples/mvp-site/ui/src/DashboardPage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/ui/src/DashboardPage.tsx) and [`examples/mvp-site/backend/gateway-plugins/site/controllers/history.js`](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/backend/gateway-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](/reference/worker). ## 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 a mining site end to end (/tutorials/run-a-site) If Kernel, Gateway, Worker, manager, or thing are unfamiliar, [terminology](/reference/glossary) defines them. ## Overview This tutorial runs the [Starter site example](https://github.com/tetherto/mdk/tree/main/examples/mvp-site) end to end: a Whatsminer worker, an Ocean pool worker, and a SATEC powermeter worker, each backed by mock hardware that speaks the real wire protocol, a Gateway HTTP API, and a React dashboard, all supervised by PM2. What you'll have at the end: - Mock miners, a mock pool, and a mock powermeter, each driven by the real Worker driver code against a localhost mock instead of hardware - A Gateway API on `:3000` serving `/site/overview`, `/site/history`, `/site/miners/:id/command`, and `/site/miners/:id/pools` - A React dashboard on `:3000` with Dashboard, Containers, Monitoring, Pools, and Control pages - One MCP surface on `:3101` exposing the site as tools for AI agents, served by a standalone MCP process: a hand-authored, agent-contract tool set alongside the site Gateway plugin's own routes, read off the same plugin dir the Gateway loads Every component above runs as its own PM2-supervised OS process, discovering the Kernel over a shared local directory rather than a DHT. ## Prerequisites - [Node.js](https://nodejs.org/) >=24 (LTS) - npm 11 [(< 12)](/reference/environment) - PM2 (`npm install -g pm2`) ### 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/mvp-site npm run setup npm run setup:config ``` `setup` installs `backend/core`, [`backend/workers`](/reference/worker), the UI workspace devkit packages, and this example's own dependencies. `setup:config` copies the committed `.json.example` config files into place without overwriting any that already exist. The script walks several workspaces; first run takes 1-2 minutes. ### Start the site ```bash npm start ``` `start.js` generates `deploy/ecosystem.config.js` from `config/site.deploy.json`, starts the PM2 apps, then exits — PM2 itself keeps the processes running in the background. ```bash pm2 list # mocks, mocks-ocean, mocks-satec, kernel, worker, worker-ocean, worker-satec, gateway, mcp ``` Wait for every app to show `online`, then open `http://localhost:3000/` in a browser. The dashboard shows live hashrate, power, and per-device status. PM2 showing every app `online` means the processes started, not that the site has fully settled. The Ocean pool worker ticks its mock fetch/save cycle every 10 seconds, and Kernel's local-discovery scan runs every 4 seconds, so `/site/overview` can report `"pools": 0` for 15-20 seconds after `pm2 list` goes green. Retry the command below if the first response comes back short. Verify via the API: ```bash curl -s http://localhost:3000/site/overview | jq '{miners: (.miners|length), pools: (.pools|length), powermeters: (.powermeters|length)}' ``` Expected output: ```text { "miners": 5, "pools": 1, "powermeters": 1 } ``` `config/devices.json` seeds five miners and one powermeter by default. Add or remove entries there to resize the fleet; [configuring devices](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/README.md#configure-devices) describes the format. ### (Optional) Explore the UI pages The Dashboard, Containers, Monitoring, Pools, and Control pages are all served from `ui/dist` via the Gateway on the same `:3000` port. The Pools page reads the Ocean pool worker's stats; the Monitoring page charts the SATEC meter's power series over time. See [UI pages](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/README.md#ui-pages) for what each one shows. ### (Optional) Connect an AI agent over MCP Agents and connection modes vary; apply the method for your agent. For Claude CLI: `cd examples/mvp-site` `claude` Accept `Use this MCP server` Then your agent can query and act on the site's devices. The example exposes MCP as a single surface on `:3101`, served by a standalone MCP process and listed in `.mcp.json.example`. It carries two tool sources: - A hand-authored tool set with agent-contract metadata — `backend/mcp-plugins/site/mcp-plugin.json` — giving an agent summary-first, closed-vocabulary tools (`summarize_site`, `count_devices`, `list_devices`, `get_device`, `rank_devices`, `act_device`) instead of raw route exports - The site Gateway plugin's own `/site/` routes, read off the same plugin dir the Gateway loads and converted into tools Point an MCP client at that URL and it can query the fleet or, with the agent-contract tools, act on it with operator approval. This local site runs an empty Kernel allowlist; a hardened Kernel restricts the MCP connection through [Kernel's caller allowlist](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/README.md#troubleshooting). ### Stop the site ```bash npm run stop:pm2 ``` This stops and removes every PM2-managed process for this site: mocks, Workers, Kernel, Gateway, and the MCP server. The PM2 daemon itself (`pm2 list` still shows a `God Daemon` process) stays running in the background after this — that's expected, since PM2 manages processes across every project on the machine, not just this one. If it ever becomes unresponsive, see [stale PM2 processes](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/README.md#stale-pm2-processes-after-system-crash) for `pm2 kill`, which stops PM2 itself, not just this site. ## What just happened 1. Setup installed `backend/core`, [`backend/workers`](/reference/worker), the MDK UI devkit, and this example, then `setup:config` seeded its local config from the committed `.example` files. 2. Mock hardware: PM2's `mocks`, `mocks-ocean`, and `mocks-satec` roles each started a mock device server — a Whatsminer miner, an Ocean pool, and a SATEC powermeter — speaking the real wire protocol, so the Worker drivers run their true connect, collect, and command paths against them. 3. Kernel: the `kernel` role started the orchestration layer in local-discovery mode, watching a shared directory for Workers to publish their RPC keys to. 4. Workers: the `worker`, `worker-ocean`, and `worker-satec` roles each dispatched to that family's boot function (`startWhatsminerWorker`, `startOceanPoolWorker`, `startSatecWorker`) to construct a `WorkerRuntime`, seed its devices from `config/devices.json`, and publish its RPC key for the Kernel to discover. 5. Gateway: the `gateway` role mounted the site plugin declared by `backend/gateway-plugins/site/mdk-plugin.json` and the built UI from `ui/dist`, then opened the HTTP server on `:3000`. The plugin aggregates data across the three Workers through `mdkClient`. 6. MCP: the `mcp` role started the standalone MCP process on `:3101`, serving both tool sources — the hand-authored agent-contract tool set and the site Gateway plugin's own routes, derived from the same plugin dir the Gateway loads. ## Resetting state State (Kernel key, Worker seeds, device registry) persists in `.site-data/`. If you change `config/devices.json` after the first run, [reset it](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/README.md#reset-state) before restarting — seed devices are only registered once, on an empty store. ## Next steps - Fix a failed boot, a port clash, or stale PM2 processes with the example's troubleshooting section - Register real hardware instead of mocks by [configuring devices](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/README.md#configure-devices) - Build the same shape from an empty directory with one Worker and one route: [build a minimal single-page dashboard](/tutorials/build-a-dashboard) - Serve your own data by [adding custom plugins to the Gateway HTTP API](/guides/gateway/plugins) - Integrate your own hardware by [building a third-party Worker](/guides/workers/build-a-worker) - Run the same PM2-supervised model as a production deployment, or across hosts with DHT discovery, with the [supervised-services deployment guide](/guides/deployment/run-all-workers-site) - Go beyond querying the site's MCP tools by hand: connect [the conversational operator agent](/guides/agent), which calls the same tools and gates writes behind human approval - See the full 11-worker fleet — three miner families, containers, sensors, and two pools — in [`examples/full-site`](https://github.com/tetherto/mdk/tree/main/examples/full-site) - Browse [every runnable example in one place](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md) # 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, using the same flow every MDK agent session uses: [put `mdk` on your PATH](/guides/cli), [install the skill suite once](/guides/ui/agent-skills), then state what you want in plain language. ## 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 [a mining dashboard](/tutorials/build-a-dashboard). What will you build? IoT fleet backend reporting, workout metrics motivation app, weather stats? Your data; your choice. You'll ask for a statistics tutorial page so students can explore distributions, trends, and raw grades, and see every: - Lookup the agent makes against the [skill suite](/guides/ui/agent-skills) - Resulting page code - Run instructions 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. ## 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. Install the CLI → install the skills → plain-language intent → local registry lookup → build → typecheck. 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 - `mdk` on your PATH: [Install the CLI](/guides/cli) - The MDK React packages installed and wired: [Install and wire the React packages](/guides/ui/install)
This walkthrough uses `apps/stats-lab`, same pattern as [Install and wire the React packages](/guides/ui/install).
## Agent session walkthrough ### Install the skill suite (once per project) `cd` to your app or monorepo project root. Do not run this from the CLI checkout: ```bash mdk skill add --client cursor ``` This installs the MDK Developer Skill suite into `.cursor/skills/` (use `--client claude` for `.claude/skills/`, or omit `--client` for both), so the session knows MDK's conventions and carries the component registry. Full flag list: [Agent skills](/guides/ui/agent-skills#install). ### 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 the same whatever the domain: discover exports, scaffold, and verify compile. ### Lookups the agent makes Behind the prompt, the `mdk-ui-component` skill activates and a well-behaved session reads its bundled `references/ui-registry.json` — a deterministic file lookup, no model or network calls. A representative pass: The intent names four visuals, so the agent resolves each against `indexes.componentsByCategory` in the registry: | Intent | Category | Candidates | |--------|----------|------------| | Histogram of exam scores | `charts` | `BarChart` | | Weekly average trend | `charts` | `LineChart` | | Sortable student list | `tables` | `DataTable` | | Mean, median, enrollment | `cards` | `SingleStatCard` | Because we asked for mock data only, the agent skips the adapter hooks like `useDevices` that a live-data page would bind. For each shortlisted component the agent opens its `indexes.componentsByName` entry and copies the prop list verbatim — names, types, and which are required. That is where real shapes like `LineChartData`'s millisecond `x` values and `DataTableColumnDef` accessors come from, instead of an invented API. Each entry also points at the component's `USAGE.md` and its runnable `.example.tsx`, both shipped in the devkit, for the cases where the prop table alone is not enough. The skill's layer model puts mock datasets and labels in the page, and the visuals in panels that take props. Nothing is scaffolded from a template — the agent writes the page against the registry's contracts, then verifies: ```bash npm run typecheck ``` Type-checking against the real package barrels catches a wrong prop name or shape immediately; the app build in the local run verifies the final Vite project. Full skill reference: [Agent skills](/guides/ui/agent-skills). ### Review the generated 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([]) 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[] = [ { accessorKey: 'name', header: 'Student' }, { accessorKey: 'section', header: 'Section' }, { accessorKey: 'midterm', header: 'Midterm' }, { accessorKey: 'final', header: 'Final' }, ] return (

Stats Lab

Intro statistics — interpret distributions and trends

Charts Roster

Final exam distribution

Weekly class average

) } ``` Nothing in this file references pools, workers, or TH/s. The same components appear on mining pages because the data model is generic. ## Run Stats Lab locally Follow the same monorepo workflow as [installing and wiring the React packages](/guides/ui/install). If you already did that, skip to Run the app with `stats-lab` as the workspace name. ### Clone and build the UI monorepo ```bash git clone https://github.com/tetherto/mdk.git cd mdk ``` ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` ```bash npm install npm run build ``` ### 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 ``` ### Wrap with `MdkProvider` In `apps/stats-lab/src/main.tsx`, mirror [Wrap your app in MdkProvider](/guides/ui/install#wrap-your-app-in-mdkprovider): ```tsx // … ``` Mock data does not call the API; the provider satisfies components that expect React context. ### 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. ### Optional: compare with the MDK demo app Same commands as in the [install guide](/guides/ui/install): ```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. ## Why the agent stays accurate The registry lists real exports with their prop types and usage docs, so the agent can't invent props that don't exist. `npm run typecheck` remains the final verification against the real component APIs, and the app build catches the rest. ## Next steps - [Install and wire the React packages](/guides/ui/install): the provider, hooks, and theming your generated pages rely on, and the manual path if you'd rather not use an agent - [Agent skills](/guides/ui/agent-skills): the skill suite behind the lookups above - [Chart components](/reference/ui/components/charts): `BarChart`, `LineChart`, and related data shapes - [Data display](/reference/ui/components/display): `DataTable` sorting and pagination