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

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

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

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

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

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

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

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

(1.3 Optional) Smoke test the stack

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

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

Full command reference

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

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

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

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

{open ? children : null}

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

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

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

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

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

{datePicker} {dateRange && (

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

)}

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

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

{datePicker} {errors.length > 0 &&

{errors.join(', ')}

}

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

{viewModel.isLoading &&

Loading…

} {viewModel.errors.length > 0 &&

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

}

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

{pool.name}

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

Hashrate: {containerHashRate}

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

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

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

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

return

Active session

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

Selected: {selectedDevices.length}

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

{pendingSubmissions.length} pending submissions

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

{datePicker} {isLoading &&

Loading…

} {error &&

Failed to load cost data

}

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

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

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

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

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

No subsidy fee data for this period.

return (

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

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

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

) } ``` ### `useUpdateExistedActions` @tetherto/mdk-react-devkit/foundation Mutation hook that updates only the changed fields of an existing action record. ```tsx ``` #### Example ```tsx function DeviceActionBar({ actionType, pendingSubmissions, selectedDevices }) { const { updateExistedActions } = useUpdateExistedActions() const handleApply = () => { updateExistedActions({ actionType, pendingSubmissions, selectedDevices }) } return ( ) } ``` ## TanStack Query re-exports The adapter re-exports a curated set of [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview) hooks so you can import data-fetching primitives from a single package alongside MDK helpers. The re-exports are unmodified — refer to the upstream TanStack Query documentation for full API details. | Hook | TanStack docs | | --- | --- | | `useQuery` | [TanStack `useQuery`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) | | `useMutation` | [TanStack `useMutation`](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) | | `useQueries` | [TanStack `useQueries`](https://tanstack.com/query/latest/docs/framework/react/reference/useQueries) | | `useInfiniteQuery` | [TanStack `useInfiniteQuery`](https://tanstack.com/query/latest/docs/framework/react/reference/useInfiniteQuery) | | `useIsFetching` | [TanStack `useIsFetching`](https://tanstack.com/query/latest/docs/framework/react/reference/useIsFetching) | | `useIsMutating` | [TanStack `useIsMutating`](https://tanstack.com/query/latest/docs/framework/react/reference/useIsMutating) | | `useQueryClient` | [TanStack `useQueryClient`](https://tanstack.com/query/latest/docs/framework/react/reference/useQueryClient) | # UI CLI reference (/reference/app-toolkit/ui-cli) The **UI CLI** (`mdk-ui`, package `@tetherto/mdk-ui-cli`) is the command surface your AI agent uses to build with MDK. You usually never run it yourself, your agent does, after you [wire your IDE](/quickstart/connect-agents). This page documents the commands for when you want to drive or inspect the tooling by hand. Every command runs locally and prints JSON by default. Add `--format table` for human-readable output. There are no network or model calls: each command is a lookup against files MDK ships. ## At a glance | Bucket | Section | What it covers | |--------|---------|----------------| | Set up | [Set up a project](#set-up-a-project) | Wire your IDE with `init` | | Discover | [Discover what to use](#discover-what-to-use) | `suggest`, `hooks`, `stores`, `find` | | Read | [Read a component contract](#read-a-component-contract) | `docs`, `example` | | Recipes | [Follow a recipe](#follow-a-recipe) | `blueprints`, `blueprint` | | Scaffold | [Scaffold and verify](#scaffold-and-verify) | `add page`, `check`, `sync` | | Inspect | [Inspect the UI CLI itself](#inspect-the-ui-cli-itself) | `--json-help` | ## All commands | Command | Summary | |---------|---------| | [`init`](#init) | Bootstrap `.mdk/context.md` and IDE rules | | [`suggest`](#suggest) | Ranked shortlist from free-text intent | | [`hooks`](#hooks) | List adapter hooks (optional `--category`) | | [`stores`](#stores) | List Zustand stores and query helpers | | [`find`](#find) | Filter components by domain and capability | | [`docs`](#docs) | Print a component's `USAGE.md` | | [`example`](#example) | Print a runnable `*.example.tsx` | | [`blueprints`](#blueprints) | List curated intent-to-component recipes | | [`blueprint`](#blueprint) | Show one recipe in detail | | [`add page`](#add-page) | Scaffold a page with chosen components | | [`check`](#check) | Type-check a file against real APIs | | [`sync`](#sync) | Refresh `.mdk/context.md` | | [`--json-help`](#json-help) | Machine-readable CLI surface | ## The agent's decision flow Given an intent, the deterministic path a session follows is: ```mermaid flowchart TD intent["Plain-language intent"] suggest["mdk-ui suggest"] state{"State or hooks needed?"} hooks["mdk-ui hooks / stores"] blueprints["mdk-ui blueprints"] match{"Matching blueprint?"} blueprint["mdk-ui blueprint"] find["mdk-ui find"] docs["mdk-ui docs / example"] add["mdk-ui add page"] check["mdk-ui check"] intent --> suggest suggest --> state state -->|yes| hooks state -->|no| blueprints hooks --> add blueprints --> match match -->|yes| blueprint match -->|no| find blueprint --> docs find --> docs docs --> add add --> check ``` ## Set up a project ### init Bootstraps the current project with an agent-context file and an IDE rule so every AI session is wired automatically: ```bash npx @tetherto/mdk-ui-cli init --ide cursor # .mdk/context.md + .cursor/rules/mdk.mdc npx @tetherto/mdk-ui-cli init --ide claude # .mdk/context.md + CLAUDE.md ``` ## Discover what to use ### suggest Turns free text into a ranked shortlist across components, hooks, blueprints, and stores: ```bash mdk-ui suggest "show hashrate for a pool" ``` ### hooks Lists every hook exported from `@tetherto/mdk-react-adapter`, grouped by category (`store`, `utility`, `permission`, `ui`, `external`): ```bash mdk-ui hooks --format table # all adapter hooks mdk-ui hooks --category store --format table # store-binding hooks only ``` ### stores Describes the Zustand stores and TanStack Query helpers from `@tetherto/mdk-ui-foundation`: ```bash mdk-ui stores --format table # stores and query helpers mdk-ui stores --category devices --format table ``` ### find Filters the component library by domain and capability: ```bash mdk-ui find --domain mining-operations --capability hashrate-monitoring ``` ## Read a component contract ### docs Prints a component's usage notes: ```bash mdk-ui docs LineChartCard ``` ### example Prints a runnable example: ```bash mdk-ui example LineChartCard ``` ## Follow a recipe Blueprints are curated recipes that map a high-level intent to a concrete set of components and hooks. ### blueprints Lists available recipes: ```bash mdk-ui blueprints ``` ### blueprint Shows one recipe in detail: ```bash mdk-ui blueprint device-management ``` ## Scaffold and verify ### add page Scaffolds a page with the components you name: ```bash mdk-ui add page Dashboard --component LineChartCard ``` ### check Confirms a file compiles against the real component APIs: ```bash mdk-ui check src/pages/Dashboard.tsx ``` ### sync Keeps the `.mdk/context.md` agent-context file current as MDK updates: ```bash mdk-ui sync ``` ## Inspect the UI CLI itself ### json-help `--json-help` prints the full command surface, useful for meta-tooling that wants to discover commands without running them: ```bash mdk-ui --json-help ``` ## Next steps - [Build dashboards with your AI agent](/quickstart/connect-agents): the two-step flow most developers use - [UI Devkit](/reference/ui): the component library these commands draw from - [MDK repositories](/support/resources/repositories): source for the UI CLI and the agent-ready contract # UI Devkit (/reference/app-toolkit/ui-devkit) The UI Devkit is the frontend tools half of the [MDK App Toolkit](/concepts/stack/app-toolkit). This reference documents its constants, React hooks, TypeScript types, and helper utilities. ## Browse by topic | Topic | What's there | |-------|--------------| | [Constants](/reference/app-toolkit/ui-devkit/constants) | Colors, units, currency, chart configs and permissions, roles, header preferences| | [Hooks](/reference/app-toolkit/ui-devkit/hooks) | Discover hooks for monitoring and UI patterns; full reference at [Hooks](/reference/app-toolkit/hooks) | | [Types](/reference/app-toolkit/ui-devkit/types) | TypeScript type exports. UI primitives and domain models like `Device`, `Alert` | | [Utilities](/reference/app-toolkit/ui-devkit/utilities) | Helper functions for formatting, validation, conversions, and settings persistence | ## Browse by package If you're working with a specific package, use these per-package shortcuts: ### `@tetherto/mdk-react-devkit/core` - [Constants](/reference/app-toolkit/ui-devkit/constants#core-constants) - [Types](/reference/app-toolkit/ui-devkit/types#core-types) - [Utilities](/reference/app-toolkit/ui-devkit/utilities#core-utilities) ### `@tetherto/mdk-react-devkit/foundation` - [Constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants) - [Types](/reference/app-toolkit/ui-devkit/types#foundation-types) - [Utilities](/reference/app-toolkit/ui-devkit/utilities#foundation-utilities) - [Hooks](/reference/app-toolkit/hooks) — every App Toolkit hook (state, components, utilities) lives on a single overview page now. ### `@tetherto/mdk-ui-foundation` - [Alert utilities](/reference/app-toolkit/ui-devkit/utilities#ui-foundation-alert-utilities) — alert query-parameter builders and time-range chunking helpers # Constants (/reference/app-toolkit/ui-devkit/constants) This page documents constants exported by the MDK packages. Constants live in two distinct domains: - [Core constants](#core-constants) ships UI primitives: colors, units, currency symbols, chart defaults - [Foundation constants](#foundation-constants) ships mining-domain values: permissions, roles, header preferences, error codes ## Core constants UI primitive constants exported by `@tetherto/mdk-react-devkit/core` — colors, units, currency symbols, and chart defaults. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ### Import @tetherto/mdk-react-devkit/core ```tsx COLOR, UNITS, CURRENCY, CHART_COLORS, TABLE_COLORS, HASHRATE_LABEL_DIVISOR, } from '@tetherto/mdk-react-devkit/core' ``` ### Color constants #### `COLOR` @tetherto/mdk-react-devkit/core Comprehensive color palette with 80+ named colors. ```tsx COLOR.GREEN // '#72F59E' COLOR.RED // '#EF4444' COLOR.COLD_ORANGE // '#F7931A' ``` ##### Base colors | Constant | Value | Description | |----------|-------|-------------| | `WHITE` | `#FFFFFF` | Pure white | | `BLACK` | `#17130F` | Standard black | | `DARK_BACK` | `#1A1815` | Dark background | | `EBONY` | `#0f0f0f` | Chart background | | `TRANSPARENT` | `transparent` | Transparent | ##### Status colors | Constant | Value | Description | |----------|-------|-------------| | `GREEN` | `#72F59E` | Success/online | | `RED` | `#EF4444` | Error/danger | | `YELLOW` | `#FFC107` | Warning | | `BRIGHT_YELLOW` | `#EAB308` | Bright warning | | `LIGHT_BLUE` | `#22AFFF` | Info | | `SLEEP_BLUE` | `#3B82F6` | Sleep/standby | ##### Brand colors | Constant | Value | Description | |----------|-------|-------------| | `COLD_ORANGE` | `#F7931A` | Bitcoin orange | | `ORANGE` | `#FF6A00` | Primary orange | | `EMERALD` | `#009393` | Teal accent | | `INDIGO` | `#5B5FFB` | Purple accent | #### `TABLE_COLORS` @tetherto/mdk-react-devkit/core Colors for table styling. ```tsx TABLE_COLORS.HEADER_BG TABLE_COLORS.ROW_HOVER ``` #### `HEATMAP` @tetherto/mdk-react-devkit/core `HEATMAP` color scale for temperature and intensity displays. ```tsx ``` #### `CHART_COLORS` @tetherto/mdk-react-devkit/core Default chart color palette. ```tsx ``` #### `PIE_CHART_COLORS` @tetherto/mdk-react-devkit/core Color palette for pie and doughnut charts. ```tsx ``` #### `CATEGORICAL_COLORS` @tetherto/mdk-react-devkit/core 25-color categorical palette for multi-series charts. ```tsx CATEGORICAL_COLORS[0] // First color CATEGORICAL_COLORS[24] // Last color ``` #### `TEMPERATURE_COLORS` @tetherto/mdk-react-devkit/core Color scale for temperature displays. ```tsx ``` #### `SOCKET_BORDER_COLOR` @tetherto/mdk-react-devkit/core Colors for socket status indicators. ```tsx ``` ### Unit constants #### `UNITS` @tetherto/mdk-react-devkit/core Physical and measurement units. ```tsx UNITS.POWER_W // 'W' UNITS.POWER_KW // 'kW' UNITS.ENERGY_MWH // 'MWh' UNITS.TEMPERATURE_C // '°C' UNITS.HASHRATE_TH_S // 'TH/s' ``` | Constant | Value | Description | |----------|-------|-------------| | `POWER_W` | `W` | Watts | | `POWER_KW` | `kW` | Kilowatts | | `ENERGY_WH` | `Wh` | Watt-hours | | `ENERGY_KWH` | `kWh` | Kilowatt-hours | | `ENERGY_MW` | `MW` | Megawatts | | `ENERGY_MWH` | `MWh` | Megawatt-hours | | `ENERGY_GWH` | `GWh` | Gigawatt-hours | | `TEMPERATURE_C` | `°C` | Celsius | | `VOLTAGE_V` | `V` | Volts | | `AMPERE` | `A` | Amperes | | `PERCENT` | `%` | Percentage | | `PRESSURE_BAR` | `bar` | Pressure (bar) | | `HASHRATE_MH_S` | `MH/s` | Megahash/second | | `HASHRATE_TH_S` | `TH/s` | Terahash/second | | `HASHRATE_PH_S` | `PH/s` | Petahash/second | | `HASHRATE_EH_S` | `EH/s` | Exahash/second | | `FREQUENCY_MHZ` | `MHz` | Megahertz | | `FREQUENCY_HERTZ` | `Hz` | Hertz | | `HUMIDITY_PERCENT` | `%RH` | Relative humidity | | `EFFICIENCY_W_PER_TH` | `W/TH` | Watts per terahash | | `FLOW_M3H` | `m3/h` | Flow rate | | `SATS` | `Sats` | Satoshis | | `VBYTE` | `vByte` | Virtual bytes | #### `CURRENCY` @tetherto/mdk-react-devkit/core Currency symbols and labels. ```tsx CURRENCY.BTC // '₿' CURRENCY.USD // '$' CURRENCY.EUR // '€' CURRENCY.SATS // 'Sats' CURRENCY.BTC_LABEL // 'BTC' CURRENCY.USD_LABEL // 'USD' ``` #### `MAX_UNIT_VALUE` @tetherto/mdk-react-devkit/core Maximum values for certain units. ```tsx MAX_UNIT_VALUE.HUMIDITY_PERCENT // 100 MAX_UNIT_VALUE.TEMPERATURE_PERCENT // 100 ``` #### `HASHRATE_LABEL_DIVISOR` @tetherto/mdk-react-devkit/core Divisors for converting hashrate units. ```tsx HASHRATE_LABEL_DIVISOR['TH/s'] // 1e6 HASHRATE_LABEL_DIVISOR['PH/s'] // 1e9 HASHRATE_LABEL_DIVISOR['EH/s'] // 1e12 ``` ### Chart constants #### `defaultChartColors` @tetherto/mdk-react-devkit/core Default color array for chart datasets. ```tsx ``` #### `defaultChartOptions` @tetherto/mdk-react-devkit/core Default [Chart.js](https://www.chartjs.org/) options. ```tsx ``` #### `CHART_LEGEND_OPACITY` @tetherto/mdk-react-devkit/core Opacity values for chart legends. ```tsx ``` #### `CHART_PERFORMANCE` @tetherto/mdk-react-devkit/core Performance threshold constants for charts. ```tsx ``` #### `getChartAnimationConfig` @tetherto/mdk-react-devkit/core Get animation configuration based on data count. ```tsx const animConfig = getChartAnimationConfig(dataPointCount) ``` #### `getDataDecimationConfig` @tetherto/mdk-react-devkit/core Get data decimation configuration for large datasets. ```tsx const decimationConfig = getDataDecimationConfig(dataPointCount) ``` ### Type exports The constants module also exports TypeScript types: ```tsx UnitKey, UnitValue, CurrencyKey, CurrencyValue, } from '@tetherto/mdk-react-devkit/core' ``` ## Foundation constants Constants exported by `@tetherto/mdk-react-devkit/foundation`: app identity, dialog flows, header preferences, permissions, roles, and error codes. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ### Import @tetherto/mdk-react-devkit/foundation ```tsx WEBAPP_NAME, WEBAPP_SHORT_NAME, WEBAPP_DISPLAY_NAME, POSITION_CHANGE_DIALOG_FLOWS, HEADER_ITEMS, DEFAULT_HEADER_PREFERENCES, AUTH_PERMISSIONS, AUTH_LEVELS, USER_ROLE, USER_ROLES, PERM_LEVEL_LABELS, getRoleBadgeColors, } from '@tetherto/mdk-react-devkit/foundation' ``` ### App identity Brand strings the foundation UI uses to label the running web app in header rows, chart legends, settings export errors, and confirmation copy. The kit ships placeholder defaults; consumers read them via the named imports. #### `WEBAPP_NAME` @tetherto/mdk-react-devkit/foundation Inline name used in confirmations and the `parseSettingsFile` import-error message. ```tsx WEBAPP_NAME // 'Appl.' ``` #### `WEBAPP_SHORT_NAME` @tetherto/mdk-react-devkit/foundation Compact label embedded in [`HEADER_ITEMS`](#header_items) for the in-app miner and hashrate header rows. ```tsx WEBAPP_SHORT_NAME // 'APP' ``` #### `WEBAPP_DISPLAY_NAME` @tetherto/mdk-react-devkit/foundation Display name used in chart legends, including the hash-rate line chart series label. ```tsx WEBAPP_DISPLAY_NAME // 'Application' ``` ### Dialog flows #### `POSITION_CHANGE_DIALOG_FLOWS` @tetherto/mdk-react-devkit/foundation Flow keys consumed by [`PositionChangeDialog`](/reference/ui/react/foundation/operations/details-view/fleet-management#positionchangedialog) and its sibling dialogs to route between step-specific surfaces. ```tsx POSITION_CHANGE_DIALOG_FLOWS.MAINTENANCE // 'maintenance' POSITION_CHANGE_DIALOG_FLOWS.REPLACE_MINER // 'replaceMiner' ``` | Constant | Value | Description | |----------|-------|-------------| | `CONFIRM_REMOVE` | `remove` | Render the remove-miner confirmation surface | | `CHANGE_INFO` | `changeInfo` | Edit info for an existing miner | | `MAINTENANCE` | `maintenance` | Move a miner to (or back from) the maintenance container | | `REPLACE_MINER` | `replaceMiner` | Replace the miner currently occupying a socket | | `CONFIRM_CHANGE_POSITION` | `confirmChange` | Confirm a position change between sockets | | `CONTAINER_SELECTION` | `containerSelection` | Pick a destination container and socket | #### `PositionChangeDialogFlowKey` type @tetherto/mdk-react-devkit/foundation ```tsx type PositionChangeDialogFlowKey = keyof typeof POSITION_CHANGE_DIALOG_FLOWS ``` #### `PositionChangeDialogFlowValue` type @tetherto/mdk-react-devkit/foundation ```tsx type PositionChangeDialogFlowValue = (typeof POSITION_CHANGE_DIALOG_FLOWS)[PositionChangeDialogFlowKey] ``` ### Header controls #### `HEADER_ITEMS` @tetherto/mdk-react-devkit/foundation Array of header metric options for the [`HeaderControlsSettings`](/reference/ui/react/foundation/settings/header-controls) component. ```tsx ``` | Key | Label | |-----|-------| | `poolMiners` | `Pool Miners` | | `miners` | `` `${WEBAPP_SHORT_NAME} Miners` `` | | `poolHashrate` | `Pool Hashrate` | | `hashrate` | `` `${WEBAPP_SHORT_NAME} Hashrate` `` | | `consumption` | `Consumption` | | `efficiency` | `Efficiency` | The two in-app rows compose their labels from [`WEBAPP_SHORT_NAME`](#webapp_short_name); with the shipped default that renders as `APP Miners` and `APP Hashrate`. #### `DEFAULT_HEADER_PREFERENCES` @tetherto/mdk-react-devkit/foundation Default visibility state for all header items (all `true`). ```tsx DEFAULT_HEADER_PREFERENCES.poolMiners // true DEFAULT_HEADER_PREFERENCES.consumption // true ``` #### `HeaderPreferences` type @tetherto/mdk-react-devkit/foundation ```tsx type HeaderPreferences = { poolMiners: boolean miners: boolean poolHashrate: boolean hashrate: boolean consumption: boolean efficiency: boolean } ``` ### Permissions #### `AUTH_PERMISSIONS` @tetherto/mdk-react-devkit/foundation Permission resource identifiers. ```tsx AUTH_PERMISSIONS.USERS // 'users' AUTH_PERMISSIONS.SETTINGS // 'settings' AUTH_PERMISSIONS.MINER // 'miner' ``` | Constant | Value | Description | |----------|-------|-------------| | `USERS` | `users` | User management | | `SETTINGS` | `settings` | Application settings | | `MINER` | `miner` | Miner operations | | `ALERTS` | `alerts` | Alert management | | `ACTIONS` | `actions` | Action execution | | `EXPLORER` | `explorer` | Device explorer | | `INVENTORY` | `inventory` | Inventory management | | `CONTAINER` | `container` | Container management | | `PRODUCTION` | `production` | Production data | | `REPORTING` | `reporting` | Reports | #### `AUTH_LEVELS` @tetherto/mdk-react-devkit/foundation Permission access levels. ```tsx AUTH_LEVELS.READ // 'r' AUTH_LEVELS.WRITE // 'w' ``` #### `USER_ROLE` @tetherto/mdk-react-devkit/foundation User role identifiers. ```tsx USER_ROLE.ADMIN // 'admin' USER_ROLE.SITE_MANAGER // 'site_manager' USER_ROLE.READ_ONLY // 'read_only_user' ``` | Constant | Value | |----------|-------| | `ADMIN` | `admin` | | `SITE_MANAGER` | `site_manager` | | `SITE_OPERATOR` | `site_operator` | | `FIELD_OPERATOR` | `field_operator` | | `REPAIR_TECHNICIAN` | `repair_technician` | | `REPORTING_TOOL_MANAGER` | `reporting_tool_manager` | | `READ_ONLY` | `read_only_user` | ### Settings #### `USER_ROLES` @tetherto/mdk-react-devkit/foundation Array of role options for select dropdowns. ```tsx // [{ label: 'Admin', value: 'admin' }, ...] ``` #### `PERM_LEVEL_LABELS` @tetherto/mdk-react-devkit/foundation Human-readable labels for permission levels. ```tsx PERM_LEVEL_LABELS.rw // 'Read & Write' PERM_LEVEL_LABELS.r // 'Read Only' PERM_LEVEL_LABELS.none // 'No Access' ``` #### `SETTINGS_ERROR_CODES` @tetherto/mdk-react-devkit/foundation Error code to message mapping. ```tsx SETTINGS_ERROR_CODES.ERR_USER_EXISTS // 'User already exists' SETTINGS_ERROR_CODES.DEFAULT // 'An error occurred' ``` ### Role styling #### `getRoleBadgeColors` @tetherto/mdk-react-devkit/foundation Get badge colors for a role. ```tsx const { color, bgColor } = getRoleBadgeColors('admin') // { color: '#e8833a', bgColor: 'rgba(232, 131, 58, 0.1)' } ``` | Role | Color | Background | |------|-------|------------| | `admin` | `#e8833a` | Orange tint | | `site_manager` | `#52c41a` | Green tint | | `site_operator` | `#faad14` | Yellow tint | | `read_only_user` | `#8c8c8c` | Gray tint | # Hooks (/reference/app-toolkit/ui-devkit/hooks) Hooks shipped by `@tetherto/mdk-react-devkit`. For the full catalog — including adapter data hooks and state hooks from `@tetherto/mdk-react-adapter` — see the [Hooks reference](/reference/app-toolkit/hooks). Use the groups below to browse by concern; each hook name links to its entry in that reference. ## Available hooks | Group | Hooks | |---|---| | [Monitoring](/reference/app-toolkit/hooks) | [`useChartDataCheck`](/reference/app-toolkit/hooks/components#usechartdatacheck), [`useBeepSound`](/reference/app-toolkit/hooks/utilities#usebeepsound), [`useEnergyReportSite`](/reference/app-toolkit/hooks/components#useenergyreportsite), [`useHashrate`](/reference/app-toolkit/hooks/components#usehashrate) | | [UI](/reference/app-toolkit/hooks) | [`useNotification`](/reference/app-toolkit/hooks/components#usenotification), [`useHeaderControls`](/reference/app-toolkit/hooks/components#useheadercontrols), [`useSidebarExpandedState`](/reference/app-toolkit/hooks/components#usesidebarexpandedstate), [`useSidebarSectionState`](/reference/app-toolkit/hooks/components#usesidebarsectionstate), [`useHasPerms`](/reference/app-toolkit/hooks/utilities#usehasperms), [`useCheckPerm`](/reference/app-toolkit/hooks/utilities#usecheckperm), [`useLocalStorage`](/reference/app-toolkit/hooks/utilities#uselocalstorage), [`usePagination`](/reference/app-toolkit/hooks/utilities#usepagination), [`useIsFeatureEditingEnabled`](/reference/app-toolkit/hooks/utilities#useisfeatureeditingenabled) | # Types (/reference/app-toolkit/ui-devkit/types) This page documents the TypeScript types exported by the MDK packages. The two packages cover different territory: - [Core types](#core-types) ships **UI primitive types**: sizes, variants, colors, status, common API and chart shapes. These are the building blocks consumed by core components and re-used in your own component prop types. - [Foundation types](#foundation-types) ships **mining-domain models**: `Device`, `Container`, `Alert`, `MinerStats`, settings shapes. These describe the data flowing through foundation components and the API responses they consume. ## Core types UI primitive types exported by `@tetherto/mdk-react-devkit/core` — sizes, variants, colors, status, and common API and chart shapes. These are the building blocks consumed by core components and re-used in your own component prop types. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ### Import @tetherto/mdk-react-devkit/core ```tsx ComponentSize, ButtonVariant, ColorVariant, Status, ApiResponse, } from '@tetherto/mdk-react-devkit/core' ``` ### Common types #### `ComponentSize` @tetherto/mdk-react-devkit/core Standard size variants used across multiple components. ```tsx type ComponentSize = 'sm' | 'md' | 'lg' ``` Used by: `Button`, `Badge`, `Checkbox`, `Switch`, `Radio`, `Spinner`, `Indicator`, `EmptyState`, `Pagination`. #### `ButtonSize` @tetherto/mdk-react-devkit/core Extends `ComponentSize` with an icon-only variant. ```tsx type ButtonSize = ComponentSize | 'icon' ``` #### `BorderRadius` @tetherto/mdk-react-devkit/core Border radius variants for form components. ```tsx type BorderRadius = 'none' | 'small' | 'medium' | 'large' | 'full' ``` Used by: `Checkbox`, `Switch`, `Radio`. #### `ColorVariant` @tetherto/mdk-react-devkit/core Comprehensive color variants for components. ```tsx type ColorVariant = | 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' ``` #### `StatusVariant` @tetherto/mdk-react-devkit/core Status variants for state indication. ```tsx type StatusVariant = 'success' | 'processing' | 'error' | 'warning' | 'default' | 'idle' ``` Used by: badges, notifications, status indicators. #### `ComponentColor` @tetherto/mdk-react-devkit/core Color options for form components. ```tsx type ComponentColor = 'default' | 'primary' | 'success' | 'warning' | 'error' ``` Used by: `Checkbox`, `Switch`, `Radio`, `Typography`. #### `Position` @tetherto/mdk-react-devkit/core Position/side options for UI elements. ```tsx type Position = 'top' | 'right' | 'bottom' | 'left' ``` Used by: `Tooltip`, `Popover`, chart legends. #### `TextAlign` @tetherto/mdk-react-devkit/core Text alignment options. ```tsx type TextAlign = 'left' | 'center' | 'right' | 'justify' ``` #### `FlexAlign` @tetherto/mdk-react-devkit/core Flex/grid alignment options. ```tsx type FlexAlign = 'start' | 'center' | 'end' ``` ### Component types #### `ButtonVariant` @tetherto/mdk-react-devkit/core Button visual variants. ```tsx type ButtonVariant = | 'primary' | 'secondary' | 'danger' | 'tertiary' | 'link' | 'icon' | 'outline' | 'ghost' ``` #### `ButtonIconPosition` @tetherto/mdk-react-devkit/core Where icons appear in buttons. ```tsx type ButtonIconPosition = 'left' | 'right' ``` #### `NotificationVariant` @tetherto/mdk-react-devkit/core Toast/notification variants. ```tsx type NotificationVariant = 'success' | 'error' | 'warning' | 'info' ``` #### `BadgeStatus` @tetherto/mdk-react-devkit/core Badge status options. ```tsx type BadgeStatus = 'success' | 'processing' | 'error' | 'warning' | 'default' ``` #### `TypographyColor` @tetherto/mdk-react-devkit/core Typography color options including muted. ```tsx type TypographyColor = 'default' | 'primary' | 'success' | 'warning' | 'error' | 'muted' ``` ### Utility types #### `UnknownRecord` @tetherto/mdk-react-devkit/core Generic type for objects with unknown structure. ```tsx type UnknownRecord = Record ``` #### `Nullable` / `Optional` / `Maybe` @tetherto/mdk-react-devkit/core Null/undefined wrapper types. ```tsx type Nullable = T | null type Optional = T | undefined type Maybe = T | null | undefined ``` #### `Status` @tetherto/mdk-react-devkit/core Async operation status. ```tsx type Status = 'idle' | 'loading' | 'success' | 'error' ``` ### API types #### `PaginationParams` @tetherto/mdk-react-devkit/core Pagination request parameters. ```tsx type PaginationParams = { limit?: number offset?: number page?: number } ``` #### `PaginatedResponse` @tetherto/mdk-react-devkit/core Paginated response wrapper. ```tsx type PaginatedResponse = { data: T[] page: number total: number totalPages: number } ``` #### `ApiResponse` @tetherto/mdk-react-devkit/core API response wrapper. ```tsx type ApiResponse = { data: T message?: string status: number } ``` #### `ApiError` @tetherto/mdk-react-devkit/core API error response structure. ```tsx type ApiError = { error: string message: string status: number data?: { message?: string } } ``` ### Data table types @tetherto/mdk-react-devkit/core Re-exported from TanStack Table for convenience. ```tsx DataTableColumnDef, DataTableExpandedState, DataTablePaginationState, DataTableRow, DataTableRowSelectionState, DataTableSortingState, } from '@tetherto/mdk-react-devkit/core' ``` ### Value types #### `ValueUnit` @tetherto/mdk-react-devkit/core A value paired with a unit, used for display formatting. ```tsx type ValueUnit = { value: number | string | null unit: string realValue: number } ``` #### `HashrateUnit` / `CurrencyUnit` @tetherto/mdk-react-devkit/core Specialized value-unit aliases. ```tsx type HashrateUnit = ValueUnit type CurrencyUnit = ValueUnit ``` #### `UnitLabel` @tetherto/mdk-react-devkit/core SI-prefix unit labels. ```tsx type UnitLabel = 'decimal' | 'k' | 'M' | 'G' | 'T' | 'P' ``` ### Time types #### `TimeRangeFormatted` @tetherto/mdk-react-devkit/core A formatted time range. ```tsx type TimeRangeFormatted = { start: string end: string formatted: string } ``` #### `TimeInterval` @tetherto/mdk-react-devkit/core A time interval with start/end timestamps. ```tsx type TimeInterval = { start: number end: number } ``` ### Chart types #### `ChartLegendPosition` @tetherto/mdk-react-devkit/core Chart legend position options. ```tsx type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'center' | 'chartArea' ``` #### `WeightedAverageResult` @tetherto/mdk-react-devkit/core Result from weighted average calculation. ```tsx type WeightedAverageResult = { avg: number totalWeight: number weightedValue: number } ``` #### `ErrorWithTimestamp` @tetherto/mdk-react-devkit/core An error with optional timestamp. ```tsx type ErrorWithTimestamp = { msg?: string message?: string timestamp?: number | string } ``` ## Foundation types Foundation types describe the shape of devices, containers, alerts, site configuration, and settings data flowing through `@tetherto/mdk-react-devkit/foundation` components and API responses. They are organized into barrels including `alerts`, `config`, `device`, and `settings.types`. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ### Import @tetherto/mdk-react-devkit/foundation ```tsx Alert, Device, DeviceLast, DeviceInfo, ContainerSnap, ContainerStats, MinerStats, MinerConfig, SettingsUser, PermLevel, GlobalConfig, TimelineChartDataPoint, TimelineChartDataset, TimelineChartData, ChartRange, AxisTitleText, MetricsEfficiencyLogEntry, } from '@tetherto/mdk-react-devkit/foundation' ``` ### Alert types #### `Alert` @tetherto/mdk-react-devkit/foundation Raw alert record as it appears on a device's `alerts` array. ```tsx type Alert = { id?: string severity: string createdAt: number | string name: string description: string message?: string uuid?: string code?: string | number [key: string]: unknown } ``` The `severity` field uses string values like `critical`, `high`, `medium`, `low`. The open `[key: string]: unknown` index signature allows vendor-specific fields without breaking the type contract. #### `LogFormattedAlertData` @tetherto/mdk-react-devkit/foundation Alert reshaped for log display components (e.g., `AlertsLog`). ```tsx type LogFormattedAlertData = { title: string subtitle: string status: string severityLevel: number creationDate: number | string body: string id: string uuid?: string [key: string]: unknown } ``` ### Device types The `Device` family models everything that appears on the device explorer: miners, containers, power meters, temperature sensors, and cabinets. The shape is intentionally permissive (open index signatures, optional fields) because devices come from a live API that adds vendor-specific fields over time. #### `Device` @tetherto/mdk-react-devkit/foundation The root device record. Used pervasively in the [operations centre](/reference/ui/react/foundation/operations) components. ```tsx type Device = { id: string type: string tags?: string[] rack?: string last?: DeviceLast username?: string info?: DeviceInfo containerId?: string address?: string | null code?: string alerts?: Alert[] | null powerMeters?: Device[] tempSensors?: Device[] transformerTempSensor?: Device rootTempSensor?: Device [key: string]: unknown } ``` The `type` string discriminates devices by category (such as miner or container) and by vendor. The `last` field carries the latest snapshot from the device. #### `DeviceLast` @tetherto/mdk-react-devkit/foundation The latest reading wrapper that lives on `Device.last`. ```tsx type DeviceLast = { err?: string | null type?: string snap?: ContainerSnap alerts?: Alert[] | null [key: string]: unknown } ``` `err` is a connection or upstream error string when the device is unreachable. `snap` carries the actual stats and config payload. #### `DeviceInfo` @tetherto/mdk-react-devkit/foundation Identification and placement metadata that lives on `Device.info`. ```tsx type DeviceInfo = { container?: string pos?: string poolConfig?: string serialNum?: string macAddress?: string | null posHistory?: Partial [key: string]: unknown } ``` #### `PosHistoryEntry` @tetherto/mdk-react-devkit/foundation A single past placement of a miner. ```tsx type PosHistoryEntry = { container: string pos: string removedAt: number } ``` #### `DeviceData` @tetherto/mdk-react-devkit/foundation A flattened version of `Device` with a guaranteed (non-optional) `snap` field, returned by the `getDeviceData` helper. ```tsx type DeviceData = { id: string type: string tags?: string[] rack?: string snap: ContainerSnap alerts?: Alert[] username?: string info?: DeviceInfo containerId?: string address?: string err?: string [key: string]: unknown } ``` ### Container types #### `Container` @tetherto/mdk-react-devkit/foundation A `Device` specialized for containers, with container-specific `info` and `last` shapes. ```tsx type Container = { info?: Partial last?: Partial } & Device ``` #### `ContainerInfo` @tetherto/mdk-react-devkit/foundation Cooling, supply, and pressure metadata for a container. ```tsx type ContainerInfo = { container: string cooling_system: Record cdu: Record primary_supply_temp: number second_supply_temp1: number second_supply_temp2: number supply_liquid_temp: number supply_liquid_set_temp: number supply_liquid_pressure: number return_liquid_pressure: number } ``` #### `ContainerPosInfo` @tetherto/mdk-react-devkit/foundation Position descriptor for a device inside a container (PDU/socket coordinates). ```tsx type ContainerPosInfo = { containerInfo: Partial<{ container: string; type: string }> pdu: string | number socket: string | number pos: string [key: string]: unknown } ``` #### `ContainerLast` @tetherto/mdk-react-devkit/foundation Last-snapshot wrapper for a container. ```tsx type ContainerLast = { snap: { stats?: Partial } alerts: unknown[] | null err: string | null } ``` #### `ContainerSnap` @tetherto/mdk-react-devkit/foundation The `snap` payload found on `DeviceLast.snap` for both miners and containers. `stats` is what most components read. ```tsx type ContainerSnap = { stats?: Partial config?: Record } ``` #### `ContainerStats` @tetherto/mdk-react-devkit/foundation The big stats blob produced by every container snapshot. ```tsx type ContainerStats = { status: string ambient_temp_c: number humidity_percent: number power_w: number container_specific: Partial distribution_box1_power_w: number distribution_box2_power_w: number stats: Record temperature_c: Partial frequency_mhz: Partial miner_specific: Partial [key: string]: unknown } ``` `status` is one of `running`, `offline`, `stopped` (see `CONTAINER_STATUS` in [Constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants)). #### `ContainerSpecific` @tetherto/mdk-react-devkit/foundation Container-specific stats (currently the PDU array). ```tsx type ContainerSpecific = { pdu_data: Partial[] [key: string]: unknown } ``` #### `ContainerPduData` @tetherto/mdk-react-devkit/foundation Per-PDU power and status reading. ```tsx type ContainerPduData = { power_w: number status: number } ``` #### `StatsTemperatureC` @tetherto/mdk-react-devkit/foundation Temperature stats with per-chip detail. ```tsx type StatsTemperatureC = { avg: number min: number max: number chips: TempChipData[] [key: string]: unknown } ``` #### `StatsFrequencyMhz` @tetherto/mdk-react-devkit/foundation Frequency stats with per-chip detail. ```tsx type StatsFrequencyMhz = { avg: number chips: ChipData[] [key: string]: unknown } ``` #### `ChipData` / `TempChipData` @tetherto/mdk-react-devkit/foundation Per-chip readings. ```tsx type ChipData = { index: number current: number } type TempChipData = { index: number max?: number min?: number avg?: number } ``` #### `MinerSpecificStats` @tetherto/mdk-react-devkit/foundation Miner-specific stats blob. ```tsx type MinerSpecificStats = { upfreq_speed: number [key: string]: unknown } ``` ### Miner types #### `MinerStats` @tetherto/mdk-react-devkit/foundation Per-miner stats reported on each snapshot. ```tsx type MinerStats = { status?: string uptime_ms?: number power_w?: number hashrate_mhs?: MinerHashrateMhs poolHashrate?: string temperature_c?: { max?: number } } ``` #### `MinerHashrateMhs` @tetherto/mdk-react-devkit/foundation Hashrate readings, currently just the rolling 5-minute window. ```tsx type MinerHashrateMhs = { t_5m?: number } ``` #### `MinerInfo` @tetherto/mdk-react-devkit/foundation Identifying info for a miner (used by miner record cards). ```tsx type MinerInfo = { container?: string pos?: string macAddress?: string serialNum?: string } ``` #### `MinerConfig` @tetherto/mdk-react-devkit/foundation Mutable miner configuration. ```tsx type MinerConfig = { firmware_ver?: string power_mode?: string led_status?: boolean } ``` `power_mode` values come from `MINER_POWER_MODE` (`sleep`, `low`, `normal`, `high`). #### `MinerDeviceSnapshot` @tetherto/mdk-react-devkit/foundation Lightweight snapshot wrapper holding only `MinerConfig`. ```tsx type MinerDeviceSnapshot = { last?: { snap?: { config?: MinerConfig } } } ``` #### `MinerRecord` @tetherto/mdk-react-devkit/foundation Combined miner record used by list/table views. ```tsx type MinerRecord = { id?: string shortCode?: string info?: MinerInfo address?: string type?: string alerts?: unknown[] stats?: MinerStats config?: MinerConfig device?: MinerDeviceSnapshot error?: string err?: string isPoolStatsEnabled?: boolean } ``` ### Power and cabinet types #### `PowerMeter` @tetherto/mdk-react-devkit/foundation Minimal power meter reading shape. ```tsx type PowerMeter = { last?: { snap?: { stats?: { power_w?: number } } } } ``` #### `LvCabinetRecord` @tetherto/mdk-react-devkit/foundation LV cabinet record carrying its associated power meters. ```tsx type LvCabinetRecord = { id: string powerMeters?: PowerMeter[] } ``` ### Config types #### `GlobalConfig` @tetherto/mdk-react-devkit/foundation Site-wide configuration from your API or store, including nominal targets for reporting dashboards. Load this shape in your app from your API or store and pass it into foundation reporting UI as needed. ```tsx type GlobalConfig = { nominalSiteHashrate_MHS?: number nominalAvailablePowerMWh?: number nominalPowerConsumption_MW?: number nominalWeightedAvgEfficiency_WThs?: number nominalMinerCapacity?: number isAutoSleepAllowed?: boolean siteEnergyDataThresholdMWh?: number [key: string]: unknown } ``` | Field | Type | Description | |-------|------|-------------| | `nominalSiteHashrate_MHS` | `number` | Nominal site hashrate (MH/s) | | `nominalAvailablePowerMWh` | `number` | Nominal available power (MWh on the wire) | | `nominalPowerConsumption_MW` | `number` | Nominal power consumption (MW) | | `nominalWeightedAvgEfficiency_WThs` | `number` | Nominal weighted average efficiency (W/TH) | | `nominalMinerCapacity` | `number` | Nominal miner capacity | | `isAutoSleepAllowed` | `boolean` | Whether auto-sleep is permitted for the site | | `siteEnergyDataThresholdMWh` | `number` | Energy data threshold (MWh) | | `[key: string]` | `unknown` | Additional API fields without breaking the type | ### Timeline chart types Types for [`TimelineChart`](/reference/ui/react/foundation/dashboard/charts#timelinechart) in `@tetherto/mdk-react-devkit/foundation`. Each segment uses `x: [startMs, endMs]` and `y` matching a row in `labels`. #### `TimelineChartDataPoint` @tetherto/mdk-react-devkit/foundation One horizontal segment on a timeline row. ```tsx type TimelineChartDataPoint = { x: [number, number] y: string | undefined } ``` | Field | Type | Description | |-------|------|-------------| | `x` | `[number, number]` | Segment start and end (epoch ms) | | `y` | `string \| undefined` | Row label; must match an entry in `TimelineChartData.labels` | #### `TimelineChartDataset` @tetherto/mdk-react-devkit/foundation A named group of segments (legend entry). ```tsx type TimelineChartDataset = { label: string data: TimelineChartDataPoint[] borderColor?: string[] backgroundColor?: string[] color?: string } ``` #### `TimelineChartData` @tetherto/mdk-react-devkit/foundation Full payload for `initialData` and `newData`. ```tsx type TimelineChartData = { labels: string[] datasets: TimelineChartDataset[] } ``` | Field | Type | Description | |-------|------|-------------| | `labels` | `string[]` | Row names (Y axis) | | `datasets` | `TimelineChartDataset[]` | Segment groups keyed by `label` | #### `ChartRange` @tetherto/mdk-react-devkit/foundation Visible time window for the `range` prop. ```tsx type ChartRange = { min: Date | number max: Date | number } ``` #### `AxisTitleText` @tetherto/mdk-react-devkit/foundation Axis title strings for `axisTitleText`. ```tsx type AxisTitleText = { x: string y: string } ``` ### Metrics efficiency types Types for **`/auth/metrics/efficiency`**, used by the site view tab on [`OperationsEfficiency`](/reference/ui/react/foundation/reporting/operations-efficiency). #### `MetricsEfficiencyLogEntry` @tetherto/mdk-react-devkit/foundation One point on the site efficiency time series. ```tsx type MetricsEfficiencyLogEntry = { ts: number efficiencyWThs: number } ``` | Field | Type | Description | |-------|------|-------------| | `ts` | `number` | Timestamp (epoch ms) | | `efficiencyWThs` | `number` | Site efficiency (W/TH) at `ts` | #### `MetricsEfficiencySummary` @tetherto/mdk-react-devkit/foundation Summary block returned with the efficiency metrics response. ```tsx type MetricsEfficiencySummary = { avgEfficiencyWThs: number | null } ``` #### `MetricsEfficiencyResponse` @tetherto/mdk-react-devkit/foundation Wrapper for the efficiency metrics endpoint (`log` entries plus summary), using the shared `MetricsResponse` shape from `@tetherto/mdk-react-devkit/foundation`. ### Settings types #### `SettingsUser` @tetherto/mdk-react-devkit/foundation A user record as it appears in user-management lists. ```tsx type SettingsUser = { id: string name?: string email: string role: string last_login?: string lastActive?: string [key: string]: unknown } ``` #### `RoleOption` @tetherto/mdk-react-devkit/foundation Role option for select dropdowns. Also exported as the array `USER_ROLES` in [Constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants). ```tsx type RoleOption = { label: string value: string } ``` #### `PermLevel` @tetherto/mdk-react-devkit/foundation Permission level values. ```tsx type PermLevel = 'rw' | 'r' | false ``` #### `RolesPermissionsData` @tetherto/mdk-react-devkit/foundation The shape consumed by [`RBACControlSettings`](/reference/ui/react/foundation/settings/access-control). ```tsx type RolesPermissionsData = { permissions: Record> labels: Record } ``` #### `SettingsExportData` @tetherto/mdk-react-devkit/foundation The export envelope produced and consumed by [`ImportExportSettings`](/reference/ui/react/foundation/settings/import-export). Generic `TExtra` lets you attach app-specific extras. ```tsx type SettingsExportData = Record> = { headerControls?: Record featureFlags?: Record timestamp?: string version?: string } & TExtra ``` #### `ImportResult` @tetherto/mdk-react-devkit/foundation Result returned from settings import operations. ```tsx type ImportResult = { success: boolean applied?: string[] errors?: string[] message?: string } ``` # Utilities (/reference/app-toolkit/ui-devkit/utilities) This page documents helper functions exported by the MDK packages. - [Core utilities](#core-utilities) ships **15 utility modules** with functions for formatting, dates, validation, conversions, class-name merging, and more - [Foundation utilities](#foundation-utilities) currently ships a single public utility module (`settings-utils`) for parsing, validating, and exporting settings JSON - [UI Foundation alert utilities](#ui-foundation-alert-utilities) ships query-parameter builders and time-range chunking helpers for the Alerts feature ## Core utilities Helper functions exported by `@tetherto/mdk-react-devkit/core` for formatting, dates, validation, conversions, and class-name merging. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ### Import @tetherto/mdk-react-devkit/core ```tsx formatNumber, formatHashrate, formatDate, formatRelativeTime, cn, isEmpty, isValidEmail, } from '@tetherto/mdk-react-devkit/core' ``` ### Formatting utilities #### `formatNumber` @tetherto/mdk-react-devkit/core Format numbers with locale formatting and configurable options. ```tsx formatNumber(1234.567) // "1,234.57" formatNumber(null) // "-" formatNumber(1234, { minimumFractionDigits: 2 }) // "1,234.00" formatNumber(undefined, {}, 'N/A') // "N/A" ``` #### `formatHashrate` @tetherto/mdk-react-devkit/core Format hashrate values with rounding. ```tsx formatHashrate(150.456) // "150.46" formatHashrate(null) // "-" ``` #### `formatCurrency` @tetherto/mdk-react-devkit/core Format currency values. ```tsx formatCurrency(1234.56, 'USD') // "$1,234.56" formatCurrency(0.00012345, 'BTC') // "₿0.00012345" ``` #### `getPercentFormattedNumber` @tetherto/mdk-react-devkit/core Format numbers as percentages. ```tsx getPercentFormattedNumber(0.75) // "75%" getPercentFormattedNumber(0.1234, 1) // "12.3%" ``` #### `formatValueUnit` @tetherto/mdk-react-devkit/core Format value-unit objects. ```tsx formatValueUnit(150, 'TH/s') // "150 TH/s" ``` ### Date utilities #### `formatDate` @tetherto/mdk-react-devkit/core Format dates with customizable patterns. ```tsx formatDate(new Date()) // "Jan 15, 2025" formatDate(1705334400000, { format: 'yyyy-MM-dd' }) // "2025-01-15" ``` #### `formatRelativeTime` @tetherto/mdk-react-devkit/core Format dates as relative time strings. ```tsx formatRelativeTime(new Date(Date.now() - 3600000)) // "1h ago" formatRelativeTime(new Date(Date.now() - 86400000)) // "1d ago" ``` #### `formatChartDate` @tetherto/mdk-react-devkit/core Format timestamps for chart display. ```tsx formatChartDate(1705334400) // "Jan 15" formatChartDate(1705334400, true) // "Jan 15, 2025" ``` #### `isValidTimestamp` @tetherto/mdk-react-devkit/core Check if a timestamp is valid. ```tsx isValidTimestamp(1705334400000) // true isValidTimestamp('invalid') // false ``` #### `parseMonthLabelToDate` @tetherto/mdk-react-devkit/core Parse month labels to `Date` objects. ```tsx parseMonthLabelToDate('01-26') // Date(2026, 0, 1) parseMonthLabelToDate('03-2025') // Date(2025, 2, 1) ``` #### `getPastDateFromDate` @tetherto/mdk-react-devkit/core Get a date in the past. ```tsx getPastDateFromDate({ dateTs: Date.now(), days: 7 }) // 7 days ago ``` ### Validation utilities #### `isEmpty` @tetherto/mdk-react-devkit/core Check if a value is empty. ```tsx isEmpty(null) // true isEmpty('') // true isEmpty([]) // true isEmpty({}) // true isEmpty('hello') // false isEmpty([1, 2, 3]) // false ``` #### `isValidEmail` @tetherto/mdk-react-devkit/core Validate email addresses. ```tsx isValidEmail('user@example.com') // true isValidEmail('invalid') // false ``` #### `isValidUrl` @tetherto/mdk-react-devkit/core Validate URLs. ```tsx isValidUrl('https://example.com') // true isValidUrl('not-a-url') // false ``` #### `isNil` @tetherto/mdk-react-devkit/core Check if value is `null` or `undefined`. ```tsx isNil(null) // true isNil(undefined) // true isNil(0) // false isNil('') // false ``` #### `isPlainObject` @tetherto/mdk-react-devkit/core Check if value is a plain object. ```tsx isPlainObject({}) // true isPlainObject({ a: 1 }) // true isPlainObject([]) // false isPlainObject(new Date()) // false ``` ### Class name utilities #### `cn` @tetherto/mdk-react-devkit/core Merge class names using [clsx](https://github.com/lukeed/clsx) and [tailwind-merge](https://github.com/dcastil/tailwind-merge). ```tsx cn('px-4', 'py-2') // "px-4 py-2" cn('text-red', isError && 'bg-red') // conditional classes cn('p-4', { 'hidden': !visible }) // object syntax ``` ### Conversion utilities #### `toMW` / `toMWh` @tetherto/mdk-react-devkit/core Convert watts to megawatts. ```tsx toMW(1000000) // 1 toMWh(1000000) // 1 ``` #### `toPHS` @tetherto/mdk-react-devkit/core Convert raw hashrate to `PH/s`. ```tsx toPHS(1000000000000000) // 1 ``` #### `convertMpaToBar` @tetherto/mdk-react-devkit/core Convert pressure units. ```tsx convertMpaToBar(0.1) // 1 ``` #### `unitToKilo` @tetherto/mdk-react-devkit/core Convert to kilo units. ```tsx unitToKilo(1000) // 1 ``` ### Number utilities #### `percentage` @tetherto/mdk-react-devkit/core Calculate percentage. ```tsx percentage(25, 100) // 25 percentage(1, 4) // 25 ``` #### `getPercentChange` @tetherto/mdk-react-devkit/core Calculate percentage change. ```tsx getPercentChange(110, 100) // 10 getPercentChange(90, 100) // -10 ``` #### `convertUnits` @tetherto/mdk-react-devkit/core Convert between SI-prefix units. ```tsx convertUnits(1, 'k', 'M') // 0.001 convertUnits(1000, 'decimal', 'k') // 1 ``` #### `safeNumber` @tetherto/mdk-react-devkit/core Safely convert to number. ```tsx safeNumber('123') // 123 safeNumber('invalid') // 0 safeNumber(null) // 0 ``` ### String utilities #### `toTitleCase` @tetherto/mdk-react-devkit/core Convert string to Title Case. ```tsx toTitleCase('hello world') // "Hello World" ``` #### `formatMacAddress` @tetherto/mdk-react-devkit/core Format MAC addresses. ```tsx formatMacAddress('aa:bb:cc:dd:ee:ff') // "AA:BB:CC:DD:EE:FF" ``` #### `safeString` @tetherto/mdk-react-devkit/core Safely convert to string. ```tsx safeString(123) // "123" safeString(null) // "" ``` ### Time utilities #### `secondsToMs` @tetherto/mdk-react-devkit/core Convert seconds to milliseconds. ```tsx secondsToMs(60) // 60000 ``` #### `breakTimeIntoIntervals` @tetherto/mdk-react-devkit/core Split `[start, end]` into consecutive windows of `intervalMs`. Re-exported from `@tetherto/mdk-ui-foundation`. ```tsx breakTimeIntoIntervals(start, end, 3_600_000) // Array of 1-hour { start, end } windows ``` #### `timeRangeWalker` @tetherto/mdk-react-devkit/core Generator for iterating through time ranges. ```tsx for (const interval of timeRangeWalker(start, end, duration)) { // Process each interval } ``` ### Color utilities #### `hexToRgba` @tetherto/mdk-react-devkit/core Convert hex color to rgba. ```tsx hexToRgba('#72F59E', 0.5) // "rgba(114, 245, 158, 0.5)" ``` ### Array utilities #### `getNestedValue` @tetherto/mdk-react-devkit/core Get nested value by dot-path. ```tsx getNestedValue({ a: { b: 1 } }, 'a.b') // 1 ``` #### `getWeightedAverage` @tetherto/mdk-react-devkit/core Calculate weighted average. ```tsx getWeightedAverage(items, 'value', 'weight') ``` #### `circularArrayAccess` @tetherto/mdk-react-devkit/core Create infinite cycling generator. ```tsx const colors = circularArrayAccess(['red', 'green', 'blue']) colors.next().value // 'red' colors.next().value // 'green' colors.next().value // 'blue' colors.next().value // 'red' (cycles) ``` ## Foundation utilities Helpers exported by `@tetherto/mdk-react-devkit/foundation` for filtering, formatting, validating, parsing, and exporting settings data. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ### Import @tetherto/mdk-react-devkit/foundation ```tsx filterUsers, formatRoleLabel, formatLastActive, validateSettingsJson, parseSettingsFile, exportSettingsToFile, } from '@tetherto/mdk-react-devkit/foundation' ``` ### Settings utilities #### `filterUsers` @tetherto/mdk-react-devkit/foundation Filter a `SettingsUser[]` list by email substring (case-insensitive) and exact role match. Used by the user-management table search. ```tsx filterUsers({ users, email: 'alice', // partial, case-insensitive match on user.email role: 'admin', // exact match on user.role; pass null to skip }) ``` | Parameter | Type | Description | |-----------|------|-------------| | `users` | `SettingsUser[]` | Source list | | `email` | `string \| null \| undefined` | Substring filter on `email` (case-insensitive). Skipped when falsy. | | `role` | `string \| null \| undefined` | Exact role match. Skipped when falsy. | #### `formatRoleLabel` @tetherto/mdk-react-devkit/foundation Convert a snake case role identifier to a human-readable Title Case label. ```tsx formatRoleLabel('site_manager') // "Site Manager" formatRoleLabel('reporting_tool_manager') // "Reporting Tool Manager" formatRoleLabel('admin') // "Admin" ``` #### `formatLastActive` @tetherto/mdk-react-devkit/foundation Format a timestamp string as `MM/DD/YYYY - HH:MM`. Returns `'-'` when the input is missing or invalid. ```tsx formatLastActive('2025-01-15T14:30:00Z') // "01/15/2025 - 14:30" formatLastActive(undefined) // "-" formatLastActive('not-a-date') // "-" ``` #### `validateSettingsJson` @tetherto/mdk-react-devkit/foundation Type-guard that checks whether an unknown value is a valid `SettingsExportData`. Returns `true` if the value is an object that contains at least one of `headerControls`, `featureFlags`, or `timestamp`. ```tsx if (validateSettingsJson(parsed)) { // parsed is now narrowed to SettingsExportData } ``` #### `parseSettingsFile` @tetherto/mdk-react-devkit/foundation Read a `File` containing settings JSON, validate it, and resolve to `SettingsExportData`. Rejects on invalid JSON, an invalid format, or a file read error. ```tsx try { const settings = await parseSettingsFile(file) applySettings(settings) } catch (err) { notifyError('Could not import settings', err.message) } ``` | Throws | Reason | |--------|--------| | `` `Invalid settings file format. Please ensure the file is a valid ${WEBAPP_NAME} settings export.` `` | The JSON parsed but didn't match the `SettingsExportData` shape. The literal interpolates [`WEBAPP_NAME`](/reference/app-toolkit/ui-devkit/constants#webapp_name). | | `Failed to parse JSON file. Please ensure the file is valid JSON.` | The file contents weren't valid JSON. | | `Failed to read file.` | The browser couldn't read the file. | #### `exportSettingsToFile` @tetherto/mdk-react-devkit/foundation Serialize `SettingsExportData` to JSON, package it as a downloadable Blob, and trigger a browser download. Returns the generated filename (e.g., `mdk-settings-2025-01-15T14-30-00-000Z.json`). The filename prefix is fixed in the foundation kit and does not interpolate [`WEBAPP_NAME`](/reference/app-toolkit/ui-devkit/constants#webapp_name). ```tsx const filename = exportSettingsToFile({ headerControls: { poolMiners: true, consumption: false }, featureFlags: { betaCharts: true }, timestamp: new Date().toISOString(), version: '1.0.0', }) ``` ## UI Foundation alert utilities `@tetherto/mdk-ui-foundation` ships two utility modules for the Alerts feature: query-parameter builders (`alert-queries`) and time-range chunking helpers (`historical-log-chunks`). These are the source consumed directly by the `useCurrentAlertDevices` and `useHistoricalAlerts` adapter hooks. ### Prerequisites - Complete the [@tetherto/mdk-ui-foundation installation](/reference/app-toolkit/ui-foundation) ### Import @tetherto/mdk-ui-foundation ```tsx ONE_DAY_MS, DEFAULT_HISTORICAL_WINDOW_MS, getDefaultHistoricalAlertsRange, buildCurrentAlertDevicesParams, buildHistoricalAlertsParams, breakTimeIntoIntervals, mergeAlertsByUuid, fetchHistoricalAlertsInChunks, } from '@tetherto/mdk-ui-foundation' ``` ### Alert query builders #### `ONE_DAY_MS` @tetherto/mdk-ui-foundation One day in milliseconds (`86_400_000`). The fetch-window size used by the historical-alerts data path. ```tsx ONE_DAY_MS // 86400000 ``` #### `DEFAULT_HISTORICAL_WINDOW_MS` @tetherto/mdk-ui-foundation Default historical-alerts look-back window — 14 days (`14 * ONE_DAY_MS`). Matches the devkit [``](/reference/ui/react/foundation/alerts) feature default; wider ranges fan out into more 24-hour requests. ```tsx DEFAULT_HISTORICAL_WINDOW_MS // 1209600000 (14 days in ms) ``` #### `getDefaultHistoricalAlertsRange` @tetherto/mdk-ui-foundation Returns the default historical-alerts range: the last `DEFAULT_HISTORICAL_WINDOW_MS` ending now. Used by the devkit [``](/reference/ui/react/foundation/alerts) feature and the shell Alerts page to seed their range state. Pass `now` to fix the upper bound in tests. ```tsx const range = getDefaultHistoricalAlertsRange() // { start: <14 days ago>, end: } // Injectable for tests getDefaultHistoricalAlertsRange(1_700_000_000_000) // { start: 1_700_000_000_000 - DEFAULT_HISTORICAL_WINDOW_MS, end: 1_700_000_000_000 } ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `now` | Optional | `number` | `Date.now()` | Upper bound of the window (ms epoch). | #### `buildCurrentAlertDevicesParams` @tetherto/mdk-ui-foundation Builds the `list-things` query params for the current-alerts table: every device that currently carries one or more alerts, with a 1 000 device limit. Consumed by `useCurrentAlertDevices`. `filterTags` widen the server-side selector so the fetch narrows with the active search chips (`ip-`, `sn-`, `mac-`, `firmware-`) instead of relying on client-side filtering alone. ```tsx // All devices with active alerts const params = buildCurrentAlertDevicesParams() // Narrowed to devices matching the active search chips const filtered = buildCurrentAlertDevicesParams(['ip-192.168.1.1', 'sn-ABC123']) ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `filterTags` | Optional | `string[]` | `[]` | Active alert search chips to narrow the selector server-side. | #### `buildHistoricalAlertsParams` @tetherto/mdk-ui-foundation Builds the `history-log` query params for a single alerts window (`logType: 'alerts'`). Called once per 24-hour sub-window by the chunked fetch. ```tsx const params = buildHistoricalAlertsParams({ start: range.start, end: range.end }) // { logType: 'alerts', start: ..., end: ... } ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `range` | Required | `HistoricalAlertsRange` | none | `{ start: number; end: number }` — ms epoch bounds for the window. | ### Historical alert chunking #### `breakTimeIntoIntervals` @tetherto/mdk-ui-foundation Splits `[start, end]` into consecutive windows of `intervalMs` (default `ONE_DAY_MS`); the final window is clamped to `end`. Returns an empty array for an empty or inverted range. ```tsx // 24-hour windows (default) const windows = breakTimeIntoIntervals(start, end) // Custom window size const hourly = breakTimeIntoIntervals(start, end, 3_600_000) ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `start` | Required | `number` | none | Range start (ms epoch). | | `end` | Required | `number` | none | Range end (ms epoch). | | `intervalMs` | Optional | `number` | `ONE_DAY_MS` | Window size in ms. | Returns `TimeInterval[]` where each element is `{ start: number; end: number }`. #### `mergeAlertsByUuid` @tetherto/mdk-ui-foundation Concatenates `next` onto `prev`, replacing any row that shares a `uuid` (later windows win) and appending the rest. Rows without a `uuid` are always appended. ```tsx const merged = mergeAlertsByUuid(previousAlerts, newAlerts) ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `prev` | Required | `T[]` | none | Existing alert rows. | | `next` | Required | `T[]` | none | Rows from the latest window fetch. | Returns `T[]` where `T extends { uuid?: string }`. #### `fetchHistoricalAlertsInChunks` @tetherto/mdk-ui-foundation Fetches a historical-alerts range as successive 24-hour windows (oldest to newest), merging results by `uuid`. Individual window failures are swallowed so one bad request does not drop the whole range. The loop bails out early when `options.signal` is aborted. ```tsx fetchHistoricalAlertsInChunks, buildHistoricalAlertsParams, } from '@tetherto/mdk-ui-foundation' const alerts = await fetchHistoricalAlertsInChunks( { start: range.start, end: range.end }, async (window) => { const result = await myApi.historyLog(buildHistoricalAlertsParams(window)) return result.data }, { signal: abortController.signal }, ) ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `range` | Required | `{ start: number; end: number }` | none | Full date range to paginate over (ms epoch). | | `fetchWindow` | Required | `function` | none | Called once per 24-hour window, oldest first. Receives a `TimeInterval` and returns `Promise`. | | `options.intervalMs` | Optional | `number` | `ONE_DAY_MS` | Window size in ms. | | `options.signal` | Optional | `AbortSignal` | none | Checked between windows — aborts the loop early on range changes. | # UI Foundation (/reference/app-toolkit/ui-foundation) @tetherto/mdk-ui-foundation If you are building a React app with the MDK kit, start with the [React adapter](/tutorials/ui/react) instead. `` and adapter hooks such as `useAuth` and `useDevices` wrap this package so most React code never imports `@tetherto/mdk-ui-foundation` directly. Use this reference when you need headless store access outside React (logging, websocket setup, test helpers) or when authoring a future framework adapter. `@tetherto/mdk-ui-foundation` is the framework-agnostic headless layer of the [MDK App Toolkit](/concepts/stack/app-toolkit). It ships Zustand vanilla stores and a TanStack Query Core `QueryClient` factory. There are **no React imports** in this package. ## Subpath exports | Subpath | Purpose | |---------|---------| | `.` | Top-level barrel | | `./store` | Zustand vanilla stores | | `./query` | `QueryClient` factory, query keys, and query/mutation factories | | `./types` | Shared type contracts | | `./stores.json` | Machine-readable store manifest (generated at build time) | ## Stores Each store is a Zustand vanilla singleton. In a React app, read and update state through the matching adapter hook instead of importing stores directly. | Store | Summary | Adapter hook | |-------|---------|--------------| | `authStore` | Session token and permission payload | [`useAuth`](/reference/app-toolkit/hooks/state#useauth) | | `devicesStore` | Fleet device list and current selection | [`useDevices`](/reference/app-toolkit/hooks/state#usedevices) | | `timezoneStore` | Active operator timezone | [`useTimezone`](/reference/app-toolkit/hooks/state#usetimezone) | | `notificationStore` | Unread notification counter (`count`, `increment`, `decrement`, `reset`) | [`useNotifications`](/reference/app-toolkit/hooks/state#usenotifications) | | `actionsStore` | Pending device and pool action submissions | [`useActions`](/reference/app-toolkit/hooks/state#useactions) | Import from `@tetherto/mdk-ui-foundation/store` (or the top-level barrel). ## QueryClient factory `createMdkQueryClient` builds a TanStack Query Core client with environment-aware Gateway base URL resolution: 1. Explicit override (typically from ``) 2. Build-time env: `VITE_MDK_API_URL` (Vite) or `MDK_API_URL` (Node) 3. Default: `http://localhost:3000` The `./query` subpath also exports query key helpers and factories (`authQuery`, `devicesQuery`, `deviceQuery`, `telemetryQuery`). See [TanStack Query](https://tanstack.com/query/latest) for general usage. ## Headless read outside React Utility code can subscribe to a store without React: ```ts const token = authStore.getState().token const unsubscribe = authStore.subscribe((state) => { console.log('token changed', state.token) }) // later: unsubscribe() ``` `` wires these singleton stores into React and creates the shared `QueryClient` for adapter hooks. ## What's not here yet Throttled telemetry subscriptions, stale detection, and history ring buffers are not yet present. They will be added alongside the consuming code that requires them. ## Next steps - [React get started](/tutorials/ui/react): three-package install and `` - [Wire a React app](/tutorials/ui/react/tutorial): full adapter wiring walkthrough - [MDK App Toolkit](/concepts/stack/app-toolkit): where UI Foundation fits in the frontend stack # Glossary (/reference/glossary) This page provides explanations for terms that new users may not be familiar with. - [Stack](#stack-and-hardware-terms) - [HRPC](#hyperswarm-rpc) ## Stack and hardware terms This section explains the terms you need to familiarize yourself with, using an Antminer rack as an example. | Term | What it is | Lives at | | --- | --- | --- | | **Kernel** (Orchestration Kernel) | The pull-only kernel that owns the device registry, routes commands, and aggregates telemetry. | [`backend/core/kernel/index.js`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/index.js) | | **Gateway** | The developer-owned entry point between non-Node clients (UI, AI agents) and Kernel. Mandatory whenever a non-Node consumer reaches the kernel; not used in the in-process Antminer-rack example below. | [`backend/core/gateway/`](https://github.com/tetherto/mdk/blob/main/backend/core/gateway/worker.js) | | **Worker** | A device-family translator. Speaks the MDK Protocol upward to Kernel and the vendor's native API downward to one device family (one miner brand, one container type, one pool API). | [`backend/workers/docs/install-pattern.md`](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md) | | **Manager class** | The JavaScript class a Worker exports, one per supported device model. Instances drive a single rack of devices. | e.g. `AM_S19XP`, `AM_S21` in [`backend/workers/miners/antminer/index.js`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/index.js) | | **Thing** | One registered device instance. Created by calling `manager.registerThing({ info, opts })`. Identified by a generated `deviceId`. | runtime, in `manager.mem.things` | ### How they compose, for an Antminer rack ```mermaid flowchart TB subgraph clientLayer ["Your code"] Client["your script (e.g., client.js)"] end subgraph kernel ["Kernel"] Kernel["Kernel
device registry · command routing · telemetry pull"] end subgraph workerLayer ["Antminer Worker"] AntminerWorker["e.g., AM_S21PRO"] end subgraph devices ["Antminer devices (real or mock)"] Miners["Antminers (HTTP / digest auth)"] end Client -->|"HRPC"| Kernel Kernel -->|"HRPC"| AntminerWorker AntminerWorker --> Miners ``` The same shape repeats for every other device family (Whatsminer, container vendors, pool APIs). For a multi-Worker view, parallel Workers, and multi-site deployments, see [`architecture.md#scaling`](/concepts/architecture#scaling). ## Hyperswarm RPC MDK uses [`@hyperswarm/rpc`](https://github.com/holepunchto/rpc) as its runtime transport. Hyperswarm RPC (HRPC) is not an HTTP-based RPC system. It is an RPC layer that rides on Hyperswarm peer-to-peer connectivity. The library is a simple RPC over the Hyperswarm DHT, backed by `Protomux`. Think of it as a peer-to-peer remote function call system built on a DHT and an encrypted connection layer. **Mental model** — Hyperswarm finds peers and establishes connections; `Protomux` divides the connection into named channels; RPC defines the conversation — a caller names a method and receives a reply. A useful analogy is a phone call between peers — Hyperswarm helps the phones find each other and connect; `Protomux` splits the line into channels; RPC defines how one side asks for a method and the other side responds. **Practical implications:** - You work with services, methods, requests, and responses — not URLs and routes - The RPC-shaped API is identical across same-process, same-host, and distributed deployments; only the discovery mechanism changes (same-process registration, shared directory, or DHT topic) - Peers discover and communicate without a central HTTP server ### HRPC on the same host MDK uses HRPC as the single transport across all deployment shapes — same-process, same-host, and distributed. Every component is addressed by its public key, not by a socket path or hostname. The Gateway, a standalone Node.js script, and a remote service all connect the same way: ```js createMdkClient({ hrpc: { key } }) ``` The Noise handshake that HRPC performs on every connection authenticates by key, so Kernel's allowlist works identically whether the caller is on the same machine or a remote host. This is consistent with the broader Holepunch ecosystem philosophy — everything is a peer addressed by public key. When the peer is on the same machine it routes locally over the local network interface; the application code sees no difference. ## Next steps - You are ready to run the example in [Run the stack](/tutorials/backend-stack/run) - Learn more about: - Multi-process discovery across machines: [Worker discovery](/concepts/stack/workers) - Gateway implementation details (HTTP routing, JWT auth, RBAC) — see [`backend/core/gateway/worker.js`](https://github.com/tetherto/mdk/blob/main/backend/core/gateway/worker.js) - Building your own Worker for a new device family: see [`backend/workers/docs/install-pattern.md`](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md) - Per-device contract details (telemetry units, command shapes, error codes): those live in each Worker's `mdk-contract.json`, e.g. [`backend/workers/miners/antminer/mdk-contract.json`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/plugin/mdk-contract.json) # Kernel reference (/reference/kernel) `@tetherto/mdk-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 these modules fit together, see [Kernel](/concepts/stack/kernel). ## What's documented - **[Modules](/reference/kernel/modules)**: per-module responsibility, interfaces, state machines, transition rules, crash-recovery procedures, and scaling characteristics. # Kernel modules (/reference/kernel/modules) `@tetherto/mdk-kernel`'s coordination splits across single-purpose modules. Each owns its own state machine, persistence boundary, and scaling characteristics. Six modules ship in v0.0.1; two more (Fault Supervisor, Concurrency Manager) are deferred to a later release. For the architectural overview that explains how these modules connect, see [Kernel](/concepts/stack/kernel). This page is the per-module spec. ## How to read this page Each accordion below covers one module: - **Responsibility**: what the module owns and the example commands or events it handles. - **Interfaces**: input and output channels, plus the public function names callers depend on. - **State machine**: the canonical diagram for the module's internal lifecycle. - **Crash recovery**: behavior on a fresh start, including how state is reconstructed. - **Scalability**: where the module can be extracted, sharded, or replicated. ## Modules **Responsibility**: validates incoming commands against the generic MDK schema, checks permissions, and resolves the correct Worker based on the `deviceId`. *Example*: when a Gateway sends a `reboot` command for `wm001`, the Dispatcher verifies that `wm001` exists, that `reboot` is a valid capability for it, then passes the request to the State Machine. **Interfaces**: - *Input*: receives generic commands via Holepunch RPC (HRPC) and the MDK Protocol from the Gateway or MCP Handler. - *Output*: hands off validated commands to the Command State Machine. - *Functions*: `dispatchCommand(deviceId, action, payload)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Validating Validating --> RoutingAction : Valid Validating --> Rejected : Invalid RoutingAction --> Enqueued Enqueued --> [*] ``` **Crash recovery**: none needed. In-flight requests fail and must be retried by the client. **Scalability**: extracted easily; can run independently to offload validation. **Responsibility**: tracks the execution lifecycle of every single command in the system. Receives execution results directly via the synchronous HRPC response. If the connection drops or a response is delayed, it relies on the Scheduler to fetch the latest status via `state.pull` so commands cannot hang. *Example*: once the `reboot` command is dispatched it transitions to `EXECUTING`. If the HRPC response returns OK it transitions to `SUCCESS`. If the response hangs, the next `state.pull` fetches the true status from the Worker. **Interfaces**: - *Input*: receives validated commands from the Dispatcher; status updates from HRPC responses or Scheduler ticks. - *Output*: invokes the Worker HRPC execution layer; emits terminal state results to the caller. - *Functions*: `enqueue(command)`, `syncState(commandId)`, `cancel(commandId)` **State machine**: ```mermaid stateDiagram-v2 [*] --> QUEUED QUEUED --> DISPATCHED DISPATCHED --> EXECUTING : HRPC sent EXECUTING --> SUCCESS : state.pull (response) EXECUTING --> FAILED : state.pull (error) EXECUTING --> TIMEOUT TIMEOUT --> QUEUED : Retry allowed TIMEOUT --> FAILED : Max retries SUCCESS --> [*] FAILED --> [*] ``` **Crash recovery**: on startup, performs a recovery sweep of pending commands. `DISPATCHED` and `EXECUTING` commands are forced to `TIMEOUT` (and re-queued if retries are available); `QUEUED` commands are left untouched. **Scalability**: requires state sharding (for example, by device or rack). **Responsibility**: the phonebook for the entire `@tetherto/mdk-kernel` ecosystem. Maps which physical device IDs belong to which connected Worker channels and stores their declared capabilities. *Example*: a `whatsminer-worker` connects and declares it manages `wm001` and `wm002`. The Registry saves this topology so the Dispatcher knows exactly where to route a command for `wm001`. **Interfaces**: - *Input*: `identity.register` requests from Workers. - *Output*: internal events triggering full state lifecycle binding. - *Functions*: `resolveWorkerState(target)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Unregistered Unregistered --> Discovered : DHT peer detected Discovered --> IdentitySaved : identity pulled IdentitySaved --> Ready : capabilities pulled Ready --> Terminated : eviction Terminated --> [*] ``` **Crash recovery**: rebuilt from state, which serves as a baseline to detect Workers that were registered but failed to reconnect. **Scalability**: read-heavy by nature; can be extracted into a read-replica architecture or partitioned by region or rack. **Responsibility**: a lightweight proxy and routing layer between the upper system (UI / AI) and the downstream Workers. Rather than `@tetherto/mdk-kernel` performing heavy time-series aggregations, the *Worker* is responsible for storing and aggregating data for the specific devices it controls. The Collector simply provides an interface to query this data and proxies the response up to the UI (via Gateway) or the AI Agent. **Worker data handling (telemetry context)**: - *Compaction*: the Worker handles compaction of metrics over large time frames. - *Local storage*: Workers should save telemetry data in a local Hyper DB. - *As-requested serving*: the Worker serves data strictly when `@tetherto/mdk-kernel` asks for it, precisely as dictated by the telemetry schemas in `mdk-contract.json`. - *Internal scheduling*: to achieve this without blocking `@tetherto/mdk-kernel`, the Worker may run its own internal scheduler for device polling. **Interfaces**: - *Input*: client or AI telemetry queries (for example, "fetch metrics for device wm001"). - *Output*: normalized telemetry payloads passed straight through from the Worker to the requesting layer. - *Functions*: `proxyTelemetryFetch(deviceId, queryArgs)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Idle Idle --> Proxying : Request received Proxying --> RoutingToClient : Worker returns data Proxying --> Timeout : Worker unresponsive RoutingToClient --> Idle ``` **Scalability**: because the heavy lifting of data storage and aggregation is pushed down into the isolated Worker processes, the Collector remains stateless and highly scalable as a pure asynchronous router. **Responsibility**: the system metronome. Triggers repetitive tasks without holding any domain-specific logic itself. *Example*: emits an internal `tick` event every 5 seconds that the Health Monitor listens to, prompting it to ping all Workers. **Interfaces**: - *Input*: system clock and configured task intervals. - *Output*: injects intents (for example, `telemetry.pull`, `health.ping`) into the Dispatcher or Collector. - *Functions*: `addJob(interval, intent)`, `removeJob(jobId)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Waiting Waiting --> Triggered : Interval elapsed Triggered --> Waiting ``` **Crash recovery**: timers re-initialize from zero on startup. Tasks are strictly idempotent. **Scalability**: scales trivially. Requires basic distributed locking to avoid duplicate ticks in multi-process `@tetherto/mdk-kernel` deployments. **Responsibility**: continuously evaluates the liveness and readiness of every registered Worker to prevent routing messages to dead nodes. *Example*: if `health.ping` to a Worker fails three times in a row, the Health Monitor marks the Worker's status as `SICK` and tells the Registry to halt routing new commands there. **Interfaces**: - *Input*: executes `health.ping` sequentially based on Scheduler ticks. - *Output*: pushes status updates to the Registry. - *Functions*: `pingWorker(workerId)`, `getHealth(workerId)` **State machine**: ```mermaid stateDiagram-v2 [*] --> UNKNOWN UNKNOWN --> HEALTHY : Ping success HEALTHY --> SICK : Ping failed (1) SICK --> DEAD : Ping failed (threshold) SICK --> HEALTHY : Ping success DEAD --> HEALTHY : Reconnected ``` **Crash recovery**: blank slate on startup; re-evaluates all known Workers immediately via ping. **Scalability**: operates locally per `@tetherto/mdk-kernel` kernel, or via independent lightweight ping agents. **Idea**: implements circuit-breaker patterns to protect the overall system from cascading failures caused by bad hardware or software bugs (for example, rejecting commands during a cooling period after repeated errors). **Status**: deferred for the first cut to keep the core orchestrator simple. If the use case arises (such as complex retry backoffs or cluster destabilization), it will be reintroduced. **Idea**: provides guaranteed lock management and queue limits to ensure mutually exclusive commands do not overlap on physical devices. **Status**: deferred for the first cut. The system relies solely on the basic command queue. If explicit global locks or backpressure limits become necessary, this module will be built out. # Protocol reference (/reference/protocol) The MDK Protocol is the contract that crosses every layer of the stack: Workers, `@tetherto/mdk-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#the-mdk-protocol). ## What's documented - **[Messages](/reference/protocol/messages)**: envelope schema, request/response examples, the full action catalogue, and the base command set. # Protocol messages (/reference/protocol/messages) Every MDK Protocol message uses the same envelope regardless of which layers are talking. This page is the canonical spec for that envelope, the full set of protocol actions, and the base command set every Worker must support. For the architectural narrative explaining when each action fires, see [Architecture](/concepts/architecture#the-mdk-protocol). ## Envelope ```json { "id": "uuid-v4", "version": "0.1.0", "type": "request | response | event", "action": "", "sender": "", "target": " | null", "deviceId": "string | null", "timestamp": 1711640000000, "payload": {} } ``` External consumers (UI or AI agents) only provide `deviceId`; the `target` Worker identity is internally resolved by `@tetherto/mdk-kernel`. A concrete request and response pair, end to end: ```json // request: Gateway asks @tetherto/mdk-kernel to reboot device wm001 { "id": "8d1c-e3a4", "version": "0.1.0", "type": "request", "action": "command.request", "sender": "appNode:fleet-api:1", "target": null, "deviceId": "wm001", "timestamp": 1711640000000, "payload": { "command": "reboot" } } // response: @tetherto/mdk-kernel relays the worker's terminal result { "id": "1f9b-77c2", "version": "0.1.0", "type": "response", "action": "command.result", "sender": "ork:kernel:tx-1", "target": "appNode:fleet-api:1", "deviceId": "wm001", "timestamp": 1711640002145, "payload": { "status": "SUCCESS", "elapsedMs": 2145 } } ``` ## Actions | Action | Type | Direction | Purpose | |---|---|---|---| | *(DHT presence)* | passive | Worker to DHT topic | Worker joins a known Hyperswarm topic; `@tetherto/mdk-kernel` detects its peer connection automatically | | `identity.request` | request | `@tetherto/mdk-kernel` to Worker | Requests the Worker's identity and managed devices | | `capability.request` | request | `@tetherto/mdk-kernel` to Worker | Asks the Worker to declare its full capability schema | | `state.pull` | request | `@tetherto/mdk-kernel` to Worker | Worker returns a snapshot of state-machine status (low cadence tick, e.g., 60s) | | `telemetry.pull` | request | `@tetherto/mdk-kernel` to Worker | Worker returns device metrics plus history (medium cadence tick, e.g., 10s) | | `command.request` | request | `@tetherto/mdk-kernel` to Worker | Resolves the Worker by `deviceId` and dispatches the command for execution | | `health.ping` | request | `@tetherto/mdk-kernel` to Worker | Liveness probe (high cadence tick, e.g., 5s) | ## Base command set The protocol standardizes a Base Command Set supported by every Worker: - `getConfig`: retrieve current device configuration - `setConfig`: update device configuration parameters - `health`: fetch detailed diagnostic health status from the device # Supported hardware (/reference/supported-hardware) ## Overview MDK integrates field hardware through Workers. Each Worker declares what it supports in its `mdk-contract.json`, and that contract is the single source of truth for coverage. Use this page to discover what Workers are supported. ## What MDK supports - **Miners**: For example, Bitmain Antminer, MicroBT Whatsminer - **Containers**: For example, Bitmain Antspace, Bitdeer - **Power meters**: For example, ABB, Satec - **Sensors**: For example, Seneca - **Mining pools**: Protocol integrations such as Ocean, F2Pool For the exact model lists, Worker packages, and per-Worker docs, see the generated catalogue: - [Full supported-hardware catalogue](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/supported-hardware.md) — generated from every `backend/workers/**/mdk-contract.json` ## Next steps - New to the moving parts? Read [terminology](/reference/glossary) (Kernel, Worker, manager, thing, mock) - Decide how to run the Worker service — [Deployment topologies](/concepts/deployment-topologies) - Run a miner Worker — [Run a miner Worker](/guides/miners) # UI 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 | 113 hooks | | [Types](/reference/ui/types) | TypeScript type definitions | 774 types | | [Utilities](/reference/ui/utilities) | Helper functions and formatters | 149 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 ``` ## Getting Started 1. [Install the packages](/quickstart/wire-react) 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](/quickstart/wire-react) - 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 Components (/reference/ui/components/actions) Components for triggering actions and user interactions. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `ActionButton` [**`ActionButton`**](/reference/ui/components/actions/#actionbutton) component with confirmation popover or dialog `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `loading` | `boolean \| undefined` | | - | - | | `disabled` | `boolean \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | | `variant` | `TActionButtonVariant \| undefined` | | - | - | | `confirmation` | `ActionButtonConfirmation` | ✓ | - | - | | `mode` | `"dialog" \| "popover" \| undefined` | | - | Confirmation mode: popover (inline) or dialog (modal). Default: popover | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `loading` | `boolean` | | - | Show a spinner instead of the content and disable the button. | | `fullWidth` | `boolean` | | - | Make the button stretch to fill its container. | | `icon` | `React.ReactNode` | | - | Icon node rendered alongside `children`. | | `variant` | `ButtonVariant` | | - | Visual variant (e.g. `primary`, `secondary`, `ghost`). | | `contentClassName` | `string` | | - | Class names applied to the inner content wrapper. | | `iconPosition` | `ButtonIconPosition` | | - | Icon placement relative to children. | | `size` | `ComponentSize` | | - | Size token (`sm`, `md`, `lg`). | ### `StatsExport` Dropdown button that triggers asynchronous CSV or JSON export. Shows a spinner while the corresponding handler is awaited. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `showLabel` | `boolean \| undefined` | | - | - | | `disabled` | `boolean \| undefined` | | - | - | | `onCsvExport` | `() => Promise` | ✓ | - | - | | `onJsonExport` | `() => Promise` | ✓ | - | - | # Auth Components (/reference/ui/components/auth) Components for authentication flows and user sign-in. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `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 `<Navigate to… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `children` | `React.ReactNode` | ✓ | - | Rendered when a token is present. | | `fallback` | `React.ReactNode` | ✓ | - | Rendered when no token is present — typically `<Navigate to="/signin" />`. | | `rememberPath` | `boolean \| undefined` | | - | When true (default), the current location is persisted to sessionStorage before rendering the fallback so the sign-in f… | ### `SignInGoogleButton` One-click Google OAuth sign-in trigger. Defaults to a full-page redirect to `../../../../_snippets/current/generated/react-devkit/components/auth.mdx#123;oauthBaseUrl}/oauth/google`, mirroring the production MOS flow. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | ✓ | - | Icon node rendered alongside `children`. | | `loading` | `boolean \| undefined` | ✓ | - | Show a spinner instead of the content and disable the button. | | `variant` | `ButtonVariant \| undefined` | ✓ | - | Visual variant (e.g. `primary`, `secondary`, `ghost`). | | `size` | `ComponentSize \| undefined` | ✓ | - | Size token (`sm`, `md`, `lg`). | | `fullWidth` | `boolean \| undefined` | ✓ | - | Make the button stretch to fill its container. | | `contentClassName` | `string \| undefined` | ✓ | - | Class names applied to the inner content wrapper. | | `iconPosition` | `ButtonIconPosition \| undefined` | ✓ | - | Icon placement relative to children. | | `oauthBaseUrl` | `string` | ✓ | - | Base URL of the OAuth backend (no trailing slash). Click navigates to `../../../../_snippets/current/generated/react-devkit/components/auth.mdx#123;oauthBaseUrl}/oauth/google`. | | `label` | `string \| undefined` | | - | Override the visible button label. | | `onClick` | `(() => void) \| undefined` | | - | Override the click behaviour entirely. When set, `oauthBaseUrl` is ignored. | # Branding Components (/reference/ui/components/branding) Components for brand identity and visual consistency. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `MdkWordmark` MDK wordmark — the canonical brand lockup, rendered as inline SVG so it tints to `currentColor`. Use this in `<[**`AppHeader`**](/reference/ui/components/navigation/#appheader)>` (via the `logo` slot) or anywhere else the brand should appear. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `size` | `MdkWordmarkSize \| undefined` | | - | Visual size of the wordmark. `sm` ≈ 24px tall, `md` ≈ 32px, `lg` ≈ 64px. | | `className` | `string \| undefined` | | - | Optional class hook on the outer `<svg>`. | | `title` | `string \| undefined` | | - | Accessible label. Defaults to "MDK". | # Card Components (/reference/ui/components/cards) Card components for grouping and presenting content. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `ActiveIncidentsCard` Summary card displaying a list of active incidents/alerts with severity indicators, loading skeleton, and empty state. Rows are virtualized via `@tanstack/react-virtual` so the card stays responsive… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string` | | - | - | | `isLoading` | `boolean` | | - | - | | `className` | `string` | | - | - | | `skeletonRows` | `number` | | - | - | | `emptyMessage` | `string` | | - | - | | `items` | `TIncidentRowProps[]` | | - | - | | `onItemClick` | `(id: string) => void` | | - | - | ### `CabinetDetailCard` Read-only LV cabinet detail: powermeter readings, the root plus per-position temperature readings (severity-coloured, with an offline marker), and the active-warnings timeline. Presentational — shape… `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | ✓ | - | Cabinet display title (`LV Cabinet 1` / transformer title). | | `powerMeters` | `CabinetReadingRow[]` | ✓ | - | Non-root powermeter reading rows. | | `rootTempSensor` | `CabinetReadingRow \| undefined` | | - | The cabinet-root temperature reading, when present. | | `tempSensors` | `CabinetReadingRow[]` | ✓ | - | Non-root temperature sensor reading rows. | | `alarmsDataItems` | `TimelineItemData[]` | ✓ | - | Active-warnings timeline items. | | `onNavigate` | `((path: string) => void) \| undefined` | | - | Router navigate used by warning rows to deep-link into the alert. | | `isLoading` | `boolean \| undefined` | | - | Shows a spinner while the cabinet snapshot is loading. | ### `MetricCard` Compact card displaying a labelled metric value with optional highlight and transparency states. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string` | ✓ | - | - | | `unit` | `string` | ✓ | - | - | | `value` | `string \| number \| null` | ✓ | - | - | | `bgColor` | `string \| undefined` | ✓ | - | - | | `className` | `string \| undefined` | ✓ | - | - | | `noMinWidth` | `boolean \| undefined` | ✓ | - | - | | `isValueMedium` | `boolean \| undefined` | ✓ | - | - | | `isHighlighted` | `boolean \| undefined` | ✓ | - | - | | `showDashForZero` | `boolean \| undefined` | ✓ | - | - | | `isTransparentColor` | `boolean \| undefined` | ✓ | - | - | ### `MiningPoolsPanel` Dashboard card that lists configured mining pools — one row per pool, with revenue, hash rate, and an optional "Show details" action. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string` | | - | Override the card title — defaults to `Mining Pools`. | | `hideHeader` | `boolean` | | - | Hide the title row entirely. | | `isLoading` | `boolean` | | - | Loading state — renders skeleton rows. | | `skeletonRows` | `number` | | - | Number of skeleton rows to show while loading. | | `emptyMessage` | `string` | | - | Message shown when `rows` is empty. | | `rows` | `MiningPoolRow[]` | | - | Pool rows, in display order. | | `onShowDetails` | `(row: MiningPoolRow) => void` | | - | Called when the user clicks the per-row "Show details" button. | | `className` | `string` | | - | Extra className for the root. | ### `PoolDetailsCard` Compact key/value card for displaying pool metadata (URL, fee, worker count, etc.). Empty list renders a "No data available" placeholder. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | ✓ | - | - | | `underline` | `boolean \| undefined` | ✓ | - | - | | `className` | `string \| undefined` | ✓ | - | - | | `details` | `PoolDetailItem[]` | ✓ | - | - | ### `PoolDetailsPopover` [**`Button`**](/reference/ui/components/actions/#button)-triggered popover that displays a pool's key/value details (URL, fee, worker count, status, …) inside a Radix `Dialog`. Wraps `[**`PoolDetailsCard`**](/reference/ui/components/cards/#pooldetailscard)` so the read-out matches the embedded card varian… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string \| undefined` | ✓ | - | - | | `description` | `string \| undefined` | ✓ | - | - | | `disabled` | `boolean \| undefined` | ✓ | - | - | | `className` | `string \| undefined` | ✓ | - | - | | `triggerLabel` | `string \| undefined` | ✓ | - | - | | `details` | `PoolDetailItem[]` | ✓ | - | - | # Chart Components (/reference/ui/components/charts) Components for data visualization and charting. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `ActualEbitdaCard` Stat card summarising the realised EBITDA for the selected reporting window vs the prior period. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `ChartData<"line", (number \| Point \| null)[], unknown>` | ✓ | - | Chart data - required, provided by parent | | `options` | `_DeepPartialObject & ElementChartOptions<"line"> & PluginChartOptions<"line"> & DatasetChartOptions<"line"> & ScaleChartOptions<"line"> & LineControllerChartOptions> \| undefined` | | - | Chart.js options - merged with defaults | | `tooltip` | `ChartTooltipConfig \| undefined` | | - | Custom HTML tooltip configuration. When provided, replaces the default Chart.js tooltip. | | `height` | `number \| undefined` | | - | Chart height in pixels | | `className` | `string \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | | - | - | | `unit` | `string` | | - | - | | `height` | `number` | | - | - | | `barWidth` | `number` | | - | - | | `className` | `string` | | - | - | | `isLoading` | `boolean` | | - | - | | `emptyMessage` | `string` | | - | - | | `data` | `AverageDowntimeChartData` | | - | - | | `yTicksFormatter` | `(value: number) => string` | | - | Formats Y-axis ticks, tooltips, and bar data labels (values are 0–1 rates). | | `showDataLabels` | `boolean` | | - | - | ### `AvgAllInCostChart` Avg All-in [**`Cost`**](/reference/ui/components/dashboards/#cost) - revenue vs cost ($/MWh) bar chart over time. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `readonly AvgAllInCostDataPoint[] \| undefined` | | - | - | | `dateRange` | `FinancialDateRange \| null` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `BarChart` Presentational Chart.js bar chart. Data must be pre-aggregated; use grouped or stacked categories via `datasets`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `any` | ✓ | - | Chart data - required, provided by parent. Use `as any` for mixed bar+line datasets. | | `options` | `_DeepPartialObject & ElementChartOptions<"bar"> & PluginChartOptions<"bar"> & DatasetChartOptions<"bar"> & ScaleChartOptions<"bar"> & BarControllerChartOptions> \| undefined` | | - | Chart.js options - merged with defaults | | `isStacked` | `boolean \| undefined` | | - | Stack bars on top of each other | | `isHorizontal` | `boolean \| undefined` | | - | Render bars horizontally (indexAxis: 'y') | | `formatYLabel` | `((value: number) => string) \| undefined` | | - | Format Y-axis tick labels | | `showLegend` | `boolean \| undefined` | | - | Show built-in Chart.js legend (default: true) | | `legendPosition` | `Position \| undefined` | | - | Position of the legend (default: 'top') | | `legendAlign` | `FlexAlign \| undefined` | | - | Alignment of the legend labels within their position (default: 'start') | | `showDataLabels` | `boolean \| undefined` | | - | Show values above each bar | | `formatDataLabel` | `((value: number) => string) \| undefined` | | - | Format data label values (default: round to nearest integer) | | `tooltip` | `ChartTooltipConfig \| undefined` | | - | Custom HTML tooltip configuration. When provided, replaces the default Chart.js tooltip. | | `height` | `number \| undefined` | | - | Chart height in pixels | | `className` | `string \| undefined` | | - | - | ### `BitcoinPriceCard` Stat card showing the BTC reference price used by the reporting view with currency and timestamp. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | ### `BitcoinProducedCard` Stat card summarising the bitcoin produced during the reporting window with delta to prior period. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | ### `BitcoinProducedChart` Time-series chart of bitcoin produced per day across the selected reporting window. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartData` | `BarChartDataResult` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `hasAllZeros` | `boolean \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | ### `BitcoinProductionCostCard` Stat card showing the average cost in USD to produce one bitcoin during the reporting window. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string \| undefined` | | - | - | | `titleExtra` | `React.ReactNode` | | - | Optional node rendered immediately after the title text (e.g. an info tooltip). Only shown when `title` is set and `hea… | | `header` | `React.ReactNode` | | - | - | | `headerAction` | `React.ReactNode` | | - | Optional action rendered on the right side of the header row (e.g. an expand/fullscreen toggle). Sits alongside the ran… | | `legendData` | `LegendItem[] \| undefined` | | - | - | | `highlightedValue` | `HighlightedValueProps \| undefined` | | - | - | | `rangeSelector` | `RangeSelectorProps \| undefined` | | - | - | | `loading` | `boolean \| undefined` | | - | - | | `empty` | `boolean \| undefined` | | - | - | | `emptyMessage` | `string \| undefined` | | - | - | | `minMaxAvg` | `Partial<{ min: string; max: string; avg: string; }> \| undefined` | | - | - | | `timeRange` | `string \| undefined` | | - | - | | `footer` | `React.ReactNode` | | - | - | | `footerClassName` | `string \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | | `children` | `React.ReactNode` | ✓ | - | - | | `onToggleDataset` | `((index: number) => void) \| undefined` | | - | - | ### `ChartExpandAction` Expand / collapse toggle rendered in a dashboard chart card's header. Swaps between a maximize and a minimize glyph based on `isExpanded`. `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isExpanded` | `boolean` | ✓ | - | Whether the parent chart is currently expanded to full width. | | `onToggle` | `VoidFunction \| undefined` | | - | 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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `minMaxAvg` | `Partial<{ min: string; max: string; avg: string; }>` | | - | Min/Max/Avg values row | | `stats` | `ChartStatsFooterItem[]` | | - | Additional stats displayed in a columnar grid | | `statsPerColumn` | `number` | | - | Number of stat items per column (default: 1) | | `secondaryLabel` | `SecondaryLabel` | | - | Secondary label displayed below stats | | `className` | `string` | | - | Custom class name | ### `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 in… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `costLog` | `readonly CostTimeSeriesEntry[]` | ✓ | - | - | | `btcPriceLog` | `readonly BtcPriceTimeSeriesEntry[]` | ✓ | - | - | | `totals` | `CostSummaryMonetaryTotals \| null` | ✓ | - | - | | `dateRange` | `FinancialDateRange \| null` | ✓ | - | - | | `avgAllInCostData` | `readonly AvgAllInCostDataPoint[] \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `DetailLegend` [**`DetailLegend`**](/reference/ui/components/charts/#detaillegend) - Enhanced chart legend with current values and percentage change indicators `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `items` | `DetailLegendItem[]` | ✓ | - | Legend items to display | | `onToggle` | `((label: string, index: number) => void) \| undefined` | | - | Callback when a legend item is toggled | | `className` | `string \| undefined` | | - | Custom class name | ### `DoughnutChart` [**`DoughnutChart`**](/reference/ui/components/charts/#doughnutchart) – Presentational Chart.js doughnut chart with custom HTML legend matching the MDK design. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `DoughnutChartDataset[]` | ✓ | - | Array of labelled slices | | `unit` | `string \| undefined` | | - | Unit suffix shown in tooltips | | `options` | `_DeepPartialObject & ElementChartOptions<"doughnut"> & PluginChartOptions<"doughnut"> & DatasetChartOptions<"doughnut"> & ScaleChartOptions<"doughnut"> & DoughnutControllerChartOptions> \| undefined` | | - | Chart.js options – merged with defaults | | `cutout` | `string \| undefined` | | - | Doughnut cutout percentage (default: '75%') | | `borderWidth` | `number \| undefined` | | - | Border width between segments (default: 4) | | `height` | `number \| undefined` | | - | Chart height in pixels | | `legendPosition` | `Position \| undefined` | | - | Where to place the legend relative to the chart (default: 'top') | | `tooltip` | `ChartTooltipConfig \| undefined` | | - | Custom HTML tooltip configuration. When provided, replaces the default doughnut tooltip (which shows label, value with… | | `formatValue` | `((value: number) => string) \| undefined` | | - | Formats slice values in the built-in legend and default tooltip (default: raw number). | | `className` | `string \| undefined` | | - | - | ### `Ebitda` Top-level EBITDA section of the reporting view — pulls together metric cards, charts, and tables. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `EbitdaDisplayMetrics \| null` | ✓ | - | - | | `ebitdaChartInput` | `ToBarChartDataInput \| null` | ✓ | - | - | | `btcProducedChartInput` | `ToBarChartDataInput \| null` | ✓ | - | - | | `hasBtcProducedAllZeros` | `boolean` | ✓ | - | - | | `showEbitdaBarChart` | `boolean` | ✓ | - | - | | `currentBTCPrice` | `number` | ✓ | - | - | | `datePicker` | `React.ReactElement>` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `errors` | `string[] \| undefined` | | - | - | | `hasDateSelection` | `boolean` | ✓ | - | When false, show the "select a period" hint instead of empty data. | | `setCostHref` | `string \| undefined` | | - | 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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `showEbitdaBarChart` | `boolean` | ✓ | - | - | | `ebitdaChartData` | `BarChartDataResult` | ✓ | - | - | | `btcDisplayData` | `BarChartDataResult` | ✓ | - | - | | `isLoading` | `boolean` | ✓ | - | - | | `hasBtcProducedAllZeros` | `boolean` | ✓ | - | - | ### `EbitdaHodlCard` Stat card projecting EBITDA assuming all produced bitcoin is held instead of sold. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | | `currentBTCPrice` | `number` | ✓ | - | - | ### `EbitdaMetrics` Row of summary metric cards across the top of the EBITDA section (actual, hodl, selling, cost). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `EbitdaDisplayMetrics` | ✓ | - | - | | `currentBTCPrice` | `number` | ✓ | - | - | ### `EbitdaSellingCard` Stat card projecting EBITDA assuming all produced bitcoin is sold at the daily reference price. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | ### `EnergyBalance` Full energy balance view with tabbed revenue and cost sections, charts, and metric cards. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `viewModel` | `EnergyBalanceViewModel` | ✓ | - | - | | `onTabChange` | `(tab: EnergyBalanceTab) => void` | ✓ | - | - | | `onRevenueDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `onCostDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `isDemoMode` | `boolean \| undefined` | | - | - | | `timeframeControls` | `React.ReactNode` | | - | Slot for timeframe / date-range controls rendered by the host app. | | `setCostHref` | `string \| undefined` | | - | Optional URL for the "Set Monthly [**`Cost`**](/reference/ui/components/dashboards/#cost)" control (hidden when omitted). | ### `EnergyBalanceCostCharts` Layout container for the energy cost tab charts: revenue-vs-cost bar chart and power line chart. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `costChartData` | `BarChartDataResult` | ✓ | - | - | | `btcUnit` | `string \| null` | ✓ | - | - | | `powerChartInput` | `ThresholdLineChartInput` | ✓ | - | - | | `displayMode` | `DisplayMode` | ✓ | - | - | | `barLabelFormatter` | `(v: number) => string` | ✓ | - | - | | `onDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `showCostBarChart` | `boolean` | ✓ | - | Show the revenue-vs-cost bar chart only for non-daily periods. | | `periodType` | `PeriodType` | ✓ | - | - | ### `EnergyBalanceCostMetrics` Grid of stat cards summarising energy cost metrics for the selected period. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `EnergyCostMetrics` | ✓ | - | - | ### `EnergyBalancePowerChart` Line chart visualising power consumption against threshold for the energy balance view. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `height` | `number \| undefined` | | - | - | | `fillHeight` | `boolean \| undefined` | | - | - | | `periodType` | `PeriodType` | ✓ | - | - | | `chartInput` | `ThresholdLineChartInput` | ✓ | - | - | ### `EnergyBalanceRevenueCharts` [**`Mosaic`**](/reference/ui/components/layout/#mosaic) layout of revenue, downtime, and power charts for the energy balance revenue tab. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `revenueChartData` | `BarChartDataResult` | ✓ | - | - | | `averageDowntimeData` | `AverageDowntimeChartData` | ✓ | - | - | | `powerChartInput` | `ThresholdLineChartInput` | ✓ | - | - | | `displayMode` | `DisplayMode` | ✓ | - | - | | `barLabelFormatter` | `(v: number) => string` | ✓ | - | - | | `onDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `periodType` | `PeriodType` | ✓ | - | - | | `revenueMetrics` | `EnergyRevenueMetrics` | ✓ | - | - | ### `EnergyBalanceRevenueMetrics` Grid of stat cards summarising energy revenue metrics for the selected period. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `EnergyRevenueMetrics` | ✓ | - | - | ### `EnergyCostChart` Bar chart comparing site revenue vs cost per MWh, with USD/BTC currency toggle. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartData` | `BarChartDataResult` | ✓ | - | - | | `btcUnit` | `string \| null` | ✓ | - | - | | `displayMode` | `DisplayMode` | ✓ | - | - | | `barLabelFormatter` | `(v: number) => string` | ✓ | - | - | | `onDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `height` | `number \| undefined` | | - | - | ### `EnergyMetricCard` Stat card for a single energy balance metric. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `name` | `string` | ✓ | - | - | | `value` | `number` | ✓ | - | - | | `unit` | `string` | ✓ | - | - | | `fallback` | `string \| undefined` | | - | - | ### `EnergyReportMinerTypeView` Energy report — power consumption grouped by miner model (latest day in range). `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isLoading` | `boolean \| undefined` | | - | - | | `containers` | `Container[] \| undefined` | | - | - | | `groupedConsumption` | `MetricsConsumptionGroupedResponse \| undefined` | | - | - | | `onTimeFrameChange` | `((start: Date, end: Date) => void) \| undefined` | | - | - | ### `EnergyReportMinerUnitView` Energy report — power consumption grouped by mining unit / container. `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isLoading` | `boolean \| undefined` | | - | - | | `containers` | `Container[] \| undefined` | | - | - | | `groupedConsumption` | `MetricsConsumptionGroupedResponse \| undefined` | | - | - | | `onTimeFrameChange` | `((start: Date, end: Date) => void) \| undefined` | | - | - | ### `EnergyReportSiteView` Energy report site tab — power trend, power-mode table, and per–mining-unit activity cards. `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `consumptionError` | `unknown` | | - | - | | `tailLogLoading` | `boolean \| undefined` | | - | - | | `containersLoading` | `boolean \| undefined` | | - | - | | `consumptionLoading` | `boolean \| undefined` | | - | - | | `consumptionFetching` | `boolean \| undefined` | | - | - | | `nominalConfigLoading` | `boolean \| undefined` | | - | - | | `containers` | `EnergyReportContainer[] \| undefined` | | - | - | | `tailLog` | `EnergyReportTailLogItem[][] \| undefined` | | - | - | | `nominalPowerAvailabilityMw` | `number \| null \| undefined` | | - | - | | `consumptionLog` | `MetricsConsumptionLogEntry[] \| undefined` | | - | - | | `snapshotLoading` | `boolean \| undefined` | | - | - | | `onRefetchSnapshot` | `VoidFunction \| undefined` | | - | - | | `dateRange` | `EnergyReportDateRange` | ✓ | - | - | | `onDateRangeChange` | `((range: EnergyReportDateRange) => void) \| undefined` | | - | - | ### `EnergyRevenueChart` Bar chart showing site energy revenue per MWh, with USD/BTC currency toggle. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartData` | `BarChartDataResult` | ✓ | - | - | | `displayMode` | `DisplayMode` | ✓ | - | - | | `barLabelFormatter` | `(v: number) => string` | ✓ | - | - | | `onDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `height` | `number \| undefined` | | - | - | ### `GaugeChart` [**`GaugeChart`**](/reference/ui/components/charts/#gaugechart) - Presentational gauge / speedometer chart. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `percent` | `number` | ✓ | - | Value between 0 and 1 (e.g. 0.75 = 75%). Values outside the range are clamped. | | `colors` | `string[] \| undefined` | | - | Arc colours in HEX format. | | `arcWidth` | `number \| undefined` | | - | Arc thickness as a fraction of the gauge radius (0–1). | | `nrOfLevels` | `number \| undefined` | | - | Number of arc segments. Ignored when `arcsLength` is provided. | | `arcsLength` | `number[] \| undefined` | | - | Custom arc-segment proportions (auto-normalised), overriding `nrOfLevels`. e.g. `[0.7, 0.3]` for a progress-style gauge… | | `needleColor` | `string \| undefined` | | - | Needle + hub colour. | | `hideNeedle` | `boolean \| undefined` | | - | Hide the needle + hub (e.g. for a progress-style gauge). | | `formatTextValue` | `((percent: number) => string) \| undefined` | | - | Format the centre label from the clamped fraction (0–1). | | `hideText` | `boolean \| undefined` | | - | Hide the percentage text rendered inside the gauge. | | `id` | `string \| undefined` | | - | Stable id used for the gauge's accessibility labels. | | `height` | `string \| number \| undefined` | | - | Chart height in pixels or any CSS length (e.g. `'200px'` or `'50%'`). | | `maxWidth` | `number \| undefined` | | - | Maximum width in pixels. | | `className` | `string \| undefined` | | - | - | ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `defaultTab` | `HashrateTabValue \| undefined` | | - | Tab selected on first render. Defaults to the Site View. | | `siteView` | `HashrateSiteViewProps \| undefined` | | - | Props forwarded to the Site View tab. | | `minerTypeView` | `HashrateMinerTypeViewProps \| undefined` | | - | Props forwarded to the Miner Type View tab. | | `miningUnitView` | `HashrateMiningUnitViewProps \| undefined` | | - | Props forwarded to the Mining Unit 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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `log` | `HashrateGroupedLog \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) log grouped by miner type (groupBy=miner). | | `isLoading` | `boolean \| undefined` | | - | - | | `dateRange` | `HashrateDateRange \| undefined` | | - | - | | `onDateRangeChange` | `((range: HashrateDateRange) => void) \| undefined` | | - | - | | `onReset` | `VoidFunction \| undefined` | | - | - | ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `log` | `HashrateGroupedLog \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) log grouped by container / mining unit (groupBy=container). | | `isLoading` | `boolean \| undefined` | | - | - | | `dateRange` | `HashrateDateRange \| undefined` | | - | - | | `onDateRangeChange` | `((range: HashrateDateRange) => void) \| undefined` | | - | - | | `onReset` | `VoidFunction \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `log` | `HashrateGroupedLog \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) log grouped by miner type. | | `isLoading` | `boolean \| undefined` | | - | Loading state - drives the chart spinner. | | `dateRange` | `HashrateDateRange \| undefined` | | - | Selected date range used by the host to drive the query. | | `onDateRangeChange` | `((range: HashrateDateRange) => void) \| undefined` | | - | Fires when the user picks a new range from the [**`DateRangePicker`**](/reference/ui/components/forms/#daterangepicker). | | `onReset` | `VoidFunction \| undefined` | | - | 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. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `HeatmapCell[][]` | ✓ | - | Rows of cells (row-major). Rows may be ragged. | | `min` | `number \| undefined` | | - | Range floor; auto-derived from the finite values when omitted. | | `max` | `number \| undefined` | | - | Range ceiling; auto-derived from the finite values when omitted. | | `colors` | `readonly string[] \| undefined` | | - | Gradient stops low→high. Defaults to the cold→hot `HEATMAP_GRADIENT`. | | `emptyColor` | `string \| undefined` | | - | Colour used for `null` cells. | | `showValues` | `boolean \| undefined` | | - | Render each cell's value/label as text. | | `renderCell` | `((cell: HeatmapCell, context: HeatmapCellContext) => React.ReactNode) \| undefined` | | - | Override the cell's inner content — e.g. to overlay socket borders, selection, or tooltips for a PDU grid. The primitiv… | | `ariaLabel` | `string \| undefined` | | - | Accessible label for the grid. | | `className` | `string \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `min` | `string \| number` | ✓ | - | Value (or pre-formatted label) at the low end of the scale. | | `max` | `string \| number` | ✓ | - | Value (or pre-formatted label) at the high end of the scale. | | `unit` | `string \| undefined` | | - | Unit suffix appended to `min`/`max`. | | `label` | `string \| undefined` | | - | Heading above the gradient bar (e.g. "Temperature"). | | `colors` | `readonly string[] \| undefined` | | - | Gradient stops low→high. Defaults to `HEATMAP_GRADIENT`. | | `className` | `string \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartRef` | `React.MutableRefObject \| undefined` | | - | Mutable ref to hold the LightWeightCharts reference | | `data` | `LineChartData` | ✓ | - | Data of the chart | | `yTicksFormatter` | `((value: number) => string) \| undefined` | | - | Callback to format ticks on y axis. If `priceFormatter` is given. It would be used instead. | | `customLabel` | `string \| undefined` | | - | TODO: Doc | | `priceFormatter` | `((value: number) => string) \| undefined` | | - | Callback to format ticks on y axis. | | `roundPrecision` | `number \| undefined` | | - | The number of decimals to show | | `timeline` | `string \| undefined` | | - | TODO: DOC | | `fixedTimezone` | `string \| undefined` | | - | Applies offset if provided, otherwise timestamps are assumed to already be in local time. Otherwise, use browser's curr… | | `shouldResetZoom` | `boolean \| undefined` | | - | Wether to Reset Zoom | | `skipRound` | `boolean \| undefined` | | - | Prevent rounding of values | | `skipMinWidth` | `boolean \| undefined` | | - | Do not enforce a min width | | `fadedBackground` | `boolean \| undefined` | | - | Use a faded background | | `backgroundColor` | `string \| undefined` | | - | Background color of the chart | | `customDateFormat` | `string \| undefined` | | - | Custom date format | | `verticalLineLabelVisible` | `boolean \| undefined` | | - | Show vertical line at mouse position | | `horizontalLineLabelVisible` | `boolean \| undefined` | | - | Show horizontal line at mouse position | | `showDateInTooltip` | `boolean \| undefined` | | - | Show date line in tooltip | | `disableAutoRange` | `boolean \| undefined` | | - | Disable automatically determining range | | `uniformDistribution` | `boolean \| undefined` | | - | Changes horizontal scale marks generation. With this flag equal to true, marks of the same weight are either all drawn… | | `unit` | `string \| undefined` | | - | The unit to display with values | | `beginAtZero` | `boolean \| undefined` | | - | Starts the value axis at 0 | | `showPointMarkers` | `boolean \| undefined` | | - | Show a marker on the line | | `height` | `number \| undefined` | | - | Controls the height of the chart. Default: 240 | ### `LineChartCard` Composable line-chart card with title, timeline range selector, legend (basic or detailed), error boundary, and an optional min/max/avg footer. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `LineChartCardData` | | - | Pre-adapted chart data (use this OR rawData+dataAdapter) | | `rawData` | `unknown` | | - | Raw data to be transformed by dataAdapter | | `dataAdapter` | `(data: unknown) => LineChartCardData` | | - | Adapter to transform rawData into LineChartCardData | | `timelineOptions` | `TimelineOption[]` | | - | Timeline range selector options | | `timeline` | `string` | | - | Controlled timeline value | | `defaultTimeline` | `string` | | - | Default timeline when uncontrolled | | `onTimelineChange` | `(timeline: string) => void` | | - | Callback when timeline changes | | `title` | `string` | | - | Chart title | | `detailLegends` | `boolean` | | - | Show detail legends with current values | | `isLoading` | `boolean` | | - | Loading state | | `shouldResetZoom` | `boolean` | | - | Whether to reset zoom on timeline change (default: true) | | `chartProps` | `Partial` | | - | Pass-through props to the core [**`LineChart`**](/reference/ui/components/charts/#linechart) | | `chartRef` | `React.MutableRefObject` | | - | Ref to the lightweight-charts IChartApi | | `minHeight` | `string \| number` | | - | - | | `className` | `string` | | - | Custom class name | | `headerAction` | `React.ReactNode` | | - | Optional action rendered on the right of the card header (e.g. an expand toggle). Passed straight through to `ChartCont… | | `titleExtra` | `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `min` | `string \| undefined` | ✓ | - | - | | `max` | `string \| undefined` | ✓ | - | - | | `avg` | `string \| undefined` | ✓ | - | - | | `className` | `string \| undefined` | | - | - | ### `MonthlyEbitdaChart` Bar chart comparing EBITDA across the most recent months for trend visualisation. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartData` | `BarChartDataResult` | ✓ | - | - | | `height` | `number \| undefined` | | - | - | ### `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 d… `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `LineChartCardData` | | - | - | | `isLoading` | `boolean` | | - | - | | `isExpanded` | `boolean` | | - | - | | `onToggleExpand` | `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 - pas… `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `MinersStatusChartData` | | - | - | | `isLoading` | `boolean` | | - | - | | `isExpanded` | `boolean` | | - | - | | `onToggleExpand` | `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 - p… `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `LineChartCardData` | | - | - | | `isLoading` | `boolean` | | - | - | | `isExpanded` | `boolean` | | - | - | | `onToggleExpand` | `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 pr… `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `LineChartCardData` | | - | - | | `isLoading` | `boolean` | | - | - | | `isExpanded` | `boolean` | | - | - | | `onToggleExpand` | `VoidFunction` | | - | - | ### `OperationsEnergyChart` Doughnut breakdown of Operations vs Energy cost (in USD totals). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `totals` | `CostSummaryMonetaryTotals \| null` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | | - | - | | `unit` | `string` | | - | - | | `height` | `number` | | - | - | | `className` | `string` | | - | - | | `isLoading` | `boolean` | | - | - | | `emptyMessage` | `string` | | - | - | | `data` | `Partial<{ energyCostsUSD: number; operationalCostsUSD: number; }>` | | - | - | ### `PowerModeTimelineChart` Timeline chart for power-mode state changes over time. Wraps `[**`TimelineChart`**](/reference/ui/components/charts/#timelinechart)` with mining-specific data shaping. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `PowerModeTimelineEntry[]` | | - | Initial power-mode entries (each with start/end ts + mode). | | `dataUpdates` | `PowerModeTimelineEntry[]` | | - | Streaming updates appended to the initial data. | | `isLoading` | `boolean` | | - | Show a loading skeleton instead of the chart. | | `timezone` | `string` | | - | IANA timezone string for x-axis tick formatting. | | `title` | `string` | | - | Chart title. | ### `ProductionCostChart` Production cost over time, overlaid with BTC price. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `costLog` | `readonly CostTimeSeriesEntry[]` | ✓ | - | - | | `btcPriceLog` | `readonly BtcPriceTimeSeriesEntry[]` | ✓ | - | - | | `dateRange` | `FinancialDateRange \| null` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `RevenueDataItem[]` | | - | - | | `isLoading` | `boolean` | | - | - | | `siteList` | `(string \| SiteItem)[]` | | - | - | | `legendPosition` | `Position` | | - | - | | `legendAlign` | `"center" \| "start" \| "end"` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | | - | - | | `unit` | `string` | | - | - | | `height` | `number` | | - | - | | `isTall` | `boolean` | | - | When true, uses a taller default height (360px). | | `className` | `string` | | - | - | | `emptyMessage` | `string` | | - | - | | `isLegendVisible` | `boolean` | | - | - | | `data` | `ThresholdLineChartData` | | - | - | | `yTicksFormatter` | `(value: number) => string` | | - | - | ### `TimelineChart` Discrete-event timeline chart (e.g. miner state over time) with a category legend. Supports streaming updates via `newData`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `initialData` | `TimelineChartData` | ✓ | - | - | | `newData` | `TimelineChartData \| undefined` | | - | - | | `skipUpdates` | `boolean \| undefined` | | - | - | | `range` | `ChartRange \| undefined` | | - | - | | `axisTitleText` | `AxisTitleText \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `title` | `string \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | # Dashboard Components (/reference/ui/components/dashboard) Components for building dashboard layouts and containers. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `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`… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `counts` | `AlarmsBellButtonCounts \| undefined` | | - | Severity-bucketed alarm counts rendered in the stacked badge. | | `onClick` | `((event: React.MouseEvent) => void) \| undefined` | | - | Click handler — typically opens an alerts panel or routes to /alerts. | | `onSeverityClick` | `((severity: AlarmSeverity, event: React.MouseEvent) => void) \| undefined` | | - | Click handler for an individual severity count. When provided, each badge row becomes its own button so an operator can… | | `label` | `string \| undefined` | | - | Accessible label. Defaults to "Active alarms". | | `className` | `string \| undefined` | | - | - | ### `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` fro… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `DashboardDateRange` | ✓ | - | Current range as `{ start, end }` epoch-millisecond timestamps. | | `onChange` | `(next: DashboardDateRange) => void` | ✓ | - | Fires with the next `{ start, end }` window when the user applies a range. | | `dateFormat` | `string \| undefined` | | - | Display format. Defaults to `dd/MM/yyyy`. | | `disabled` | `boolean \| undefined` | | - | Disable the trigger. | | `className` | `string \| undefined` | | - | Optional class hook. | ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `onExport` | `(format: ExportFormat) => void` | ✓ | - | Fires with the chosen format when the user picks an item. | | `formats` | `readonly ExportFormat[] \| undefined` | | - | Formats to offer in the dropdown — defaults to `['csv', 'json']`. | | `label` | `string \| undefined` | | - | [**`Button`**](/reference/ui/components/actions/#button) label — defaults to `'Export'`. | | `disabled` | `boolean \| undefined` | | - | Disable the button. | | `className` | `string \| undefined` | | - | Optional class hook on the wrapper. | ### `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 Mining OS visual treatment. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | | - | - | | `valueMw` | `number \| undefined` | | - | Current site-level power consumption, in megawatts. | | `unit` | `string \| undefined` | | - | Unit label — defaults to `MW`. | | `className` | `string \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | | - | - | | `valueWthS` | `number \| undefined` | | - | Efficiency in watts per TH/s. | | `unit` | `string \| undefined` | | - | Unit label — defaults to `W/TH/S`. | | `className` | `string \| undefined` | | - | - | ### `HeaderHashrateBox` Two-row hashrate cell for the dashboard's header strip. Shows the MOS-side and pool-side aggregate hashrate side by side. Values fall back to `—` when undefined. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | | - | - | | `mosPhs` | `number \| undefined` | | - | MOS-side aggregate hashrate in PH/s. | | `poolPhs` | `number \| undefined` | | - | Pool-side aggregate hashrate in PH/s. | | `unit` | `string \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) unit label — defaults to `PH/s`. | | `className` | `string \| undefined` | | - | - | ### `HeaderMinersBox` Two-row miner-count cell for the dashboard's header strip. Top row carries the MOS-side `online / error / offline` breakdown; the bottom row shows the pool-side equivalent. Numbers fall back to `—` w… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | | - | Icon shown next to the "Miners" label. Caller-provided so the package stays icon-agnostic. | | `total` | `number \| undefined` | | - | Total miners across the site (denominator of the `158 / 2,188` ratio). | | `online` | `number \| undefined` | | - | Online miners (the `158` numerator). | | `error` | `number \| undefined` | | - | Miners flagged in warning (the small amber count). | | `offline` | `number \| undefined` | | - | Miners offline (the small red count). | | `mosTotal` | `number \| undefined` | | - | Optional MOS-side meta line — total miners reporting to MOS. | | `poolTotal` | `number \| undefined` | | - | Optional pool-side meta — total miners as reported by upstream pools. | | `poolOnline` | `number \| undefined` | | - | Optional pool-side online count (green). | | `poolMismatch` | `number \| undefined` | | - | Optional pool-side mismatch count (red). | | `className` | `string \| undefined` | | - | - | ### `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 `<[**`AppHeader`**](/reference/ui/components/navigation/#appheader)>` as the middle slot. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `children` | `React.ReactNode` | ✓ | - | Stat boxes to render in order, left-to-right. | | `className` | `string \| undefined` | | - | 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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `items` | `ProfileMenuItem[]` | ✓ | - | Items rendered in the dropdown, top-to-bottom. Defaults to a single "Sign out" item. | | `user` | `React.ReactNode` | | - | Optional user label rendered at the top of the dropdown (e.g. an email). | | `icon` | `React.ReactNode` | | - | Override the trigger icon — defaults to the user-avatar icon. | | `label` | `string \| undefined` | | - | Accessible label for the trigger button. | | `className` | `string \| undefined` | | - | - | ### `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 c… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | ✓ | - | Site label rendered in the header row. | | `power` | `number \| undefined` | | - | Current site-level power consumption, in watts (or whatever `powerUnit` says). | | `powerUnit` | `string \| undefined` | | - | Display unit for `power` — defaults to `kW`. | | `totalHashrate` | `number \| undefined` | | - | Aggregate hashrate, in TH/s. | | `hashrateUnit` | `string \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) display unit — defaults to `TH/s`. | | `minerCount` | `number \| undefined` | | - | Total miner count across the site. | | `containerCount` | `number \| undefined` | | - | Total container count across the site. | | `isLoading` | `boolean \| undefined` | | - | Render a skeleton bar while data is loading. | | `className` | `string \| undefined` | | - | Optional class hook. | ### `TimelineSelector` Dropdown for picking the dashboard time range. Wraps `core/[**`Select`**](/reference/ui/components/forms/#select)` and the canonical option list from `getTimelineOptions`. Pair with the `useDashboardTimeRange` hook in `@tetherto/mdk-react-adapter`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `string` | ✓ | - | Currently selected timeline value (e.g. `'1m'`, `'5m'`). | | `onChange` | `(next: string) => void` | ✓ | - | Called whenever the user picks a new option. | | `options` | `TimelineOption[] \| undefined` | | - | Available options — defaults to `getTimelineOptions`. Pass a custom list to localise labels or restrict the range. | | `label` | `string \| undefined` | | - | ARIA label / placeholder for the trigger. | | `className` | `string \| undefined` | | - | Tailwind/BEM class hook on the trigger. | # Dashboard Compositions (/reference/ui/components/dashboards) Pre-composed dashboard layouts and templates. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `ActionsSidebar` Full-height side panel for the MiningOS voting/approval workflow. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `className` | `string \| undefined` | | - | Extra class names merged onto the sidebar root element. | ### `Cost` [**`Cost`**](/reference/ui/components/dashboards/#cost) Summary - composite reporting page (single-site). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `CostSummaryDisplayMetrics \| null` | ✓ | - | - | | `costLog` | `readonly CostTimeSeriesEntry[]` | ✓ | - | - | | `btcPriceLog` | `readonly BtcPriceTimeSeriesEntry[]` | ✓ | - | - | | `totals` | `CostSummaryMonetaryTotals \| null` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `error` | `unknown` | | - | - | | `dateRange` | `FinancialDateRange \| null` | ✓ | - | - | | `avgAllInCostData` | `readonly AvgAllInCostDataPoint[] \| undefined` | | - | Optional revenue/cost time-series for the Avg All-in [**`Cost`**](/reference/ui/components/dashboards/#cost) panel. | | `controls` | `React.ReactElement>` | ✓ | - | Period selector element. Pass `<[**`TimeframeControls`**](/reference/ui/components/filters/#timeframecontrols)>` for the OSS-style year/month picker. | | `setCostAction` | `React.ReactElement> \| undefined` | | - | Optional "Set Monthly [**`Cost`**](/reference/ui/components/dashboards/#cost)" header action slot. | ### `CostContent` Renders the data-driven portion of the [**`Cost`**](/reference/ui/components/dashboards/#cost) page in a 2x2 [**`Mosaic`**](/reference/ui/components/layout/#mosaic) grid: `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `CostSummaryDisplayMetrics \| null` | ✓ | - | - | | `costLog` | `readonly CostTimeSeriesEntry[]` | ✓ | - | - | | `btcPriceLog` | `readonly BtcPriceTimeSeriesEntry[]` | ✓ | - | - | | `totals` | `CostSummaryMonetaryTotals \| null` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `error` | `unknown` | | - | - | | `dateRange` | `FinancialDateRange \| null` | ✓ | - | - | | `avgAllInCostData` | `readonly AvgAllInCostDataPoint[] \| undefined` | | - | Optional revenue/cost time-series for the Avg All-in [**`Cost`**](/reference/ui/components/dashboards/#cost) panel. | ### `EnergyReport` Operational Energy report — site consumption trend, power modes by miner type, and per–mining-unit / per–miner-type bar charts. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `defaultTab` | `EnergyReportTabValue \| undefined` | | - | - | | `siteView` | `(Omit & { dateRange?: EnergyReportDateRange \| undefined; }) \| undefined` | | - | - | | `minerTypeView` | `EnergyReportGroupedBarViewProps \| undefined` | | - | - | | `minerUnitView` | `EnergyReportGroupedBarViewProps \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | ### `HashBalance` Hash balance reporting page — revenue vs cost tabs with site hash revenue, network hashrate, hashprice charts, and integrated timeframe controls. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isError` | `boolean` | | - | - | | `isLoading` | `boolean` | | - | - | | `errorMessage` | `string` | | - | - | | `className` | `string` | | - | - | | `tabsClassName` | `string` | | - | - | | `tabsListClassName` | `string` | | - | - | | `data` | `HashRevenueResponse \| null` | | - | - | | `initialDateRange` | `FinancialDateRange` | | - | - | | `onDateRangeChange` | `(dateRange: FinancialDateRange, query: FinanceQueryParams) => void` | | - | - | ### `HashBalanceCostPanel` [**`Cost`**](/reference/ui/components/dashboards/#cost) tab panel for hash balance — metric tiles and combined cost / revenue / network hashprice bar chart for the selected period. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `HashRevenueResponse \| null \| undefined` | | - | - | | `log` | `HashRevenueLogEntry[] \| undefined` | | - | - | | `dateRange` | `FinancialDateRange` | ✓ | - | - | | `timeframeType` | `TimeframeTypeValue \| null \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `HashBalanceRevenuePanel` Revenue tab panel for hash balance — site hash revenue, network hashrate, hashprice charts, and currency toggle for per-PH/day units. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `HashRevenueResponse \| null \| undefined` | | - | - | | `log` | `HashRevenueLogEntry[] \| undefined` | | - | - | | `dateRange` | `FinancialDateRange` | ✓ | - | - | | `timeframeType` | `TimeframeTypeValue \| null \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `currency` | `HashBalanceCurrency` | ✓ | - | - | | `onCurrencyChange` | `(currency: HashBalanceCurrency) => void` | ✓ | - | - | ### `OperationalDashboard` Operational dashboard - a 2x2 grid of the four site-operations charts (hashrate, power consumption, site efficiency, miners status). Each card can expand to full width; expand state persists across r… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `hashrate` | `OperationalDashboardTrendInput` | | - | - | | `consumption` | `OperationalDashboardTrendInput` | | - | - | | `efficiency` | `OperationalDashboardTrendInput` | | - | - | | `miners` | `OperationalDashboardMinersInput` | | - | - | | `controls` | `React.ReactElement>` | | - | Optional controls (e.g. a date-range picker) rendered above the grid. | ### `PendingActionsButton` Header action tile showing the total count of pending actions (local drafts + submitted voting actions + others' requests). Clicking opens the `[**`ActionsSidebar`**](/reference/ui/components/dashboards/#actionssidebar)` via the shared `actionsStore` tog… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `onClick` | `((event: React.MouseEvent) => void) \| undefined` | | - | Click handler override — defaults to toggling the actionsStore sidebar. | | `className` | `string \| undefined` | | - | - | ### `PoolManager` Composite Pool Manager surface. Owns internal, state-based view switching across the dashboard and the four feature views (Pools, Miner Explorer, Sites Overview, Site Detail) so the whole experience… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `poolConfig` | `PoolConfigEntry[]` | ✓ | - | Pool configurations shared by every sub-view (Pools, Miner Explorer, Sites). | | `stats` | `DashboardStats \| undefined` | | - | Dashboard site-level stat blocks. | | `isStatsLoading` | `boolean \| undefined` | | - | Dashboard stats loading flag. | | `alerts` | `Alert[] \| undefined` | | - | Recent alerts for the dashboard list. | | `onViewAllAlerts` | `VoidFunction \| undefined` | | - | Dashboard "View All [**`Alerts`**](/reference/ui/components/tables/#alerts)" handler (e.g. navigate to `/alerts`). | | `miners` | `ListThingsDevice[] \| undefined` | | - | Miners for the Miner Explorer view. | | `units` | `ProcessedContainerUnit[] \| undefined` | | - | Normalised site units for the Sites Overview view. | | `isSitesLoading` | `boolean \| undefined` | | - | Sites Overview loading flag. | | `sitesError` | `unknown` | | - | Sites Overview error. | | `siteDevices` | `ContainerUnit[] \| undefined` | | - | Raw container devices used to resolve the selected unit for Site Detail. | | `siteDetailDataOptions` | `SiteOverviewDetailsDataOptions \| undefined` | | - | Extra data-fetch knobs forwarded to the Site Detail container. | | `isSiteDetailLoading` | `boolean \| undefined` | | - | Site Detail loading flag. | | `initialView` | `PoolManagerView \| undefined` | | - | Initial view (defaults to `dashboard`). | | `view` | `PoolManagerView \| undefined` | | - | Controlled view — when provided the component syncs its internal state to this value whenever it changes (e.g. driven b… | | `onViewChange` | `((view: PoolManagerView) => void) \| undefined` | | - | Notified whenever the active view changes (lets the page lazy-fetch). | | `onSiteSelect` | `((unitId: string) => void) \| undefined` | | - | Notified with the selected unit id when a site card is opened. | | `className` | `string \| undefined` | | - | - | ### `PoolManagerDashboard` Landing page for the Pool Manager: site-level stats, primary navigation blocks, and a compact recent-alerts list. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `stats` | `DashboardStats \| undefined` | | - | - | | `isStatsLoading` | `boolean \| undefined` | | - | - | | `alerts` | `Alert[] \| undefined` | | - | - | | `onNavigationClick` | `(url: string) => void` | ✓ | - | - | | `onViewAllAlerts` | `VoidFunction` | ✓ | - | - | ### `PoolManagerSiteOverviewDetails` Pool-manager site detail page — drilldown for a single site showing configured pools, recent miner activity, and performance charts. Renders a breadcrumb header (`Site Overview / <unitName>`) and del… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `unit` | `UnitData` | ✓ | - | The site (container unit) to render details for. | | `unitName` | `string` | ✓ | - | Display name shown in the breadcrumb (`Site Overview / <unitName>`). | | `poolConfig` | `PoolConfigEntry[]` | ✓ | - | Pool configurations powering the per-pool detail rows. | | `dataOptions` | `SiteOverviewDetailsDataOptions \| undefined` | | - | Optional data-fetch knobs forwarded to `[**`useSiteOverviewDetailsData`**](/reference/ui/hooks/dashboards/#usesiteoverviewdetailsdata)`. | | `isLoading` | `boolean \| undefined` | | - | Show a centered loader instead of the detail container. | | `backButtonClick` | `VoidFunction` | ✓ | - | Called when the operator clicks the "Site Overview" back link. | ### `PoolManagerSitesOverview` Pool-manager sites overview page — landing screen listing every site as a status card with a snapshot of pools, miners online, hashrate, and any active incidents. Each card navigates to the site deta… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `units` | `ProcessedContainerUnit[]` | ✓ | - | Sites to render (already normalised through `useSitesOverviewData`). | | `poolConfig` | `PoolConfigEntry[]` | ✓ | - | Pool configurations powering each card's pool summary. | | `isLoading` | `boolean \| undefined` | | - | Show a skeleton placeholder while site data is fetching. | | `error` | `unknown` | | - | Surface a "could not load sites" message when defined. | | `backButtonClick` | `VoidFunction` | ✓ | - | Called when the operator clicks the "Pool Manager" back link. | | `onCardClick` | `(unitId: string) => void` | ✓ | - | Called with the clicked unit id — typically navigates to `/sites/:id`. | ### `SubsidyFee` Subsidy & fees reporting view — combines a stacked bar chart of mining rewards (subsidy vs fees) with optional summary stat cards and a timeframe selector. Drives data through the companion `useSubsi… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isError` | `boolean` | | - | - | | `isLoading` | `boolean` | | - | - | | `errorMessage` | `string` | | - | - | | `showSummaryCards` | `boolean` | | - | - | | `log` | `SubsidyFeesLogEntry[]` | | - | - | | `data` | `SubsidyFeesResponse \| null` | | - | - | | `onDateRangeChange` | `(dateRange: FinancialDateRange, query: FinanceQueryParams) => void` | | - | - | # Dialog Components (/reference/ui/components/dialogs) Modal and dialog components for user interactions. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `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. Va… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `partTypes` | `SparePartSubTypesModalPartType[]` | ✓ | - | - | | `defaultPartTypeId` | `string \| undefined` | | - | - | | `modelOptions` | `FormSelectOption[]` | ✓ | - | - | | `isModelOptionsLoading` | `boolean \| undefined` | | - | - | | `minerModelOptions` | `FormSelectOption[]` | ✓ | - | - | | `statusOptions` | `FormSelectOption[]` | ✓ | - | - | | `locationOptions` | `FormSelectOption[]` | ✓ | - | - | | `isControllerPartTypeSelected` | `boolean \| undefined` | | - | - | | `onPartTypeChange` | `(partTypeId: string) => void` | ✓ | - | - | | `onSubmit` | `(values: AddSparePartFormValues) => Promise` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `subTypesPartTypes` | `SparePartSubTypesModalPartType[] \| undefined` | | - | - | | `subTypesActivePartTypeId` | `string \| undefined` | | - | - | | `subTypes` | `string[] \| undefined` | | - | - | | `onSubTypesPartTypeChange` | `((id: string) => void) \| undefined` | | - | - | | `onAddSubType` | `((name: string) => Promise) \| undefined` | | - | - | | `isSubTypesLoading` | `boolean \| undefined` | | - | - | ### `AlertDialogAction` Primary confirmation button inside an `<AlertDialog>`; clicking dismisses the dialog and runs the action handler. `agent-ready` ### `AlertDialogCancel` Secondary dismiss button inside an `<AlertDialog>`; closes the dialog without invoking the destructive action. `agent-ready` ### `AlertDialogContent` Modal content surface for an `<AlertDialog>` — renders the centered panel above the overlay with focus trap. `agent-ready` ### `AlertDialogDescription` Supporting body text inside an `<AlertDialog>`; conveys the consequences of the action being confirmed. `agent-ready` ### `AlertDialogFooter` Right-aligned action row inside an `<AlertDialog>` — hosts the cancel and confirm buttons. `agent-ready` ### `AlertDialogHeader` Top section of an `<AlertDialog>` that groups the title and description above the action row. `agent-ready` ### `AlertDialogOverlay` Full-viewport scrim rendered behind an `<AlertDialog>` to block interaction with the page. `agent-ready` ### `AlertDialogTitle` Prominent title text inside an `<AlertDialog>` summarising the action that requires confirmation. `agent-ready` ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onClose` | `() => void` | ✓ | - | - | | `onSubmit` | `(values: { pool: PoolSummary; }) => Promise` | ✓ | - | - | | `miners` | `Device[]` | ✓ | - | - | | `poolConfig` | `PoolConfigEntry[]` | ✓ | - | - | ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `spareParts` | `BatchMoveSparePart[]` | ✓ | - | - | | `locationOptions` | `FormSelectOption[]` | ✓ | - | - | | `statusOptions` | `FormSelectOption[]` | ✓ | - | - | | `onSubmit` | `(values: { location: string \| null; status: string \| null; observation: string \| null; }) => void \| Promise` | ✓ | - | - | ### `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; CS… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `onSubmit` | `(records: CSVRecord[]) => Promise` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean \| undefined` | | - | - | | `onClose` | `VoidFunction \| undefined` | | - | - | | `onConfirm` | `((sparePart: ConfirmDeleteSparePartModalSparePart) => void \| Promise) \| undefined` | | - | - | | `sparePart` | `ConfirmDeleteSparePartModalSparePart \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `DialogContent` Centered modal surface for a `<Dialog>` — renders above the overlay with focus trap and Escape-to-close. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `closeOnClickOutside` | `boolean \| undefined` | | - | - | | `closeOnEscape` | `boolean \| undefined` | | - | - | | `bare` | `boolean \| undefined` | | - | - | | `closable` | `boolean \| undefined` | | - | - | | `onClose` | `VoidFunction \| undefined` | | - | - | ### `DialogDescription` Supporting body copy inside a `<Dialog>` rendered below the title. `agent-ready` ### `DialogFooter` Action row at the bottom of a `<Dialog>` — typically primary/secondary buttons. `agent-ready` ### `DialogHeader` Top region of a `<Dialog>` that groups the title and description. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `bare` | `boolean \| undefined` | | - | - | | `closable` | `boolean \| undefined` | | - | - | | `onClose` | `VoidFunction \| undefined` | | - | - | ### `DialogOverlay` Full-viewport scrim rendered behind an open `<Dialog>` to block background interaction. `agent-ready` ### `DialogTitle` Prominent title text at the top of a `<Dialog>` summarising the modal's purpose. `agent-ready` ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | | - | - | | `onClose` | `() => void` | | - | - | | `movement` | `MovementData` | | - | - | ### `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 t… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean \| undefined` | | - | - | | `onClose` | `VoidFunction \| undefined` | | - | - | | `sparePart` | `MoveSparePartModalSparePart \| undefined` | | - | - | | `requestedValues` | `{ location?: string \| undefined; status?: string \| undefined; } \| undefined` | | - | - | | `locationOptions` | `FormSelectOption[]` | ✓ | - | - | | `statusOptions` | `FormSelectOption[]` | ✓ | - | - | | `onSubmit` | `(values: { location: string; status: string; observation: string; }, sparePart: MoveSparePartModalSparePart) => void \| Promise` | ✓ | - | - | ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `partTypes` | `SparePartSubTypesModalPartType[]` | ✓ | - | - | | `activePartTypeId` | `string` | ✓ | - | - | | `onPartTypeChange` | `(id: string) => void` | ✓ | - | - | | `subTypes` | `string[]` | ✓ | - | - | | `onAddSubType` | `(name: string) => Promise` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | # Display Components (/reference/ui/components/display) Components for displaying and formatting data. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `Avatar` Circular avatar surface that shows a profile image with a graceful text fallback when the image fails to load. `agent-ready` ### `AvatarFallback` Initials or icon placeholder shown inside `<[**`Avatar`**](/reference/ui/components/display/#avatar)>` while the image loads or when no image is available. `agent-ready` ### `AvatarImage` Profile image slot inside `<[**`Avatar`**](/reference/ui/components/display/#avatar)>` — renders `src` and triggers the fallback on load failure. `agent-ready` ### `Badge` [**`Badge`**](/reference/ui/components/display/#badge) component - Display badge with number or dot `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `children` | `React.ReactNode` | | - | [**`Badge`**](/reference/ui/components/display/#badge) content (wraps children with badge) | | `count` | `number \| undefined` | | - | Number to display in badge If > overflowCount, will show "overflowCount+" | | `overflowCount` | `number \| undefined` | | `99` | Maximum count to display | | `showZero` | `boolean \| undefined` | | `false` | Whether to show badge when count is 0 | | `dot` | `boolean \| undefined` | | `false` | Show badge as a dot | | `text` | `string \| undefined` | | - | Custom badge content (overrides count) | | `color` | `ColorVariant \| undefined` | | `'primary'` | Color variant | | `size` | `ComponentSize \| undefined` | | `'md'` | [**`Badge`**](/reference/ui/components/display/#badge) size | | `offset` | `[number, number] \| undefined` | | `[0, 0]` | Offset position [x, y] in pixels | | `square` | `boolean \| undefined` | | `false` | Square badge (no border-radius) | | `className` | `string \| undefined` | | - | Custom className for badge | | `wrapperClassName` | `string \| undefined` | | - | Custom className for wrapper | | `title` | `string \| undefined` | | - | [**`Badge`**](/reference/ui/components/display/#badge) title for accessibility | | `status` | `"success" \| "warning" \| "error" \| "default" \| "processing" \| undefined` | | - | Status badge (small dot badge with text) | ### `BtcAveragePrice` Read-only BTC average price label for reporting toolbars. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `price` | `number \| null` | | - | BTC price in USD; formatted with grouping and no decimal places. When `null`, `undefined`, non-finite, or negative, the… | | `label` | `string` | | - | [**`Label`**](/reference/ui/components/forms/#label) for the BTC average price. | ### `DataLabel` Read-only period label (`PERIOD: start - end`) with timezone-aware dates. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `startDate` | `Date \| null` | | - | Range start; formatted in the active timezone (`dd/MM/yy`). | | `endDate` | `Date \| null` | | - | Range end; formatted in the active timezone (`dd/MM/yy`). | | `label` | `string` | | - | [**`Label`**](/reference/ui/components/forms/#label) text; defaults to `PERIOD`. | ### `Indicator` [**`Indicator`**](/reference/ui/components/display/#indicator) component - display status with colored background and label `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `color` | `"red" \| "gray" \| "blue" \| "yellow" \| "green" \| "purple" \| "amber" \| "slate" \| undefined` | | `'gray'` | Color variant of the indicator | | `size` | `ComponentSize \| undefined` | | `'md'` | Size variant of the indicator | | `className` | `string \| undefined` | | - | Custom className for the root element | | `vertical` | `boolean \| undefined` | | `false` | When true, adds extra spacing between child elements and stacks them vertically. Useful for displaying multiple pieces… | | `children` | `React.ReactNode` | | - | Children content (can include text, icons, multiple elements) | | `onClick` | `(VoidFunction & React.MouseEventHandler) \| undefined` | | - | Click handler | ### `Tag` [**`Tag`**](/reference/ui/components/display/#tag) component - display labels, categories, or status `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `color` | `"red" \| "blue" \| "green" \| "amber" \| "dark" \| undefined` | | `'dark'` | Color variant of the tag | | `className` | `string \| undefined` | | - | Custom className for the root element | | `children` | `React.ReactNode` | | - | Children content | ### `Typography` [**`Typography`**](/reference/ui/components/display/#typography) component for consistent text styling `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `variant` | `"body" \| "caption" \| "secondary" \| "heading1" \| "heading2" \| "heading3" \| undefined` | | `'body'` | [**`Typography`**](/reference/ui/components/display/#typography) variant | | `size` | `"sm" \| "md" \| "lg" \| "xs" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| undefined` | | `undefined (uses variant default)` | Text size | | `weight` | `"medium" \| "normal" \| "light" \| "semibold" \| "bold" \| undefined` | | `undefined (uses variant default)` | Font weight | | `align` | `TextAlign \| undefined` | | - | Text alignment | | `color` | `"success" \| "warning" \| "error" \| "primary" \| "default" \| "muted" \| undefined` | | - | Text color variant | | `truncate` | `boolean \| undefined` | | - | Truncate text with ellipsis | | `className` | `string \| undefined` | | - | Custom className | # Feature Components (/reference/ui/components/features) Composite components for specific application features. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `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 /… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `name` | `React.ReactNode` | | - | Container display name shown in the header. Optional — omit it when the host already renders the container name as the… | | `tabs` | `ContainerDetailTab[]` | ✓ | - | Ordered tabs for this container model (already resolved by the page). | | `activeTab` | `string` | ✓ | - | Currently active tab key. | | `onTabChange` | `(tab: string) => void` | ✓ | - | Fired with the next tab key when the operator switches tabs. | | `onBack` | `() => void` | ✓ | - | Fired when the back link is clicked (the page decides where to go). | | `backLabel` | `React.ReactNode` | | - | Back-link label. Defaults to "Explorer". | | `children` | `React.ReactNode` | | - | The active tab's body — supplied by the page (real content or a placeholder). | | `className` | `string \| undefined` | | - | - | ### `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 ho… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `containers` | `ContainerWidgetItem[]` | ✓ | - | Card-ready data for every container, shaped by the data hook. | | `title` | `string \| undefined` | | - | Section heading. | | `isLoading` | `boolean \| undefined` | | - | Shows a spinner while the first load is in flight. | | `errorMessage` | `string \| undefined` | | - | Error message shown in place of the grid. | | `onContainerClick` | `((id: string) => void) \| undefined` | | - | Invoked with the container id when a card is clicked. | | `className` | `string \| undefined` | | - | - | ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string \| undefined` | | - | Page heading. | | `headerActions` | `React.ReactNode` | | - | Optional header controls (export button, etc.) shown next to the title. | | `list` | `React.ReactNode` | ✓ | - | The list column — typically a tab switch plus the device/container table. | | `detail` | `React.ReactNode` | | - | The detail column content (shown in the sticky panel when `hasSelection`). | | `hasSelection` | `boolean \| undefined` | | - | When true the layout splits into list (70%) + a sticky detail column (30%); otherwise the list fills the width. Driven… | | `className` | `string \| undefined` | | - | - | # Feedback Components (/reference/ui/components/feedback) Components for providing feedback and notifications to users. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `AlarmContents` Body region of an alarm card listing the alert details and recommended next actions. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `alarmsData` | `unknown` | ✓ | - | - | | `onNavigate` | `(path: string) => void` | ✓ | - | - | ### `AlarmRow` Single alarm-feed row with severity dot, timestamp, source device, and the alert message. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `TimelineItemData` | ✓ | - | - | | `onNavigate` | `(path: string) => void` | ✓ | - | - | ### `CoreAlert` Inline alert banner with type-based icon, optional description, dismissible close button, and trailing action slot. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `type` | `AlertType \| undefined` | | - | Alert type | | `title` | `React.ReactNode` | | - | Main message | | `description` | `React.ReactNode` | | - | Additional description | | `showIcon` | `boolean \| undefined` | | - | Show the type icon | | `icon` | `React.ReactNode` | | - | Custom icon (used when showIcon is true) | | `closable` | `boolean \| undefined` | | - | Makes the alert closable | | `onClose` | `React.MouseEventHandler \| undefined` | | - | Called when close button is clicked | | `banner` | `boolean \| undefined` | | - | Display as full-width banner (no border radius, no margin) | | `action` | `React.ReactNode` | | - | Action element rendered to the right | | `className` | `string \| undefined` | | - | Custom className | | `style` | `React.CSSProperties \| undefined` | | - | Custom styles | ### `EmptyState` Empty state component for displaying placeholder content when no data is available. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `description` | `React.ReactNode` | ✓ | - | Description text or ReactNode displayed below the image | | `image` | `EmptyStateImage` | | `"default"` | Image to display. Use "default" for the standard illustration, "simple" for a minimal icon, or pass a custom ReactNode. | | `size` | `ComponentSize \| undefined` | | `"md"` | Size variant controlling spacing and icon dimensions | | `className` | `string \| undefined` | | - | Additional CSS class name | ### `ErrorCard` Error card component for displaying error messages. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `error` | `string` | ✓ | - | Error message string. Supports `\\n` for line breaks. | | `title` | `string \| undefined` | | `"Errors"` | Title displayed above the error message | | `variant` | `ErrorCardVariant \| undefined` | | `"card"` | Display variant. "card" shows a bordered container, "inline" shows flat text. | | `className` | `string \| undefined` | | - | Additional CSS class name | ### `Loader` [**`Loader`**](/reference/ui/components/feedback/#loader) component - display pulsing dots animation `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `size` | `number \| undefined` | | `10` | Size of each dot in pixels | | `count` | `3 \| 5 \| 7 \| undefined` | | `5` | Number of dots to display | | `color` | `"red" \| "gray" \| "blue" \| "amber" \| "orange" \| undefined` | | `'orange'` | Color variant of the loader | | `className` | `string \| undefined` | | - | Custom className for the root element | ### `SkeletonBlock` Rectangular shimmer placeholder used to hint at content shape while data is loading. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `circle` | `boolean` | | - | - | | `className` | `string` | | - | - | | `width` | `string \| number` | | - | - | | `height` | `string \| number` | | - | - | | `borderRadius` | `string \| number` | | - | - | ### `Spinner` [**`Spinner`**](/reference/ui/components/feedback/#spinner) component - display loading state with rotating squares `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `size` | `ComponentSize \| undefined` | | `'md'` | Size variant of the spinner | | `color` | `"primary" \| "secondary" \| undefined` | | `'primary'` | Color variant of the spinner | | `fullScreen` | `boolean \| undefined` | | `false` | Whether to display in fullscreen mode | | `className` | `string \| undefined` | | - | Custom className for the root element | | `label` | `string \| undefined` | | - | Optional label text to display below the spinner | | `speed` | `"slow" \| "normal" \| "fast" \| undefined` | | `'normal'` | Speed of the animation | | `type` | `"circle" \| "square" \| undefined` | | `'dot'` | Type of spinner animation | ### `Toast` Single transient notification rendered inside the `<[**`Toaster`**](/reference/ui/components/feedback/#toaster)>` viewport. Use `variant` to convey intent (`default`, `success`, `error`, `warning`, `info`); pair with `<ToastTitle>` and `<ToastDescript… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `description` | `string \| undefined` | | - | - | | `variant` | `NotificationVariant \| undefined` | | - | - | | `icon` | `React.JSX.Element \| undefined` | | - | - | ### `Toaster` Top-level provider + viewport that hosts every toast triggered via `useToast`. Mount once near the root of your app (typically inside `<MdkProvider>`). Without a `<[**`Toaster`**](/reference/ui/components/feedback/#toaster)>` in the tree, `useToast` c… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `position` | `ToastPosition \| undefined` | | - | - | # Filter Components (/reference/ui/components/filters) Components for filtering and searching data. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `ListViewFilter` Toolbar of dropdown/checkbox filters that drive a list view; emits the active filter set to the parent. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `options` | `CascaderOption[]` | ✓ | - | [**`Cascader`**](/reference/ui/components/forms/#cascader) options for filtering | | `filterKey` | `string \| undefined` | | - | 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 th… | | `localFilters` | `LocalFilters \| undefined` | | - | Current filter values as key-value pairs Example: { type: 'Antminer S19XP H', status: ['active', 'pending'] } | | `onChange` | `(selections: CascaderValue[]) => void` | ✓ | - | Callback when filters change | | `className` | `string \| undefined` | | - | Custom className for the filter button | ### `ReportTimeFrameSelector` Reporting-period selector with preset windows (7d / 30d / month-to-date / custom range). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `dateRange` | `[Date, Date]` | ✓ | - | - | | `presetTimeFrame` | `number \| null` | ✓ | - | - | | `setPresetTimeFrame` | `(value: number \| null) => void` | ✓ | - | - | | `setDateRange` | `(value: [Date, Date]) => void` | ✓ | - | - | ### `TimeframeControls` Date-range picker for financial reporting pages — supports year, month, and week granularity via connected selects. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `hint` | `string` | | - | - | | `onReset` | `VoidFunction` | | - | - | | `showResetButton` | `boolean` | | - | - | | `isWeekSelectVisible` | `boolean` | | - | - | | `isMonthSelectVisible` | `boolean` | | - | - | | `layout` | `"horizontal" \| "stacked"` | | - | - | | `dateRange` | `TimeframeControlsDateRange` | | - | - | | `timeframeType` | `TimeframeTypeValue \| null` | | - | - | | `onRangeChange` | `TimeframeControlsOnRangeChange` | | - | - | | `onTimeframeTypeChange` | `(type: TimeframeTypeValue) => void` | | - | - | ### `TimeframeWeekFlatContent` Flat list of selectable week items for the [**`TimeframeControls`**](/reference/ui/components/filters/#timeframecontrols) week selector. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `visibleWeeks` | `Week[]` | ✓ | - | - | ### `TimeframeWeekTreeContent` Hierarchical year → month → week tree for the [**`TimeframeControls`**](/reference/ui/components/filters/#timeframecontrols) week selector. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `timezone` | `string` | ✓ | - | - | | `selectedYear` | `number` | ✓ | - | - | | `selectedMonth` | `number` | ✓ | - | - | # Form Components (/reference/ui/components/forms) Form components for building data entry interfaces. ## Prerequisites - Complete the installation - 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 ## Core form workflow 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`. - 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 ```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) ### `Cascader` Two-panel hierarchical selector for picking a leaf value from a nested tree (categories → subcategories → leaf). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `options` | `CascaderOption[]` | ✓ | - | Hierarchical options to display in the cascader Parent options with children appear in the left panel Child options app… | | `value` | `CascaderValue \| CascaderValue[] \| undefined` | | - | Current selected value(s) - For single select: CascaderValue (e.g., ['category', 'option']) - For multiple select: Casc… | | `onChange` | `((value: CascaderValue \| CascaderValue[] \| null) => void) \| undefined` | | - | Callback when selection changes - For single select: receives CascaderValue or null - For multiple select: receives Cas… | | `multiple` | `boolean \| undefined` | | `false` | Enable multiple selection mode - true: Shows checkboxes, allows multiple selections, displays selected items as tags -… | | `placeholder` | `string \| undefined` | | `'Select...'` | Placeholder text shown in the input when no selections are made | | `disabled` | `boolean \| undefined` | | `false` | Disable the entire cascader (input and all options) | | `className` | `string \| undefined` | | - | Custom className for the root cascader element | | `dropdownClassName` | `string \| undefined` | | - | Custom className for the dropdown panels container | ### `Checkbox` [**`Checkbox`**](/reference/ui/components/forms/#checkbox) component with full customization `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `size` | `CheckboxSize \| undefined` | | `'md'` | Size variant of the checkbox | | `color` | `"success" \| "warning" \| "error" \| "primary" \| "default" \| undefined` | | `'primary'` | Color variant when checked | | `radius` | `BorderRadius \| undefined` | | `'none'` | Border radius variant | | `className` | `string \| undefined` | | - | Custom className for the root element | | `indicatorClassName` | `string \| undefined` | | - | Custom className for the indicator element | | `onCheckedChange` | `(((checked: CheckedState) => void) & ((checked: CheckedState) => void)) \| undefined` | | - | Callback when the checked state changes | ### `CurrencyToggler` [**`CurrencyToggler`**](/reference/ui/components/forms/#currencytoggler) component for switching between currencies `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `string` | ✓ | - | - | | `className` | `string \| undefined` | | - | - | | `currencies` | `(string \| CurrencyItem)[]` | ✓ | - | - | | `onChange` | `(currency: string) => void` | ✓ | - | - | ### `DatePicker` Single-date selection component built on react-day-picker with the MDK dark theme. Controlled via `selected` / `onSelect`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `selected` | `Date \| undefined` | | - | Currently selected date | | `onSelect` | `((date: Date \| undefined) => void) \| undefined` | | - | Callback when date changes | | `placeholder` | `string \| undefined` | | `"Pick a date"` | Placeholder text when no date is selected | | `dateFormat` | `string \| undefined` | | `"MM/dd/yyyy"` | Date format for display | | `disabled` | `(boolean & (Matcher \| Matcher[])) \| undefined` | | `false` | Whether the picker is disabled | | `triggerClassName` | `string \| undefined` | | - | Custom className for the trigger button | | `calendarClassName` | `string \| undefined` | | - | Custom className for the calendar | ### `DateRangePicker` Date-range selection component with preset shortcuts (last 7/14/30/90 days) and a modal interface. Controlled via `selected` / `onSelect`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `selected` | `DateRange \| undefined` | | - | Selected date range | | `onSelect` | `((range: DateRange \| undefined) => void) \| undefined` | | - | Callback when date range changes | | `placeholder` | `string \| undefined` | | `"Pick a date range"` | Placeholder text when no range is selected | | `dateFormat` | `string \| undefined` | | `"MM/dd/yyyy"` | Date format for display | | `disabled` | `(boolean & (Matcher \| Matcher[])) \| undefined` | | `false` | Whether the picker is disabled | | `showPresets` | `boolean \| undefined` | | `true` | Whether to show preset buttons | | `presets` | `PresetItem[] \| undefined` | | - | Custom preset items | | `allowFutureDates` | `boolean \| undefined` | | `false` | Whether to allow future dates | | `triggerClassName` | `string \| undefined` | | - | Custom className for the trigger button | | `calendarClassName` | `string \| undefined` | | - | Custom className for the calendar | | `modalClassName` | `string \| undefined` | | - | Custom className for the modal | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `form` | `UseFormReturn` | ✓ | - | - | | `children` | `React.ReactNode` | ✓ | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `options` | `CascaderOption[]` | ✓ | - | - | | `multiple` | `boolean \| undefined` | | - | - | | `cascaderProps` | `Omit, "onChange" \| "value" \| "options" \| "placeholder"> \| undefined` | | - | - | ### `FormCheckbox` Pre-built [**`Checkbox`**](/reference/ui/components/forms/#checkbox) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `checkboxProps` | `({ size?: CheckboxSize \| undefined; color?: ComponentColor \| undefined; radius?: BorderRadius \| undefined; className?: string \| undefined; indicatorClassName?: string \| undefined; onCheckedChange?: ((checked: CheckedState) => void) \| undefi… /* see source */` | | - | - | | `layout` | `"row" \| "column" \| undefined` | | - | - | ### `FormControl` Slot-based wrapper that injects ARIA attributes onto its child input element without adding an extra DOM wrapper. `agent-ready` ### `FormDatePicker` Pre-built [**`DatePicker`**](/reference/ui/components/forms/#datepicker) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `datePickerProps` | `Omit<{ selected?: Date \| undefined; onSelect?: ((date: Date \| undefined) => void) \| undefined; placeholder?: string \| undefined; dateFormat?: string \| undefined; disabled?: boolean \| undefined; triggerClassName?: string \| undefined; calenda… /* see source */` | | - | - | ### `FormDescription` Optional helper text displayed below the input. `agent-ready` ### `FormField` Wraps react-hook-form's Controller and provides field context to descendants. `agent-ready` ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `type` | `React.HTMLInputTypeAttribute \| undefined` | | - | - | | `variant` | `"search" \| "default" \| undefined` | | - | - | | `inputProps` | `Omit & React.RefAttributes, "type" \| "variant"> \| undefined` | | - | - | ### `FormItem` Layout wrapper for a form field. Generates a unique ID for accessibility linking. `agent-ready` ### `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` ### `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` ### `FormRadioGroup` Pre-built [**`RadioGroup`**](/reference/ui/components/forms/#radiogroup) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `options` | `FormRadioOption[]` | ✓ | - | - | | `orientation` | `"horizontal" \| "vertical" \| undefined` | | - | - | | `radioGroupProps` | `Omit<{ orientation?: "horizontal" \| "vertical" \| undefined; noGap?: boolean \| undefined; className?: string \| undefined; } & Omit, "ref"> & React.RefAttributes, "defaultV… /* see source */` | | - | - | ### `FormSelect` Pre-built [**`Select`**](/reference/ui/components/forms/#select) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `options` | `FormSelectOption[]` | ✓ | - | - | | `selectProps` | `Omit \| undefined` | | - | - | ### `FormSwitch` Pre-built [**`Switch`**](/reference/ui/components/forms/#switch) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `switchProps` | `Omit<{ size?: ComponentSize \| undefined; color?: ComponentColor \| undefined; radius?: BorderRadius \| undefined; className?: string \| undefined; thumbClassName?: string \| undefined; } & Omit, "label" \| "value" \| "placeholder" \| "onTagsChange"> \| undefined` | | - | - | ### `FormTextArea` Pre-built [**`TextArea`**](/reference/ui/components/forms/#textarea) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `textAreaProps` | `(Omit & React.RefAttributes) \| undefined` | | - | - | ### `Input` Text input with optional label, prefix/suffix slots, and a `search` variant. Forwards refs and all native `<input>` attributes. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `error` | `string \| undefined` | | - | Validation error message. When provided, displays error styling (red border) and the message below the input. | | `label` | `string \| undefined` | | - | Optional label displayed above the input | | `prefix` | `React.ReactNode` | | - | Prefix element displayed before the input (left side) | | `variant` | `"search" \| "default" \| undefined` | | `'default'` | Variant of the input - `default`: Standard text input - `search`: [**`Input`**](/reference/ui/components/forms/#input) with magnifying glass icon on the right | | `size` | `InputSize \| undefined` | | `'default'` | Size of the input - `default`: padding 10px 12px, icon 16px - `medium`: padding 6px 12px, icon 12px | | `wrapperClassName` | `string \| undefined` | | - | Custom className for the root wrapper | | `suffix` | `React.ReactNode` | | - | Suffix element displayed after the input (right side) | ### `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` ### `MultiLevelSelect` Multi-level select component with collapsible sections. `agent-ready` ### `MultiSelect` Multi-select picker built on Radix [**`Popover`**](/reference/ui/components/overlays/#popover) + [**`Checkbox`**](/reference/ui/components/forms/#checkbox). Sibling to `<[**`Select`**](/reference/ui/components/forms/#select)>` for cases where consumers need to pick more than one option (filter rows, multi-target actions, tag-style inputs). The pop… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `options` | `MultiSelectOption[]` | ✓ | - | - | | `value` | `string[] \| undefined` | | - | Controlled selected values. Omit to use `defaultValue` for uncontrolled mode. | | `defaultValue` | `string[] \| undefined` | | - | Initial values for uncontrolled mode. Ignored when `value` is provided. | | `onValueChange` | `((next: string[]) => void) \| undefined` | | - | - | | `placeholder` | `React.ReactNode` | | - | - | | `disabled` | `boolean \| undefined` | | - | - | | `size` | `MultiSelectSize \| undefined` | | - | - | | `variant` | `MultiSelectVariant \| undefined` | | - | - | | `emptyMessage` | `React.ReactNode` | | - | Rendered inside the popover when `options` is empty. | | `maxSelectedDisplay` | `number \| undefined` | | - | Max number of selected chips rendered in the trigger before collapsing the rest into a "+N more" badge. `undefined` (de… | | `className` | `string \| undefined` | | - | - | | `contentClassName` | `string \| undefined` | | - | - | | `aria-label` | `string \| undefined` | | - | Accessible label - applied to the trigger button. | | `id` | `string \| undefined` | | - | - | | `name` | `string \| undefined` | | - | - | ### `Radio` [**`Radio`**](/reference/ui/components/forms/#radio) button component (use within [**`RadioGroup`**](/reference/ui/components/forms/#radiogroup)) `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `size` | `ComponentSize \| undefined` | | `'md'` | Size variant of the radio | | `color` | `"success" \| "warning" \| "error" \| "primary" \| "default" \| undefined` | | `'default'` | Color variant when checked | | `radius` | `BorderRadius \| undefined` | | `'full'` | Border radius variant (full makes it circular) | | `className` | `string \| undefined` | | - | Custom className for the root element | | `label` | `string \| undefined` | | - | [**`Label`**](/reference/ui/components/forms/#label) text (or use children for custom content) | | `children` | `React.ReactNode` | | - | Children content (takes precedence over label) | | `indicatorClassName` | `string \| undefined` | | - | Custom className for the indicator element | ### `RadioCard` [**`RadioCard`**](/reference/ui/components/forms/#radiocard) component - button-like radio option `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `size` | `ComponentSize \| undefined` | | `'md'` | Size variant of the radio | | `color` | `"success" \| "warning" \| "error" \| "primary" \| "default" \| undefined` | | `'default'` | Color variant when checked | | `radius` | `BorderRadius \| undefined` | | `'full'` | Border radius variant (full makes it circular) | | `className` | `string \| undefined` | | - | Custom className for the root element | | `label` | `string \| undefined` | | - | [**`Label`**](/reference/ui/components/forms/#label) text (or use children for custom content) | | `children` | `React.ReactNode` | | - | Children content (takes precedence over label) | | `indicatorClassName` | `string \| undefined` | | - | Custom className for the indicator element | ### `RadioGroup` [**`RadioGroup`**](/reference/ui/components/forms/#radiogroup) component - container for [**`Radio`**](/reference/ui/components/forms/#radio) items `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `orientation` | `"horizontal" \| "vertical" \| undefined` | | `'vertical'` | Layout orientation | | `noGap` | `boolean \| undefined` | | `false` | Remove gap between radio items | | `className` | `string \| undefined` | | - | Custom className for the group | ### `Select` Dropdown select built on Radix UI. Supports `default` and `colored` variants, multiple sizes, and full keyboard navigation. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `allowClear` | `boolean \| undefined` | | `false` | Show a clear button when a value is selected | ### `Switch` [**`Switch`**](/reference/ui/components/forms/#switch) component for toggle controls with full customization `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `size` | `ComponentSize \| undefined` | | `'md'` | Size variant of the switch | | `color` | `"success" \| "warning" \| "error" \| "primary" \| "default" \| undefined` | | `'default'` | Color variant when checked | | `radius` | `BorderRadius \| undefined` | | `'none'` | Border radius variant | | `className` | `string \| undefined` | | - | Custom className for the root element | | `thumbClassName` | `string \| undefined` | | - | Custom className for the thumb element | ### `TagInput` Text input that converts comma- or Enter-separated entries into removable tag chips below the field. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `string[] \| undefined` | | - | Controlled tags (array of tag values) | | `onTagsChange` | `((tags: string[]) => void) \| undefined` | | - | Callback when tags change (add/remove) | | `onInputChange` | `((value: string) => void) \| undefined` | | - | Callback when input value changes (typing). Receives current input value. Useful for async option loading or custom fil… | | `onSubmit` | `((tags: string[]) => void) \| undefined` | | - | Callback when user presses Enter (submit). Receives current tags. Called after adding a tag from selection or typed tex… | | `options` | `TagInputOption[] \| undefined` | | - | Options to show in the dropdown when input is focused | | `placeholder` | `string \| undefined` | | - | Placeholder when input is empty | | `disabled` | `boolean \| undefined` | | - | Disabled state | | `allowCustomTags` | `boolean \| undefined` | | `true` | Whether to allow adding custom tags by typing and pressing Enter | | `filterOptions` | `((options: TagInputOption[], query: string) => TagInputOption[]) \| undefined` | | - | Filter options by input value. Receives options and query, returns filtered options. When undefined, filters by case-in… | | `variant` | `"search" \| "default" \| undefined` | | `'search'` | [**`Input`**](/reference/ui/components/forms/#input) variant - 'search' shows magnifying glass icon | | `label` | `string \| undefined` | | - | [**`Label`**](/reference/ui/components/forms/#label) for the input | | `id` | `string \| undefined` | | - | HTML id for the input | | `className` | `string \| undefined` | | - | Custom className for the root | | `wrapperClassName` | `string \| undefined` | | - | Custom className for the wrapper | | `dropdownMinHeight` | `string \| undefined` | | - | Minimum height of the dropdown (CSS value, e.g. '100px', '6rem') | | `dropdownMaxHeight` | `string \| undefined` | | `'12rem'` | Maximum height of the dropdown (CSS value, e.g. '300px', '20rem') | | `size` | `ComponentSize \| undefined` | | `'lg'` | Size of the tag input — matches [**`Select`**](/reference/ui/components/forms/#select) sizes - `sm`: 24px height - `md`: 32px height - `lg`: 40px height | | `renderDropdown` | `((props: TagInputDropdownProps) => React.ReactNode) \| undefined` | | - | Render custom dropdown content. When provided, replaces the default dropdown. Use this to apply your own styling or str… | ### `TextArea` [**`TextArea`**](/reference/ui/components/forms/#textarea) component with label support and error handling `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `error` | `string \| undefined` | | - | Validation error message. When provided, displays error styling (red border) and the message below the textarea. | | `label` | `string \| undefined` | | - | Optional label displayed above the textarea | | `wrapperClassName` | `string \| undefined` | | - | Custom className for the root wrapper | # Layout Components (/reference/ui/components/layout) Components for page structure and layout. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `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 `<[**`AccordionItem`**](/reference/ui/components/layout/#accordionitem)>`s as childre… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | ✓ | - | - | | `isRow` | `boolean \| undefined` | | - | - | | `isOpened` | `boolean \| undefined` | | - | - | | `unpadded` | `boolean \| undefined` | | - | - | | `noBorder` | `boolean \| undefined` | | - | - | | `showToggleIcon` | `boolean \| undefined` | | - | - | | `solidBackground` | `boolean \| undefined` | | - | - | | `customLabel` | `React.ReactNode` | | - | - | | `toggleIconPosition` | `TAccordionToggleIconPosition \| undefined` | | - | - | | `onValueChange` | `((value: string \| string[]) => void) \| undefined` | | - | - | ### `AccordionContent` [**`Accordion`**](/reference/ui/components/layout/#accordion) Content component (collapsible content area) `agent-ready` ### `AccordionItem` Single collapsible row within an `<[**`Accordion`**](/reference/ui/components/layout/#accordion)>`. Pass a unique `value` so Radix can track open/closed state; wrap an `<[**`AccordionTrigger`**](/reference/ui/components/layout/#accordiontrigger)>` and an `<[**`AccordionContent`**](/reference/ui/components/layout/#accordioncontent)>` as children. `agent-ready` ### `AccordionTrigger` [**`Accordion`**](/reference/ui/components/layout/#accordion) Trigger component (header/button) `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `timestamp` | `string \| undefined` | | - | - | | `showToggleIcon` | `boolean \| undefined` | | - | - | | `toggleIconPosition` | `TAccordionToggleIconPosition \| undefined` | | - | - | | `customLabel` | `React.ReactNode` | | - | - | ### `CardBody` Main content region of a `<Card>` — applies the standard inner padding and vertical rhythm. `agent-ready` ### `CardFooter` Bottom action/metadata row of a `<Card>`, typically used for buttons, timestamps, or secondary info. `agent-ready` ### `CardHeader` Top region of a `<Card>` that groups the title, optional subtitle, and an action slot. `agent-ready` ### `ChartWrapper` [**`ChartWrapper`**](/reference/ui/components/layout/#chartwrapper) - Wrapper component for charts with loading and empty states `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `children` | `React.ReactNode` | | - | Chart content to render | | `data` | `unknown[] \| Record \| undefined` | | - | Chart data object (for [**`LineChart`**](/reference/ui/components/charts/#linechart) with datasets) | | `dataset` | `unknown[] \| Record \| undefined` | | - | Chart dataset (for [**`BarChart`**](/reference/ui/components/charts/#barchart) with direct dataset) | | `isLoading` | `boolean \| undefined` | | `false` | Loading state | | `customLoader` | `React.ReactNode` | | - | Custom loader component to show when loading (overrides default spinner) | | `showNoDataPlaceholder` | `boolean \| undefined` | | `true` | Whether to show "no data" placeholder when data is empty | | `customNoDataMessage` | `React.ReactNode` | | - | Custom message or component to show when no data | | `minHeight` | `number \| undefined` | | - | Minimum height for the container (in pixels) | | `loadingMinHeight` | `number \| undefined` | | - | Minimum height for the loading skeleton (in pixels) Falls back to minHeight if not provided | | `className` | `string \| undefined` | | - | Custom className for the container | ### `Divider` Thin horizontal or vertical rule used to separate logical sections of a layout. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `orientation` | `DividerOrientation \| undefined` | | - | Line orientation | | `dashed` | `boolean \| undefined` | | - | Line style | | `dotted` | `boolean \| undefined` | | - | - | | `children` | `React.ReactNode` | | - | Text or node rendered in the middle of the divider | | `align` | `"center" \| "left" \| "right" \| undefined` | | - | Horizontal alignment of the label | | `plain` | `boolean \| undefined` | | - | Plain text style — no border around label | | `className` | `string \| undefined` | | - | Custom className | ### `LabeledCard` Card variant that pairs a tiny label above the body — used for compact stat or metadata blocks. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isDark` | `boolean` | | - | - | | `className` | `string` | | - | - | | `hasNoWrap` | `boolean` | | - | - | | `isRelative` | `boolean` | | - | - | | `isFullWidth` | `boolean` | | - | - | | `hasNoMargin` | `boolean` | | - | - | | `hasNoBorder` | `boolean` | | - | - | | `isFullHeight` | `boolean` | | - | - | | `isScrollable` | `boolean` | | - | - | | `label` | `React.ReactNode` | | - | - | | `children` | `React.ReactNode` | | - | - | | `getNavigateOptions` | `(label: string) => Partial<{ href: string; target: string; }>` | | - | - | ### `LazyTabWrapper` [**`LazyTabWrapper`**](/reference/ui/components/layout/#lazytabwrapper) - Wrapper for lazy-loaded tab components with Suspense `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `Component` | `React.ComponentType<{ data?: T \| undefined; }>` | ✓ | - | Lazy-loaded component to render | | `data` | `T \| undefined` | | - | Data to pass to the component | | `fallback` | `React.ReactNode` | | `` | Custom fallback component while loading | | `spinnerType` | `"circle" \| "square" \| undefined` | | `'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 `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `template` | `string[] \| string[][]` | ✓ | - | - | | `gap` | `string \| undefined` | | - | - | | `rowHeight` | `string \| undefined` | | - | - | | `columns` | `string \| string[] \| undefined` | | - | - | | `children` | `React.ReactNode` | ✓ | - | - | | `className` | `string \| undefined` | | - | - | ### `Tabs` [**`Tabs`**](/reference/ui/components/layout/#tabs) component for organizing content into panels `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `variant` | `TabsVariant \| undefined` | | - | - | # Media Components (/reference/ui/components/media) Components for displaying images, icons, and other media. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `ArrowIcon` Directional arrow glyph (up / down / left / right) used by sortable headers, breadcrumbs, and toggles. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean \| undefined` | | - | - | | `size` | `string \| number \| undefined` | | - | Sets both width and height | | `color` | `string \| undefined` | | - | Only affects single-color icons (default: 'currentColor') | | `children` | `undefined` | | - | - | # Miscellaneous Components (/reference/ui/components/misc) General-purpose and utility components. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `sparePart` | `SparePartDetailsRecord \| undefined` | | - | - | # Monitoring Components (/reference/ui/components/monitoring) Components for system monitoring and status displays. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `LogActivityIcon` Status icon used inside `<[**`LogRow`**](/reference/ui/components/monitoring/#logrow)>` to indicate event severity (info / warning / error / success). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `status` | `string` | ✓ | - | - | ### `LogDot` Coloured dot used to mark a log event's severity or category inline with the row. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `type` | `string` | ✓ | - | - | | `status` | `string` | ✓ | - | - | ### `LogItem` Compact log-line element rendering a single event with optional icon, timestamp, and message. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `LogData` | ✓ | - | - | | `onLogClicked` | `((uuid: string) => void) \| undefined` | | - | - | ### `LogRow` Single row of a logs feed — composes the dot/icon, timestamp, and message into one entry. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `log` | `LogData` | ✓ | - | - | | `type` | `string` | ✓ | - | - | | `style` | `React.CSSProperties \| undefined` | | - | - | | `onLogClicked` | `((uuid: string) => void) \| undefined` | | - | - | ### `LogsCard` Card wrapper for a vertically scrolling logs feed with a sticky header. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `type` | `string` | | - | - | | `label` | `string` | | - | - | | `isDark` | `boolean` | | - | - | | `isLoading` | `boolean` | | - | - | | `logsData` | `LogData[]` | | - | - | | `emptyMessage` | `string` | | - | - | | `skeletonRows` | `number` | | - | - | | `pagination` | `LogPagination` | | - | - | | `onLogClicked` | `(uuid: string) => void` | | - | - | # Navigation Components (/reference/ui/components/navigation) Components for application navigation. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `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, br… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `logo` | `React.ReactNode` | | - | Left-most slot — typically the app's brand lockup / logo. | | `start` | `React.ReactNode` | | - | Left-edge content — e.g. a sidebar collapse toggle button. | | `children` | `React.ReactNode` | | - | Middle slot — typically the dashboard's stats strip. | | `actions` | `React.ReactNode` | | - | Right-edge action cluster — e.g. alarms bell, profile menu. | | `className` | `string \| undefined` | | - | Optional class hook for the outer `<header>` element. | | `sticky` | `boolean \| undefined` | | - | Render the header sticky to the top of its scroll container. Defaults to `true`. | ### `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. P… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `items` | `BreadcrumbItem[]` | ✓ | - | - | | `showBack` | `boolean \| undefined` | | - | - | | `backLabel` | `string \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | | `itemClassName` | `string \| undefined` | | - | - | | `backClassName` | `string \| undefined` | | - | - | | `onBackClick` | `VoidFunction \| undefined` | | - | - | | `separator` | `React.ReactNode` | | - | - | ### `Pagination` [**`Pagination`**](/reference/ui/components/navigation/#pagination) component for navigating through pages `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `current` | `number \| undefined` | | - | Current active page number | | `total` | `number \| undefined` | | - | Total number of items | | `pageSize` | `number \| undefined` | | `20` | Number of items per page | | `pageSizeOptions` | `number[] \| undefined` | | `[10, 20, 50, 100]` | Page size options for the select dropdown | | `showSizeChanger` | `boolean \| undefined` | | `true` | Show page size changer | | `showTotal` | `boolean \| undefined` | | `false` | Show total count text | | `disabled` | `boolean \| undefined` | | `false` | Disable pagination | | `size` | `ComponentSize \| undefined` | | `'sm'` | Size variant | | `className` | `string \| undefined` | | - | Custom className for the root element | | `onChange` | `((page: number, pageSize: number) => void) \| undefined` | | - | Callback when page number or page size changes | | `onSizeChange` | `((current: number, size: number) => void) \| undefined` | | - | Callback when page size changes | ### `Sidebar` Application sidebar with collapsible state, persistent expansion (via `localStorage`), optional overlay mode, and item-click + active-item highlighting. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `activeId` | `string \| undefined` | ✓ | - | - | | `expanded` | `boolean \| undefined` | ✓ | - | - | | `visible` | `boolean \| undefined` | ✓ | - | - | | `overlay` | `boolean \| undefined` | ✓ | - | - | | `className` | `string \| undefined` | ✓ | - | - | | `defaultExpanded` | `boolean \| undefined` | ✓ | - | - | | `header` | `React.ReactNode` | ✓ | - | - | | `onClose` | `VoidFunction \| undefined` | ✓ | - | - | | `onExpandedChange` | `((expanded: boolean) => void) \| undefined` | ✓ | - | - | | `onItemClick` | `((item: SidebarMenuItem) => void) \| undefined` | ✓ | - | - | | `items` | `SidebarMenuItem[]` | ✓ | - | - | # Overlay Components (/reference/ui/components/overlays) Components for overlays and floating UI elements. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `Popover` [**`Popover`**](/reference/ui/components/overlays/#popover) Root - Container for a single popover `agent-ready` ### `SimplePopover` One-line convenience wrapper that pairs a trigger with floating content — no provider boilerplate. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `trigger` | `React.ReactNode` | ✓ | - | Element that triggers the popover | | `content` | `React.ReactNode` | ✓ | - | [**`Popover`**](/reference/ui/components/overlays/#popover) content | | `side` | `Position \| undefined` | | `"bottom"` | Position of the popover relative to trigger | | `align` | `FlexAlign \| undefined` | | `"center"` | Alignment of the popover | | `sideOffset` | `number \| undefined` | | `8` | Distance from the trigger in pixels | | `showArrow` | `boolean \| undefined` | | `false` | Whether to show the arrow | | `showClose` | `boolean \| undefined` | | `false` | Whether to show a close button | | `className` | `string \| undefined` | | - | Additional class for content | | `open` | `boolean \| undefined` | | - | Controlled open state | | `onOpenChange` | `((open: boolean) => void) \| undefined` | | - | Callback when open state changes | ### `SimpleTooltip` One-line convenience wrapper around the full `<[**`Tooltip`**](/reference/ui/components/overlays/#tooltip)>` primitive set. Pass `content` (the hover text) and any single React element as `children` — `<[**`SimpleTooltip`**](/reference/ui/components/overlays/#simpletooltip)>` handles the provider, trigger, p… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `content` | `React.ReactNode` | ✓ | - | [**`Tooltip`**](/reference/ui/components/overlays/#tooltip) content (string or JSX) | | `side` | `Position \| undefined` | | `"top"` | Position of the tooltip relative to trigger | | `sideOffset` | `number \| undefined` | | `8` | Distance from the trigger in pixels | | `delayDuration` | `number \| undefined` | | `200` | Delay before showing tooltip (ms) | | `showArrow` | `boolean \| undefined` | | `true` | Whether to show the arrow | | `className` | `string \| undefined` | | - | Additional class for content | | `children` | `React.ReactNode` | ✓ | - | Element that triggers the tooltip | ### `Tooltip` [**`Tooltip`**](/reference/ui/components/overlays/#tooltip) Root - Container for a single tooltip `agent-ready` # Page Components (/reference/ui/components/pages) Components for full-page layouts and page structures. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `NotFoundPage` Full-page 404 view with a heading, supporting copy, and a primary call-to-action back to safety. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `onGoHome` | `VoidFunction \| undefined` | | - | Callback fired when the "Go Home" button is clicked | | `title` | `string \| undefined` | | `"404"` | Page title | | `message` | `string \| undefined` | | `"The page you are looking for does not exist."` | Message displayed below the title | | `className` | `string \| undefined` | | - | Additional CSS class name | # Settings Components (/reference/ui/components/settings) Components for settings and configuration interfaces. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `AddUserModal` Modal form for inviting a new user — captures email, role, and optional team assignment. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `open` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `roles` | `RoleOption[]` | ✓ | - | - | | `onSubmit` | `(data: { name: string; email: string; role: string; }) => Promise` | ✓ | - | - | | `isSubmitting` | `boolean \| undefined` | | - | - | ### `ChangeConfirmationModal` Generic confirmation modal that shows a diff or summary of pending changes before applying them. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `open` | `boolean` | ✓ | - | - | | `title` | `string` | ✓ | - | - | | `onConfirm` | `VoidFunction` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `children` | `React.ReactNode` | ✓ | - | - | | `confirmText` | `string \| undefined` | | - | - | | `destructive` | `boolean \| undefined` | | - | - | ### `FeatureFlagsSettings` Settings panel listing every feature flag with per-flag enable/disable toggle and description. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `featureFlags` | `Record` | ✓ | - | - | | `isEditingEnabled` | `boolean` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `isSaving` | `boolean \| undefined` | | - | - | | `onSave` | `(flags: Record) => void` | ✓ | - | - | | `className` | `string \| undefined` | | - | - | ### `HeaderControlsSettings` Settings panel for the global app header — toggle controls, sticky behaviour, and theme defaults. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `preferences` | `HeaderPreferences` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `onToggle` | `(key: keyof HeaderPreferences, value: boolean) => void` | ✓ | - | - | | `onReset` | `VoidFunction` | ✓ | - | - | | `className` | `string \| undefined` | | - | - | ### `ImportExportSettings` Settings panel for exporting site configuration as JSON and importing a previously saved snapshot. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `onExport` | `VoidFunction` | ✓ | - | - | | `onImport` | `(data: SettingsExportData) => void` | ✓ | - | - | | `onParseFile` | `((file: File) => Promise) \| undefined` | | - | - | | `isExporting` | `boolean \| undefined` | | - | - | | `isImporting` | `boolean \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | ### `ManageUserModal` Modal for editing an existing user's role, status, or team membership. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `open` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `user` | `SettingsUser` | ✓ | - | - | | `roles` | `RoleOption[]` | ✓ | - | - | | `rolePermissions` | `Record>` | ✓ | - | - | | `permissionLabels` | `Record` | ✓ | - | - | | `onSubmit` | `(data: { id: string; name: string; email: string; role: string; }) => Promise` | ✓ | - | - | | `isSubmitting` | `boolean \| undefined` | | - | - | ### `RBACControlSettings` Settings panel listing roles and their permissions; supports editing role-permission grants. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `users` | `SettingsUser[]` | ✓ | - | - | | `roles` | `RoleOption[]` | ✓ | - | - | | `rolePermissions` | `Record>` | ✓ | - | - | | `permissionLabels` | `Record` | ✓ | - | - | | `canWrite` | `boolean` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `onCreateUser` | `(data: { name: string; email: string; role: string; }) => Promise` | ✓ | - | - | | `onUpdateUser` | `(data: { id: string; name: string; email: string; role: string; }) => Promise` | ✓ | - | - | | `onDeleteUser` | `(userId: string) => Promise` | ✓ | - | - | | `className` | `string \| undefined` | | - | - | ### `SettingsDashboard` Top-level settings landing page — composes the per-section settings cards in a single grid. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `dangerActions` | `ActionButtonProps[] \| undefined` | | - | - | | `headerControlsProps` | `HeaderControlsSettingsProps \| undefined` | | - | - | | `rbacControlProps` | `RBACControlSettingsProps \| undefined` | | - | - | | `importExportProps` | `ImportExportSettingsProps \| undefined` | | - | - | | `featureFlagsProps` | `FeatureFlagsSettingsProps \| undefined` | | - | - | | `showFeatureFlags` | `boolean \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | # Table Components (/reference/ui/components/tables) Components for displaying and interacting with tabular data. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `AlertConfirmationModal` Modal that confirms acknowledging or clearing one or more alerts before applying the change. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onOk` | `VoidFunction` | ✓ | - | - | ### `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 `HistoricalAl… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `devices` | `Device[][] \| undefined` | | - | Devices payload powering the "Current [**`Alerts`**](/reference/ui/components/tables/#alerts)" table. Mirrors the API response shape of `useGetListThingsQuery({ ... ale… | | `isCurrentAlertsLoading` | `boolean \| undefined` | | - | Loading flag for the "Current [**`Alerts`**](/reference/ui/components/tables/#alerts)" table. | | `historicalAlerts` | `Alert[] \| undefined` | | - | Pre-fetched historical alerts log entries. | | `isHistoricalAlertsLoading` | `boolean \| undefined` | | - | - | | `isHistoricalAlertsEnabled` | `boolean \| undefined` | | `false` | When true, shows the "Historical [**`Alerts`**](/reference/ui/components/tables/#alerts) Log" section. Mirrors the `alertsHistoricalLogEnabled` feature flag in the sour… | | `selectedAlertId` | `string \| undefined` | | - | Optional alert id used to focus on a single alert (deep-link from URL). | | `initialSeverity` | `string \| undefined` | | - | Initial severity selection (typically derived from `?severity=` URL param). | | `onAlertClick` | `((id?: string \| undefined, uuid?: string \| undefined) => void) \| undefined` | | - | Callback invoked when the operator clicks an alert row. Receives the device id and alert uuid. | | `dateRange` | `HistoricalAlertsRange \| undefined` | | - | Controlled date range for the historical alerts. Defaults to last 14 days. | | `onDateRangeChange` | `((range: HistoricalAlertsRange) => void) \| undefined` | | - | - | | `isSoundEnabled` | `boolean \| undefined` | | `false` | Whether sound notifications are enabled in user preferences. | | `isDemoMode` | `boolean \| undefined` | | `false` | When true, sound notifications are skipped (e.g. demo / preview). | | `typeFiltersForSite` | `CascaderOption[] \| undefined` | | - | Optional site-specific overrides for the type filter. | | `header` | `React.ReactNode` | | - | Optional header (e.g. breadcrumbs) rendered above the alerts. | | `className` | `string \| undefined` | | - | - | ### `AlertsTableTitle` Title strip for an alerts table with the section heading and an optional count badge. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `React.ReactNode` | ✓ | - | - | | `subtitle` | `React.ReactNode` | | - | - | | `className` | `string \| undefined` | | - | - | ### `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 mo… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `devices` | `Device[][] \| undefined` | | - | Raw devices (with last.alerts) used to derive current alerts from. Shape mirrors the API response from the source app. | | `isLoading` | `boolean \| undefined` | | - | - | | `localFilters` | `AlertLocalFilters` | ✓ | - | Filters controlled outside (typically by URL severity param). | | `onLocalFiltersChange` | `(filters: AlertLocalFilters) => void` | ✓ | - | - | | `filterTags` | `string[]` | ✓ | - | Search tags (controlled). Mirrors the redux `selectFilterTags` slice in the source app. | | `onFilterTagsChange` | `(tags: string[]) => void` | ✓ | - | - | | `selectedAlertId` | `string \| undefined` | | - | Optional id used to focus on a single alert (deep-link from URL). | | `onAlertClick` | `((id?: string \| undefined, uuid?: string \| undefined) => void) \| undefined` | | - | Click handler when the user opens an alert (right arrow icon in the row). | | `isSoundEnabled` | `boolean \| undefined` | | `false` | Whether sound notifications are enabled in user preferences (e.g. theme slice). | | `isDemoMode` | `boolean \| undefined` | | `false` | Skip sound entirely (e.g. in demo/preview environments). | | `typeFiltersForSite` | `CascaderOption[] \| undefined` | | - | Optional site-specific overrides for the type filter. | | `className` | `string \| undefined` | | - | - | ### `DataTable` Generic typed data table built on TanStack React Table. Supports pagination, sorting, expansion, row selection and custom column renderers. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `I[]` | ✓ | - | The data to be shown in the table. See https://tanstack.com/table/v8/docs/guide/data | | `columns` | `ColumnDef[]` | ✓ | - | The column configuration table. See https://tanstack.com/table/v8/docs/guide/column-defs | | `fullWidth` | `boolean \| undefined` | | `true` | Is table full width | | `enableRowSelection` | `boolean \| ((row: Row) => boolean) \| undefined` | | `false` | Show a checkbox column and enables selection | | `enableMultiRowSelection` | `boolean \| undefined` | | `true` | Enables selection of multiple rows | | `selections` | `RowSelectionState \| undefined` | | `undefined` | Specify the selected rows. If `undefined`, the selections are managed internally Object with the key of row ID and a bo… | | `onSelectionsChange` | `((selections: RowSelectionState) => void) \| undefined` | | - | Callback to be called when the row are selected / unselected | | `enablePagination` | `boolean \| undefined` | | `true` | Show pagination | | `bordered` | `boolean \| undefined` | | `false` | Add borders to all cells | | `pagination` | `PaginationState \| undefined` | | `undefined` | Specify the pagination params. Object of shape { pageIndex: number, pageSize: number }. If `undefined` then the paginat… | | `onPaginationChange` | `((pagination: PaginationState) => void) \| undefined` | | - | Callback to be called when the pagination params change | | `sorting` | `SortingState \| undefined` | | `undefined` | Specify the sorting params. If `undefined` then the sorting is managed internally. | | `defaultSorting` | `SortingState \| undefined` | | `[]` | Default sorting applied when the table is first mounted (uncontrolled mode). Ignored when `sorting` is provided. | | `onSortingChange` | `((sorting: SortingState) => void) \| undefined` | | - | Callback to be called when the sorting changes | | `wrapperClassName` | `string \| undefined` | | - | Classname of the wrapper element | | `contentClassName` | `string \| undefined` | | - | Classname of the content element | | `tableClassName` | `string \| undefined` | | - | Classname of the table element | | `loading` | `boolean \| undefined` | | `false` | Show a loading indicator overlay | | `enableRowExpansion` | `boolean \| undefined` | | `false` | Show a columns with a button which can expand the row | | `canRowExpand` | `((row: Row) => boolean) \| undefined` | | `false` | Callback to check if a row can be expanded | | `expandedRows` | `ExpandedState \| undefined` | | - | Specify the expanded rows If `undefined`, the expansions are managed internally Object with the key of row ID and a boo… | | `onExpandedRowsChange` | `((expandedRows: ExpandedState) => void) \| undefined` | | - | Callback to be called when the rows are expanded or collapsed | | `renderExpandedContent` | `((row: Row) => React.ReactNode) \| undefined` | | - | Render the content of the expanded row. Required when `enableRowExpansion` is `true` | | `getRowId` | `((row: I, index: number, parent?: Row \| undefined) => string) \| undefined` | | - | Get the row ID for a row. If not specified index is the default row ID. | | `onRowClick` | `((rowData: I) => void) \| undefined` | | - | Called when a body row is clicked. When set, rows become interactive (pointer cursor, `role="button"`, keyboard-activat… | ### `DeviceExplorer` Top-level device explorer: filter toolbar + searchable, sortable table of miners or cabinets. Designed to be controlled by URL state in the host app. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `deviceType` | `DeviceExplorerDeviceType` | ✓ | - | - | | `className` | `string \| undefined` | | - | - | | `selectedDevices` | `RowSelectionState \| undefined` | | - | - | | `onSelectedDevicesChange` | `((selections: RowSelectionState) => void) \| undefined` | | - | - | | `onFiltersChange` | `(value: LocalFilters) => void` | ✓ | - | - | | `filterOptions` | `DeviceExplorerFilterOption[]` | ✓ | - | - | | `searchOptions` | `DeviceExplorerSearchOption[]` | ✓ | - | - | | `searchTags` | `string[]` | ✓ | - | - | | `onSearchTagsChange` | `(tags: string[]) => void` | ✓ | - | - | | `onDeviceTypeChange` | `(type: DeviceExplorerDeviceType) => void` | ✓ | - | - | | `filters` | `LocalFilters \| undefined` | ✓ | - | - | | `onSortingChange` | `((sorting: SortingState) => void) \| undefined` | ✓ | - | - | | `data` | `Device[]` | ✓ | - | - | | `getFormattedDate` | `(date: Date) => string` | ✓ | - | - | | `renderAction` | `(device: Device) => React.ReactNode` | ✓ | - | - | | `onRowClick` | `((device: Device) => void) \| undefined` | | - | Called when a row is clicked (e.g. to open the device's detail page). | ### `EfficiencyMinerTypeView` Efficiency drilldown grouped by miner model — J/TH and uptime for each model in the fleet. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isLoading` | `boolean \| undefined` | | - | - | | `onTimeFrameChange` | `((start: Date, end: Date) => void) \| undefined` | | - | - | | `chartInput` | `ToBarChartDataInput \| undefined` | | - | - | | `isEmpty` | `boolean \| undefined` | | - | - | ### `EfficiencyMinerUnitView` Efficiency drilldown by individual miner serial — outliers and worst-performers surface here. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isLoading` | `boolean \| undefined` | | - | - | | `onTimeFrameChange` | `((start: Date, end: Date) => void) \| undefined` | | - | - | | `chartInput` | `ToBarChartDataInput \| undefined` | | - | - | | `isEmpty` | `boolean \| undefined` | | - | - | ### `EfficiencySiteView` Site-level efficiency view — site-aggregate J/TH, uptime, and capacity utilisation cards. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `log` | `MetricsEfficiencyLogEntry[] \| undefined` | | - | - | | `avgEfficiency` | `number \| null \| undefined` | | - | - | | `nominalValue` | `number \| null \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `dateRange` | `EfficiencyDateRange \| undefined` | | - | - | | `onDateRangeChange` | `((range: EfficiencyDateRange) => void) \| undefined` | | - | - | | `onReset` | `VoidFunction \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `alerts` | `Alert[] \| undefined` | | - | Pre-fetched historical alerts log entries (each with a `thing` device payload). | | `isLoading` | `boolean \| undefined` | | - | - | | `localFilters` | `AlertLocalFilters` | ✓ | - | Filters and search tags coming from the parent (typically shared with `[**`CurrentAlerts`**](/reference/ui/components/tables/#currentalerts)`). | | `filterTags` | `string[]` | ✓ | - | - | | `dateRange` | `HistoricalAlertsRange` | ✓ | - | Selected date range for the historical query (controlled). | | `onDateRangeChange` | `(range: HistoricalAlertsRange) => void` | ✓ | - | - | | `onAlertClick` | `((id?: string \| undefined, uuid?: string \| undefined) => void) \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | ### `OperationsEfficiency` Top-level operations-efficiency section of the report — composes the site/type/unit views. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `defaultTab` | `EfficiencyTabValue \| undefined` | | - | - | | `siteView` | `EfficiencySiteViewProps \| undefined` | | - | - | | `minerTypeView` | `EfficiencyMinerTypeViewProps \| undefined` | | - | - | | `minerUnitView` | `EfficiencyMinerUnitViewProps \| undefined` | | - | - | ### `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 actio… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `miners` | `ListThingsDevice[]` | ✓ | - | Miners to render in the explorer table. | | `poolConfig` | `PoolConfigEntry[]` | ✓ | - | Pool configurations powering the "Assign Pool" dropdown. | | `backButtonClick` | `VoidFunction` | ✓ | - | Called when the operator clicks the "Pool Manager" back link. | ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `poolConfig` | `PoolConfigEntry[]` | ✓ | - | Array of pool configurations to render. | | `backButtonClick` | `VoidFunction` | ✓ | - | Called when the operator clicks the "Pool Manager" back link. | ### `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,… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `batchAction` | `Partial<{ params: Partial<{ params: Partial<{ comment: string; id: string; rackId: string; info: { parentDeviceId: string \| null; }; }>[]; }>[]; }>` | ✓ | - | The repair batch action whose part changes should be displayed. | | `devices` | `Partial<{ id: string; rack: string; info: Partial<{ serialNum: string; macAddress: string; }>; }>[]` | ✓ | - | Devices referenced by the batch action, pre-fetched by the parent. | | `isLoading` | `boolean \| undefined` | | `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `filterTags` | `string[]` | ✓ | - | - | | `localFilters` | `AlertLocalFilters` | ✓ | - | - | | `onSearchTagsChange` | `(tags: string[]) => void` | ✓ | - | - | | `onLocalFiltersChange` | `(filters: AlertLocalFilters) => void` | ✓ | - | - | | `typeFiltersForSite` | `CascaderOption[] \| undefined` | | - | Site-specific overrides for the "type" filter children. If provided, the "Type" filter group will use these instead of… | | `placeholder` | `string \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | # Widget Components (/reference/ui/components/widgets) Widget components for dashboards and data displays. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components ### `AddReplaceMinerDialog` Modal for adding a new miner to a slot or swapping the existing one with a replacement unit. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `open` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `selectedSocketToReplace` | `UnknownRecord \| undefined` | | - | - | | `selectedEditSocket` | `UnknownRecord \| undefined` | | - | - | | `currentDialogFlow` | `string \| undefined` | | - | - | | `isDirectToMaintenanceMode` | `boolean \| undefined` | | - | - | | `minersType` | `string \| undefined` | | - | - | | `isContainerEmpty` | `boolean \| undefined` | | - | - | ### `BatchContainerControlsCard` Bulk-controls card that applies start/stop/mode changes to multiple selected containers at once. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isBatch` | `boolean` | | - | - | | `isCompact` | `boolean` | | - | - | | `connectedMiners` | `unknown` | | - | - | | `alarmsDataItems` | `TimelineItemData[]` | | - | - | | `onNavigate` | `(path: string) => void` | | - | - | ### `BitdeerOptions` Options panel for a Bitdeer container — exposes vendor-specific operating modes and thresholds. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `UnknownRecord \| undefined` | | - | - | ### `BitdeerPumps` Pump telemetry panel for a Bitdeer container showing per-pump RPM, flow, and alert states. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `UnknownRecord \| undefined` | | - | - | ### `BitdeerSettings` Settings tab for a Bitdeer container — vendor-specific configuration controls and limits. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `UnknownRecord \| undefined` | | - | - | ### `BitdeerTankPressureCharts` Stacked time-series of dielectric tank pressure for a Bitdeer immersion container. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `tag` | `string \| undefined` | | - | - | | `chartDataPayload` | `ChartDataPayload \| undefined` | | - | - | | `chartTitle` | `string \| undefined` | | - | - | | `dateRange` | `{ start?: number \| undefined; end?: number \| undefined; } \| undefined` | | - | - | | `data` | `UnknownRecord[] \| undefined` | | - | - | | `timeline` | `string \| undefined` | | - | - | | `fixedTimezone` | `string \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | | `showLegend` | `boolean \| undefined` | | - | - | | `showRangeSelector` | `boolean \| undefined` | | - | - | | `rangeOptions` | `{ label: string; value: string; }[] \| undefined` | | - | - | | `footer` | `React.ReactNode` | | - | - | ### `BitdeerTankTempCharts` Tank Temperature Charts for Bitdeer containers `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `tankNumber` | `string \| number \| undefined` | | - | Tank number (1 or 2) | | `tag` | `string \| undefined` | | - | - | | `chartDataPayload` | `ChartDataPayload \| undefined` | | - | - | | `chartTitle` | `string \| undefined` | | - | - | | `dateRange` | `{ start?: number \| undefined; end?: number \| undefined; } \| undefined` | | - | - | | `data` | `UnknownRecord[] \| undefined` | | - | - | | `timeline` | `string \| undefined` | | - | - | | `fixedTimezone` | `string \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | | `showLegend` | `boolean \| undefined` | | - | - | | `showRangeSelector` | `boolean \| undefined` | | - | - | | `rangeOptions` | `{ label: string; value: string; }[] \| undefined` | | - | - | | `footer` | `React.ReactNode` | | - | - | ### `BitMainBasicSettings` General settings form for a BitMain container — naming, location, and power limits. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | Container data | ### `BitMainControlsTab` Controls tab for a BitMain container exposing start/stop, mode select, and emergency actions. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device` | ✓ | - | Device data | ### `BitMainCoolingSystem` Cooling subsystem panel for a BitMain container — pumps, fans, and dry-cooler status. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | Container data | ### `BitMainHydroLiquidTemperatureCharts` Time-series charts of dielectric liquid temperature for a BitMain hydro-cooled container. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `tag` | `string \| undefined` | | - | - | | `chartDataPayload` | `ChartDataPayload \| undefined` | | - | - | | `chartTitle` | `string \| undefined` | | - | - | | `dateRange` | `{ start?: number \| undefined; end?: number \| undefined; } \| undefined` | | - | - | | `data` | `UnknownRecord[] \| undefined` | | - | - | | `timeline` | `string \| undefined` | | - | - | | `fixedTimezone` | `string \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | | `showLegend` | `boolean \| undefined` | | - | - | | `showRangeSelector` | `boolean \| undefined` | | - | - | | `rangeOptions` | `{ label: string; value: string; }[] \| undefined` | | - | - | | `footer` | `React.ReactNode` | | - | - | ### `BitMainHydroSettings` Settings form for a BitMain hydro-cooled container; flow, temperature, and pump configuration. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | Device data | ### `BitMainImmersionControlBox` Control box for a BitMain immersion container exposing tank, pump, and unit-level actions. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string \| undefined` | | - | Box title | | `leftContent` | `React.ReactNode` | | - | Content for left column | | `rightContent` | `React.ReactNode` | | - | Content for right column | | `bottomContent` | `React.ReactNode` | | - | Content for bottom row | | `secondary` | `boolean \| undefined` | | - | Secondary variant (no border) | | `className` | `string \| undefined` | | - | Custom className | ### `BitMainImmersionPumpStationControlBox` Pump-station control card for a BitMain immersion container with per-pump enable/disable. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string \| undefined` | | - | Box title | | `alarmStatus` | `boolean \| undefined` | | - | Alarm/fault status | | `ready` | `boolean \| undefined` | | - | Ready status | | `operation` | `boolean \| undefined` | | - | Operation status | | `start` | `boolean \| undefined` | | - | Start status | | `className` | `string \| undefined` | | - | Custom className | ### `BitMainImmersionSettings` Settings form for a BitMain immersion container — tank thresholds, pump curves, and limits. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | Device data | | `containerSettings` | `{ thresholds?: Record \| undefined; } \| null \| undefined` | | - | Container settings with custom thresholds | ### `BitMainImmersionSummaryBox` Summary card for a BitMain immersion-cooled container: temps, pumps, power, and overall status. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | - | | `containerSettings` | `BitMainImmersionSummaryBoxContainerSettings \| null \| undefined` | | - | - | ### `BitMainImmersionSystemStatus` Aggregated system-status card for a BitMain immersion container; rolls up subsystem health. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | Device data | ### `BitMainImmersionUnitControlBox` Per-unit control card inside a BitMain immersion container with start/stop and reset actions. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string \| undefined` | | - | Box title | | `alarmStatus` | `boolean \| undefined` | | - | Alarm/fault status | | `frequency` | `number \| undefined` | | - | Frequency value in Hz | | `isDryCooler` | `boolean \| undefined` | | - | Whether this is a dry cooler unit | | `running` | `boolean \| undefined` | | - | Whether the unit is running | | `showFrequencyInLeftColumn` | `boolean \| undefined` | | - | Show frequency in left column instead of right | | `secondary` | `boolean \| undefined` | | - | Secondary variant (no border) | | `className` | `string \| undefined` | | - | Custom className | ### `BitMainLiquidPressureCharts` Time-series charts of dielectric liquid pressure across a BitMain immersion container. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `tag` | `string \| undefined` | | - | - | | `chartDataPayload` | `ChartDataPayload \| undefined` | | - | - | | `chartTitle` | `string \| undefined` | | - | - | | `dateRange` | `{ start?: number \| undefined; end?: number \| undefined; } \| undefined` | | - | - | | `data` | `UnknownRecord[] \| undefined` | | - | - | | `timeline` | `string \| undefined` | | - | - | | `fixedTimezone` | `string \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | | `showLegend` | `boolean \| undefined` | | - | - | | `showRangeSelector` | `boolean \| undefined` | | - | - | | `rangeOptions` | `{ label: string; value: string; }[] \| undefined` | | - | - | | `footer` | `React.ReactNode` | | - | - | ### `BitMainLiquidTempCharts` Time-series charts of dielectric liquid temperature across a BitMain immersion container. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `tag` | `string \| undefined` | | - | - | | `chartDataPayload` | `ChartDataPayload \| undefined` | | - | - | | `chartTitle` | `string \| undefined` | | - | - | | `dateRange` | `{ start?: number \| undefined; end?: number \| undefined; } \| undefined` | | - | - | | `data` | `UnknownRecord[] \| undefined` | | - | - | | `timeline` | `string \| undefined` | | - | - | | `fixedTimezone` | `string \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | | `showLegend` | `boolean \| undefined` | | - | - | | `showRangeSelector` | `boolean \| undefined` | | - | - | | `rangeOptions` | `{ label: string; value: string; }[] \| undefined` | | - | - | | `footer` | `React.ReactNode` | | - | - | ### `BitMainPowerAndPositioning` Power and physical-positioning settings for a BitMain container — circuits, phases, and rack slots. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | Container data | ### `BitMainPowerCharts` Time-series charts of per-phase power, voltage, and current draw for a BitMain container. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `tag` | `string \| undefined` | | - | - | | `chartDataPayload` | `ChartDataPayload \| undefined` | | - | - | | `chartTitle` | `string \| undefined` | | - | - | | `dateRange` | `{ start?: number \| undefined; end?: number \| undefined; } \| undefined` | | - | - | | `data` | `UnknownRecord[] \| undefined` | | - | - | | `timeline` | `string \| undefined` | | - | - | | `fixedTimezone` | `string \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | | `showLegend` | `boolean \| undefined` | | - | - | | `showRangeSelector` | `boolean \| undefined` | | - | - | | `rangeOptions` | `{ label: string; value: string; }[] \| undefined` | | - | - | | `footer` | `React.ReactNode` | | - | - | ### `BitMainSupplyLiquidFlowCharts` Time-series charts of supply-side coolant flow rates for a BitMain immersion container. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `tag` | `string \| undefined` | | - | - | | `chartDataPayload` | `ChartDataPayload \| undefined` | | - | - | | `chartTitle` | `string \| undefined` | | - | - | | `dateRange` | `{ start?: number \| undefined; end?: number \| undefined; } \| undefined` | | - | - | | `data` | `UnknownRecord[] \| undefined` | | - | - | | `timeline` | `string \| undefined` | | - | - | | `fixedTimezone` | `string \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | | `showLegend` | `boolean \| undefined` | | - | - | | `showRangeSelector` | `boolean \| undefined` | | - | - | | `rangeOptions` | `{ label: string; value: string; }[] \| undefined` | | - | - | | `footer` | `React.ReactNode` | | - | - | ### `ContainerCharts` Tabbed chart panel showing per-container hashrate, power, and temperature time series. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `featureEnabled` | `boolean \| undefined` | | `true` | When false, shows an empty state (feature gate). | | `disabledMessage` | `string \| undefined` | | - | Message when `featureEnabled` is false | | `combinations` | `ContainerChartCombinationOption[]` | ✓ | - | Options for the combination selector | | `isLoadingCombinations` | `boolean \| undefined` | | - | Loading state for combination options | | `title` | `string \| undefined` | | - | Section heading | | `selectedCombination` | `string \| null \| undefined` | | - | Controlled selected combination value | | `defaultSelectedCombination` | `string \| null \| undefined` | | - | Initial selection when uncontrolled | | `onSelectedCombinationChange` | `((value: string \| null) => void) \| undefined` | | - | - | | `chartRawData` | `ChartEntry[] \| null \| undefined` | | - | Raw overview stats rows passed to chart adapters | | `isLoadingCharts` | `boolean \| undefined` | | - | - | | `getDatasetBorderColor` | `ContainerChartsDatasetBorderColorResolver \| undefined` | | - | Optional per-dataset line colors after adapters run (e.g. demo or host branding). | ### `ContainerControlsBox` Control panel for a single container — start/stop, mode select, and operator actions. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | - | | `isBatch` | `boolean \| undefined` | | - | - | | `isCompact` | `boolean \| undefined` | | - | - | | `selectedDevices` | `Device[] \| undefined` | | - | - | | `pendingSubmissions` | `PendingSubmission[] \| undefined` | | - | - | | `alarmsDataItems` | `TimelineItemData[] \| undefined` | | - | - | | `tailLogData` | `UnknownRecord[] \| undefined` | | - | - | | `powerModesLog` | `UnknownRecord \| undefined` | | - | - | | `onNavigate` | `(path: string) => void` | ✓ | - | - | ### `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 (populate… `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isLoading` | `boolean` | | - | - | | `buttonsStates` | `ButtonsStates` | | - | - | ### `ContainerFanLegend` Legend strip describing fan states and colours used by the container fans visualisation. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `index` | `number \| null \| undefined` | | - | Fan index/number to display | | `enabled` | `boolean \| undefined` | | - | Whether the fan is enabled/running | | `className` | `string \| undefined` | | - | Custom className | ### `ContainerFansCard` Card displaying the array of cooling fans in a container with live state per fan. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `fansData` | `PumpItem[] \| undefined` | | - | - | ### `ContainerSelectionDialog` Modal that lists containers and lets the operator pick one or many for a follow-up action. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `miner` | `Device \| undefined` | | - | - | | `containers` | `Device[] \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `open` | `boolean` | ✓ | - | - | | `onClose` | `(value?: boolean \| undefined) => void` | ✓ | - | - | ### `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… `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | ✓ | - | Container display name shown in the header row. | | `power` | `number \| undefined` | | - | Latest container power draw in watts (rendered in kW by the top row). | | `powerUnit` | `string \| undefined` | | - | Power unit label shown next to the reading. | | `alarms` | `Partial> \| undefined` | | - | Per-category alarm badges for the header row. | | `statsErrorMessage` | `string \| ErrorWithTimestamp[] \| null \| undefined` | | - | Raw stats error surfaced as a tooltip in place of the power reading. | | `summary` | `MinersSummaryParam[]` | ✓ | - | Pre-formatted miners-summary rows (label + display value incl. units). | | `activity` | `ContainerActivityData \| undefined` | | - | Miner-state activity counts for the embedded chart. | | `isActivityLoading` | `boolean \| undefined` | | - | Activity chart loading state. | | `isActivityError` | `boolean \| undefined` | | - | Activity chart error state. | | `activityError` | `ContainerActivityError \| undefined` | | - | Activity chart error payload. | | `isOffline` | `boolean \| undefined` | | - | Render the offline banner instead of the body. | | `errorMessage` | `string \| undefined` | | - | Container-level error message; renders an error banner instead of the body. | | `flash` | `boolean \| undefined` | | - | Critical-high alarm flash. Computed upstream (by the data hook) so the card stays presentational — never derive alarm s… | | `vendorContent` | `React.ReactNode` | | - | Optional vendor-specific content (supply-liquid / tanks / immersion / MicroBT boxes) rendered above the miners summary.… | | `onClick` | `(() => void) \| undefined` | | - | Invoked when the card is clicked (navigation is the caller's concern). | | `className` | `string \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `CostSummaryDisplayMetrics` | ✓ | - | - | ### `DryCooler` Dry-cooler subsystem panel showing inlet/outlet temperatures and fan-stage status. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `UnknownRecord \| undefined` | | - | - | ### `EnabledDisableToggle` [**`Switch`**](/reference/ui/components/forms/#switch) with confirmation that enables or disables a container, miner, or feature flag. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `unknown` | ✓ | - | - | | `tankNumber` | `string \| number` | ✓ | - | - | | `isButtonDisabled` | `boolean` | ✓ | - | - | | `isOffline` | `boolean` | ✓ | - | - | | `onToggle` | `(params: EnabledDisableToggleCbParams) => void` | ✓ | - | - | ### `ExplorerDetail` Per-type Explorer detail panel. Reads the selection the `[**`useExplorerSelection`**](/reference/ui/hooks/op-centre/#useexplorerselection)` bridge writes into `devicesStore` and composes the matching cards: `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `deviceType` | `DeviceExplorerDeviceType` | ✓ | - | The active Explorer tab — selects which per-type panel renders. | | `onNavigate` | `((path: string) => void) \| undefined` | | - | Router navigate used by alarm rows to deep-link into `/alerts/:id`. | | `isCompact` | `boolean \| undefined` | | - | Compact layout for the narrower Explorer detail column. | ### `FireStatusBox` Fire Status Box Component x Displays fire safety and environmental monitoring status. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `{ smokeDetector: string \| number; waterIngressDetector: string \| number; coolingFanStatus: string \| number; } \| undefined` | | - | Device data | ### `GaugeChartComponent` Single-needle gauge chart used inside container settings for thresholded percentage values. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `max` | `number` | ✓ | - | Maximum value for the gauge | | `value` | `number` | ✓ | - | Current value | | `label` | `string \| undefined` | | - | [**`Label`**](/reference/ui/components/forms/#label)/title for the chart | | `unit` | `string` | ✓ | - | Unit of measurement | | `chartStyle` | `React.CSSProperties \| undefined` | | - | Custom chart style | | `colors` | `string[] \| undefined` | | - | Arc colors in HEX format | | `hideText` | `boolean \| undefined` | | - | Hide the percentage text inside the chart | | `height` | `number \| undefined` | | - | Chart height in pixels | | `className` | `string \| undefined` | | - | Custom className | ### `GenericDataBox` Reusable labelled stat box used by container summary panels for one-off numeric values. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `DataItem[] \| undefined` | | - | Array of data items to display | | `fallbackValue` | `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `selectedEditSocket` | `Partial` | | - | - | | `onCancel` | `VoidFunction` | | - | - | ### `MicroBTCooling` Cooling subsystem panel for a MicroBT container — pumps, fans, and coolant flow telemetry. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | Device data | ### `MicroBTSettings` Settings form for a MicroBT container with vendor-specific operating limits. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | Device data | | `containerSettings` | `{ thresholds?: Record \| undefined; } \| null \| undefined` | | - | Container settings with custom thresholds | ### `MicroBTWidgetBox` Summary card for a MicroBT-equipped container showing pumps, fans, and operating mode. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | - | ### `MinerChip` Selectable chip representing a single miner; surfaces id, slot, and current state with click handling. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `index` | `number` | ✓ | - | - | | `frequency` | `{ current: number; }` | ✓ | - | - | | `temperature` | `{ avg: number; min: number; max: number; }` | ✓ | - | - | ### `MinerChipsCard` Card listing every miner in a container as `<[**`MinerChip`**](/reference/ui/components/widgets/#minerchip)>`s for at-a-glance selection. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `ContainerStats` | ✓ | - | - | ### `MinerControlsCard` Action card for a single miner: power, reboot, mode select, and maintenance entry points. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `buttonsStates` | `Record` | ✓ | - | - | | `isLoading` | `boolean` | ✓ | - | - | | `showPowerModeSelector` | `boolean \| undefined` | | - | - | ### `MinerInfoCard` Info card for one miner — serial, model, firmware, location, and recent activity summary. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `InfoItem[]` | | - | - | | `label` | `string` | | - | - | ### `MinerMetricCard` Single-metric card (hashrate, temperature, or power) for one miner with sparkline and delta. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `primaryStats` | `StatItem[]` | | - | Primary statistics (efficiency, hashrate, temperature, frequency, consumption) | | `secondaryStats` | `StatItem[]` | | - | Secondary statistics to display in grid | | `showSecondaryStats` | `boolean` | | - | Whether to show secondary stats section | ### `MinerPowerModeSelectionButtons` Segmented control letting an operator switch a miner between low / normal / turbo power modes. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `selectedDevices` | `Device[] \| undefined` | | - | - | | `setPowerMode` | `((devices: Device[], mode: string) => void) \| undefined` | | - | - | | `connectedMiners` | `Device[] \| undefined` | | - | - | | `powerModesLog` | `UnknownRecord \| undefined` | | - | - | | `disabled` | `boolean \| undefined` | | - | - | | `hasMargin` | `boolean \| undefined` | | - | - | ### `MinersActivityChart` Per-status miner counts (online / offline / faulted / power-mode). Renders as coloured indicator dots (`indicators`) or tinted status tiles (`tiles`). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `MinersActivityData` | | - | - | | `large` | `boolean` | | - | - | | `isLoading` | `boolean` | | - | - | | `isError` | `boolean` | | - | - | | `error` | `MinerActivityChartErrorProp \| null` | | - | - | | `showLabel` | `boolean` | | - | - | | `isDemoMode` | `boolean` | | - | - | | `variant` | `MinersActivityVariant` | | - | `indicators` (default) renders coloured dots; `tiles` renders tinted status tiles. | ### `MinersSummaryBox` Headline card summarising miner counts by state (online, offline, faulted) for one container. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `params` | `MinersSummaryParam[]` | ✓ | - | Array of label-value pairs to display in a 2-column grid | | `className` | `string \| undefined` | | - | Additional CSS class name | ### `PositionChangeDialog` Modal that moves a miner to a different rack slot, validating the destination first. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `open` | `boolean` | ✓ | - | - | | `onClose` | `(currentDialogFlow: string, isDontReset?: boolean \| undefined) => void` | ✓ | - | - | | `selectedSocketToReplace` | `UnknownRecord \| undefined` | | - | - | | `selectedEditSocket` | `UnknownRecord \| undefined` | | - | - | | `onChangePositionClicked` | `VoidFunction \| undefined` | | - | - | | `onPositionChangedSuccess` | `VoidFunction \| undefined` | | - | - | | `isContainerEmpty` | `boolean \| undefined` | | - | - | | `dialogFlow` | `string \| undefined` | | - | - | ### `PowerMeters` Per-circuit power-meter panel showing live kW, kWh, and power-factor readings. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | Device data | ### `PumpBox` Single-pump status card with RPM, flow, and fault state for one immersion-cooling pump. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `pumpTitle` | `string` | ✓ | - | - | | `pumpItem` | `PumpItem \| undefined` | | - | - | ### `RemoveMinerDialog` Confirmation modal for removing a miner from a slot with an optional reason capture. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `headDevice` | `Device \| undefined` | | - | - | | `isRemoveMinerFlow` | `boolean` | ✓ | - | - | | `onCancel` | `VoidFunction` | ✓ | - | - | ### `SecondaryStatCard` Compact stat tile rendered alongside a primary stat to provide supporting context. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `name` | `string \| undefined` | | - | Stat name/label | | `value` | `string \| number \| undefined` | | - | Stat value | | `className` | `string \| undefined` | | - | Custom className | ### `SingleStatCard` Hero stat tile rendering one big number with a label and optional delta indicator. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `name` | `string \| undefined` | | - | Stat name/label | | `subtitle` | `string \| undefined` | | - | Subtitle text | | `value` | `string \| number \| null \| undefined` | | - | Stat value | | `unit` | `string \| undefined` | | - | Unit of measurement | | `color` | `string \| undefined` | | - | Color for flash/border | | `flash` | `boolean \| undefined` | | - | Enable flash animation | | `superflash` | `boolean \| undefined` | | - | Enable superflash animation (faster) | | `variant` | `SingleStatCardVariant \| undefined` | | - | Card variant | | `row` | `boolean \| undefined` | | - | Row layout | ### `Socket` Per-socket panel showing the miner slotted into a container slot, its state, and quick actions. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `current_a` | `number \| null \| undefined` | | - | Current in amperes | | `power_w` | `number \| null \| undefined` | | - | Power in watts | | `enabled` | `boolean \| undefined` | | - | Whether socket is enabled | | `socket` | `number \| null \| undefined` | | - | [**`Socket`**](/reference/ui/components/widgets/#socket) number/index | | `selected` | `boolean \| undefined` | | - | Whether socket is selected | | `innerRef` | `React.ForwardedRef \| undefined` | | - | Forwarded ref for the container | | `miner` | `Miner \| null \| undefined` | | - | Miner data | | `heatmap` | `Heatmap \| null \| undefined` | | - | [**`Heatmap`**](/reference/ui/components/charts/#heatmap) configuration | | `isEditFlow` | `boolean \| undefined` | | - | Whether in edit flow mode | | `clickDisabled` | `boolean \| undefined` | | - | Whether click is disabled | | `cooling` | `boolean \| undefined` | | - | Cooling status | | `isEmptyPowerDashed` | `boolean \| undefined` | | - | Whether to show dashed border for empty power | | `isContainerControlSupported` | `boolean \| undefined` | | - | Whether container control is supported | | `pdu` | `Pdu \| undefined` | | - | PDU information | ### `StatsGroupCard` Card grouping multiple `<[**`SingleStatCard`**](/reference/ui/components/widgets/#singlestatcard)>`s or `<[**`SecondaryStatCard`**](/reference/ui/components/widgets/#secondarystatcard)>`s under a shared title. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `miners` | `Device[] \| DeviceData[] \| undefined` | | - | Array of miners to display stats for | | `isMinerMetrics` | `boolean \| undefined` | | - | Whether to show miner metrics card layout | ### `StatusItem` Compact labelled status pill used inside container panels for boolean or enum readings. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | Status label text | | `status` | `"warning" \| "normal" \| "fault" \| "unavailable" \| undefined` | | - | Status type | ### `SupplyLiquidBox` Status card for the dielectric supply tank — level, temperature, and pressure readings. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `Device \| undefined` | | - | - | | `containerSettings` | `SupplyLiquidBoxContainerSettings \| null \| undefined` | | - | - | ### `TankRow` Single tank-list row used inside `<[**`TanksBox`**](/reference/ui/components/widgets/#tanksbox)>` to display per-tank temperature and pressure. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string` | ✓ | - | - | | `temperature` | `number` | ✓ | - | - | | `unit` | `string` | ✓ | - | - | | `oilPumpEnabled` | `boolean` | ✓ | - | - | | `waterPumpEnabled` | `boolean` | ✓ | - | - | | `color` | `string` | ✓ | - | - | | `flash` | `boolean \| undefined` | | - | - | | `tooltip` | `string \| undefined` | | - | - | | `pressure` | `Partial<{ value: number; flash: boolean; color: string; tooltip: string; }>` | ✓ | - | - | ### `TanksBox` Card listing all tanks inside an immersion container with per-tank temperature and pressure rows. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `{ oil_pump: Tank[]; water_pump: WaterPump[]; pressure: TanksBoxPressure[]; } \| undefined` | | - | - | ### `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` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | ✓ | - | - | | `power` | `number \| undefined` | | - | - | | `unit` | `string \| undefined` | | - | - | | `statsErrorMessage` | `string \| ErrorWithTimestamp[] \| null \| undefined` | | - | - | | `alarms` | `Partial> \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | # 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](/quickstart/wire-react) ## Browse by category ### Data & State Hooks | Category | Description | Package | |----------|-------------|---------| | [Store](/reference/ui/hooks/store) | Zustand store access hooks | react-adapter | | [Auth](/reference/ui/hooks/auth) | Authentication state hooks | react-adapter | | [Permission](/reference/ui/hooks/permission) | Permission and access control hooks | react-adapter | | [Dashboard](/reference/ui/hooks/dashboard) | Dashboard data and state hooks | react-adapter, react-devkit | ### 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 | | [Forms](/reference/ui/hooks/forms) | Form state and validation hooks | react-devkit | | [Tables](/reference/ui/hooks/tables) | Table state and interaction hooks | react-devkit | | [Filters](/reference/ui/hooks/filters) | Filter state hooks | react-devkit | | [Navigation](/reference/ui/hooks/navigation) | Navigation state hooks | react-devkit | | [Feedback](/reference/ui/hooks/feedback) | Toast and notification hooks | react-devkit | | [Settings](/reference/ui/hooks/settings) | Settings and preferences hooks | react-devkit | | [Widgets](/reference/ui/hooks/widgets) | Widget state hooks | react-devkit | | [UI](/reference/ui/hooks/ui) | General UI state hooks | react-adapter | ### Feature Hooks | Category | Description | Package | |----------|-------------|---------| | [Alerts](/reference/ui/hooks/alerts) | Alert management hooks | react-adapter | | [Op Centre](/reference/ui/hooks/op-centre) | Operations centre hooks | react-adapter, react-devkit | ### Utility Hooks | Category | Description | Package | |----------|-------------|---------| | [Utility](/reference/ui/hooks/utility) | General utility hooks | react-adapter, react-devkit | | [Misc](/reference/ui/hooks/misc) | Miscellaneous hooks | react-devkit | | [Example](/reference/ui/hooks/example) | Example and demo hooks | react-adapter | ## Import pattern ```tsx // From react-adapter (state/data hooks) // From react-devkit (UI component hooks) ``` # Alert Hooks (/reference/ui/hooks/alerts) Hooks for managing alerts and notifications. ## Package `@tetherto/mdk-react-adapter` ## Hooks ### `useCurrentAlertDevices` TanStack Query hook returning the **raw** devices that currently carry one or more alerts, as the nested `ListThingsDevice[][]` the devkit `<Alerts>` / `<CurrentAlerts>` table expects (the table heads the outer array itself). ```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 Hooks (/reference/ui/hooks/auth) Hooks for authentication flows and session management. ## Package `@tetherto/mdk-react-adapter` ## Hooks ### `useAuthToken` Reads `?authToken=…` from `window.location.search`, persists it into the headless `authStore`, and strips the parameter from the URL via `history.replaceState` so the token never lingers in the address bar. ```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` Periodically calls `POST /auth/token` to refresh the bearer token. On a 401 or 500 response the session is cleared (`authStore.reset()`) and `onSessionEnded` fires so the host app can redirect to its sign-in page. ```typescript (options: UseTokenPollingOptions = {}) => void ``` # Card Hooks (/reference/ui/hooks/cards) Hooks for card component state management. ## Package `@tetherto/mdk-react-devkit` ## Hooks ### `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 r… ```typescript (onNavigate?: (path: string) => void) => UseCabinetDetailResult ``` ### `useDeviceAlarms` Shapes the active alarms of the selected devices into timeline items for the Explorer detail panel, mirroring MOS's `getContainerFormatedAlerts` → `getAlertTimelineItems` chain: `getAlarms` reads eac… ```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… ```typescript (id: string | undefined, options?: UseThingDetailOptions) => UseExplorerThingDetailResult ``` # Chart Hooks (/reference/ui/hooks/charts) Hooks for chart components and data visualization. ## Package `@tetherto/mdk-react-devkit` ## Hooks ### `useChartDataCheck` Hook to check if chart data is empty or unavailable ```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 Hooks (/reference/ui/hooks/dashboard) Hooks for dashboard data and state management. ## From `@tetherto/mdk-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 — Mining OS (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` ### `useContainerWidgetsData` Site Overview data hook: composes the container inventory + realtime miner aggregate (`useContainerWidgets`) with the per-model thresholds (`useContainerSettings`) and shapes them into th… ```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 ``` # Example Hooks (/reference/ui/hooks/example) Example hooks for learning and demonstration purposes. ## Package `@tetherto/mdk-react-adapter` ## Hooks ### `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 Hooks (/reference/ui/hooks/feedback) Hooks for user feedback and notifications. ## Package `@tetherto/mdk-react-devkit` ## Hooks ### `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 Hooks (/reference/ui/hooks/filters) Hooks for filter components and state management. ## Package `@tetherto/mdk-react-devkit` ## Hooks ### `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 Hooks (/reference/ui/hooks/forms) Hooks for form state management and validation. ## Package `@tetherto/mdk-react-devkit` ## Hooks ## Used by form primitives ## Related API - [**`FormField`**](/reference/ui/components/forms/#formfield) ### `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 Hooks (/reference/ui/hooks/misc) Miscellaneous and general-purpose hooks. ## Package `@tetherto/mdk-react-devkit` ## Hooks ### `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 `Subsid… ```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. ```typescript () => { updateExistedActions: ({ actionType, pendingSubmissions, selectedDevices, }: UpdateExistedActionsParams) => void; } ``` ### `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 `<[**`HashrateSiteView`**](/reference/ui/components/charts/#hashratesiteview)>`, `<[**`HashrateMinerTypeView`**](/reference/ui/components/charts/#hashrateminertypeview)>`… ```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 r… ```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 Hooks (/reference/ui/hooks/navigation) Hooks for navigation and routing state. ## Package `@tetherto/mdk-react-devkit` ## Hooks ### `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 Centre Hooks (/reference/ui/hooks/op-centre) Hooks for operations centre functionality and monitoring. ## From `@tetherto/mdk-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-Centre 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 Centre 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` ### `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 — contain… ```typescript ({ deviceType, rows, selected, }: UseExplorerSelectionParams) => UseExplorerSelectionResult ``` ### `useMinerDetail` Reads the miner selection the `[**`useExplorerSelection`**](/reference/ui/hooks/op-centre/#useexplorerselection)` bridge writes into `devicesStore` and shapes the head miner for the read-only cards of the miner detail panel — the info rows ({@link MinerInfoCar… ```typescript () => UseMinerDetailResult ``` # Permission Hooks (/reference/ui/hooks/permission) Hooks for checking permissions and managing access control. ## Package `@tetherto/mdk-react-adapter` ## Hooks ### `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 Hooks (/reference/ui/hooks/settings) Hooks for managing user settings and preferences. ## Package `@tetherto/mdk-react-devkit` ## Hooks ### `useHeaderControls` Read/write hook for the global header-controls store (toggles, sticky flag, theme). ```typescript () => { preferences: HeaderPreferences; isLoading: boolean; error: null; handleToggle: (key: keyof HeaderPreferences, value: boolean) => void; handleReset: () => void; } ``` # Store Hooks (/reference/ui/hooks/store) Hooks for accessing Zustand stores and managing application state. ## Package `@tetherto/mdk-react-adapter` ## Hooks ### `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 Hooks (/reference/ui/hooks/tables) Hooks for table components and data management. ## Package `@tetherto/mdk-react-devkit` ## Hooks ### `useExplorerData` Explorer list data hook: fetches the things behind one tab (`useExplorerList`) and shapes them for `<[**`DeviceExplorer`**](/reference/ui/components/tables/#deviceexplorer)>` — applying the toolbar's search + filter selections client-side and derivin… ```typescript (options: UseExplorerDataOptions) => UseExplorerDataResult ``` # UI Hooks (/reference/ui/hooks/ui) General-purpose UI state hooks. ## Package `@tetherto/mdk-react-adapter` ## Hooks ### `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… ``` ### `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; } ``` # Utility Hooks (/reference/ui/hooks/utility) General-purpose utility hooks. ## From `@tetherto/mdk-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` ### `useCostSummary` Base hook for the cost-summary reporting page (single-site mode). ```typescript ({ query, ...dateRangeOptions }?: UseCostSummaryOptions) => { queryParams: CostSummaryQueryParams | null; isLoading: boolean; error: {} | null; metrics: CostSummaryDisplayMetrics | null; costLog: readonly CostTimeSeriesEntry[]; btcPriceLog:… /* see source */ ``` # Widget Hooks (/reference/ui/hooks/widgets) Hooks for dashboard widgets and data cards. ## Package `@tetherto/mdk-react-devkit` ## Hooks ### `useContainerThresholds` Hook that reads and updates the temperature/pressure/power thresholds for a single container. ```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 ``` # @tetherto/mdk-react-devkit (/reference/ui/react/core) [The core entrypoint](/support/resources/repositories) (`@tetherto/mdk-react-devkit/core`) provides the foundational **React** UI components, utilities, and theme system for the MDK React UI Devkit. This is the `/core` subpath of the devkit package, not the framework-agnostic [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation) headless package. Mining-domain components, hooks, and settings live on the [`/foundation`](/reference/ui/react/foundation) entrypoint. Both subpaths are exported from `@tetherto/mdk-react-devkit`. ## Prerequisites - Complete the installation ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Add the dependency to your app's `package.json` ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. ## What's included ### Components Production-ready React components organized by category: | Category | Description | |----------|-------------| | [Forms](/reference/ui/react/core/components/forms) | Input and form control components | | [Overlays](/reference/ui/react/core/components/overlays) | Dialogs, popovers, tooltips, and toasts | | [Data display](/reference/ui/react/core/components/data-display) | Cards, tables, tags, and data presentation | | [Charts](/reference/ui/react/core/components/charts) | Data visualization components | | [Navigation](/reference/ui/react/core/components/navigation) | Sidebar, tabs, and breadcrumbs | | [Loading](/reference/ui/react/core/components/loading) | Spinners, loaders, and progress indicators | | [Errors](/reference/ui/react/core/components/errors) | Error boundaries, error cards, and alerts | | [Logs](/reference/ui/react/core/components/logs) | Log display components | See the [Components reference](/reference/ui/react/core/components) for the full list with demo links. ### Icons 70+ purpose-built icons for Bitcoin mining applications: - Navigation icons (Dashboard, Farms, Inventory, etc.) - Status icons (Mining, Offline, Error, etc.) - Weather icons (Sunny, Cloudy, Rainy, etc.) - Alarm icons (Temperature, Pressure, Fluid, etc.) ### Utilities Helper functions for common operations: - [`formatNumber`](/reference/app-toolkit/ui-devkit/utilities#formatnumber), [`formatHashrate`](/reference/app-toolkit/ui-devkit/utilities#formathashrate), [`formatCurrency`](/reference/app-toolkit/ui-devkit/utilities#formatcurrency): Number formatting - [`formatDate`](/reference/app-toolkit/ui-devkit/utilities#formatdate), [`formatRelativeTime`](/reference/app-toolkit/ui-devkit/utilities#formatrelativetime): Date formatting - [`cn`](/reference/app-toolkit/ui-devkit/utilities#cn): Class name merging ([clsx](https://github.com/lukeed/clsx) wrapper) - Conversion utilities for energy, hashrate, and units - Validation utilities for email, URL, and empty checks ### Theme system CSS custom properties and utilities for consistent styling: - Color tokens (primary, gray scales) - Spacing scale - Border radius scale - Font size scale - Light/dark mode support ### Types TypeScript types for type-safe development: - [`ComponentSize`](/reference/app-toolkit/ui-devkit/types#componentsize), [`ButtonVariant`](/reference/app-toolkit/ui-devkit/types#buttonvariant), [`ColorVariant`](/reference/app-toolkit/ui-devkit/types#colorvariant) - [`Status`](/reference/app-toolkit/ui-devkit/types#status), [`PaginationParams`](/reference/app-toolkit/ui-devkit/types#paginationparams), [`ApiResponse`](/reference/app-toolkit/ui-devkit/types#apiresponse) - Chart types, table types, and utility types ## Reference Detailed reference material lives in the unified [Reference section](/reference). Core (`/core`) slices are: - [Constants](/reference/app-toolkit/ui-devkit/constants#core-constants): colors, units, currency, chart configs - [Types](/reference/app-toolkit/ui-devkit/types#core-types): UI primitives, API shapes, value-unit types - [Utilities](/reference/app-toolkit/ui-devkit/utilities#core-utilities): formatting, validation, conversions, `cn` and friends ## Import examples ```tsx // Import components // Import utilities // Import types // Import icons // Import styles (required for component styling) ``` # Components (/reference/ui/react/core/components) The `@tetherto/mdk-react-devkit/core` package provides production-ready React components. All components are built with accessibility in mind and support both light and dark themes. ## Import ### Prerequisites - Complete the [installation](/quickstart/wire-react) ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Import the core styles in your app's entry point: ```tsx ``` ### Import named components Declare the components you require: ```tsx ``` ## Supported components ## Styling Components use BEM-style CSS classes (e.g., `.mdk-button`, `.mdk-card__header`) for styling consistency and easy customization. ## Class name forwarding Every component forwards `className` to its root element, so you can apply layout or override styles without ejecting. This is assumed throughout and not repeated in every props table. Components with multiple styleable parts also expose **named** hooks (for example `contentClassName`, `indicatorClassName`, `dropdownClassName`) — those *are* listed in the relevant component's props table. ## Component design principles - **Composable**: Components are designed to work together - **Accessible**: Built with ARIA attributes and keyboard navigation - **Themeable**: Support light/dark modes via CSS custom properties - **Type-safe**: Full TypeScript support with exported prop types # Chart components (/reference/ui/react/core/components/charts) Chart components for visualizing time-series data, metrics, and statistics. Built on [Chart.js](https://www.chartjs.org/) and [Lightweight Charts](https://tradingview.github.io/lightweight-charts/), supporting: - Chart types: components that render datasets (`AreaChart`, `BarChart`, `DoughnutChart`, `GaugeChart`, `LineChart`) - Domain chart wrappers: opinionated chart components with preset layouts and series config (`AverageDowntimeChart`, `ThresholdLineChart`, `OperationsEnergyCostChart`) - [Composition elements](/reference/ui/react/core/components/charts/composition): layout chrome, legends, stats rows, and chart utilities (`ChartContainer`, `ChartStatsFooter`, `DetailLegend`, `MinMaxAvg`, helpers) ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## All chart type components ## `AreaChart` Presentational Chart.js area chart (line series with fill). Data and options follow the same Chart.js model as [`LineChart`](#linechart), without a separate MDK data wrapper type. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `ChartData` | none | [Chart.js](https://www.chartjs.org/) line chart `data` (datasets typically use `fill: true` for an area look) | | `options` | Optional | `ChartOptions` | none | [Chart.js](https://www.chartjs.org/) options (merged with defaults) | | `tooltip` | Optional | `ChartTooltipConfig` | none | Custom HTML tooltip config; when set, replaces the default Chart.js tooltip | | `height` | Optional | `number` | `300` | Chart height in pixels | | `className` | Optional | `string` | none | Root class name from the host app | ### Basic usage ```tsx const data = { labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'], datasets: [ { label: 'Revenue', data: [100, 120, 115, 134, 168], fill: true, backgroundColor: 'rgba(114, 245, 158, 0.2)', borderColor: '#72F59E', }, ], } ``` ## `BarChart` The `BarChart` component renders Chart.js bar or column series. It manages: 1. **Data** (`data`): labels and datasets passed to Chart.js. 2. **Chart options** (`options`): merged with MDK defaults. 3. **Formatting** (`formatYLabel`, `formatDataLabel`, `tooltip`): axis labels, data labels, and HTML tooltips. 4. **Presentation** (`isStacked`, `isHorizontal`, `showLegend`, `legendPosition`, `legendAlign`, `showDataLabels`): layout and legend. 5. **Size** (`height`): chart height in pixels. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `ChartData` | none | [Chart.js](https://www.chartjs.org/) data object | | `options` | Optional | `ChartOptions` | none | [Chart.js](https://www.chartjs.org/) options (merged with defaults) | | `formatYLabel` | Optional | `function` | none | Format Y-axis tick labels | | `formatDataLabel` | Optional | `function` | none | Format data label values | | `tooltip` | Optional | `ChartTooltipConfig` | none | Custom HTML tooltip config | | `isStacked` | Optional | `boolean` | `false` | Stack bars on top of each other | | `isHorizontal` | Optional | `boolean` | `false` | Render bars horizontally | | `showLegend` | Optional | `boolean` | `true` | Show [Chart.js](https://www.chartjs.org/) legend | | `legendPosition` | Optional | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Legend position | | `legendAlign` | Optional | `'start' \| 'center' \| 'end'` | `'start'` | Legend alignment | | `showDataLabels` | Optional | `boolean` | `false` | Show values above bars | | `height` | Optional | `number` | `300` | Chart height in pixels | ### Basic usage ```tsx const data = { labels: ['Jan', 'Feb', 'Mar', 'Apr'], datasets: [ { label: 'Hashrate (TH/s)', data: [120, 150, 180, 200], backgroundColor: '#72F59E', }, ], } ``` ### Data from hooks Hand-built Chart.js `data` (above) is valid. When app hooks return `{ labels, series }` declarative input, convert with [`buildBarChartData`](/reference/ui/react/core/components/charts/composition#hook-shaped-bar-data) in [chart utilities](/reference/ui/react/core/components/charts/composition#chart-utilities), optionally merge per-series `datalabels`, then pass the result to `data`. ### Stacked bar chart ```tsx const data = { labels: ['Site A', 'Site B', 'Site C'], datasets: [ { label: 'Online', data: [100, 80, 120], backgroundColor: '#72F59E' }, { label: 'Offline', data: [10, 20, 5], backgroundColor: '#FF6B6B' }, ], } ``` ### Horizontal bar chart ```tsx `${value} TH/s`} /> ``` ### With data labels ```tsx `${value.toFixed(1)}%`} /> ``` ## `DoughnutChart` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `DoughnutChartDataset[]` | none | Array of `{ label, value, color? }` slices (see [data shape](#data-shape-for-doughnut-charts)) | | `unit` | Optional | `string` | `''` | Unit suffix shown in the default tooltip | | `options` | Optional | `ChartOptions` | none | [Chart.js](https://www.chartjs.org/) doughnut options (merged with defaults) | | `cutout` | Optional | `string` | `'75%'` | Inner radius cutout (doughnut ring thickness) | | `borderWidth` | Optional | `number` | `4` | Border width between segments | | `height` | Optional | `number` | `260` | Chart height in pixels | | `legendPosition` | Optional | `string` | `'top'` | Where to place the custom legend relative to the chart | | `tooltip` | Optional | `ChartTooltipConfig` | none | Custom HTML tooltip; when set, replaces the default doughnut tooltip | | `formatValue` | Optional | `(value: number) => string` | none | Formats slice values in the built-in legend and default tooltip (default: raw number) | | `className` | Optional | `string` | none | Root class name from the host app | #### Data shape for doughnut charts Pass `data` as an array of `{ label, value, color? }`. The chart maps this into Chart.js internally (`labels`, single dataset, segment colors). Omit `color` to use the default palette rotation. ### Basic usage ```tsx const data = [ { label: 'Online', value: 85, color: '#72F59E' }, { label: 'Offline', value: 10, color: '#FF6B6B' }, { label: 'Maintenance', value: 5, color: '#FFD700' }, ] ``` ## `GaugeChart` Speedometer-style presentational arc gauge for displaying a single normalized value, providing: 1. **Percent** (`percent`): fill level from `0` to `1` (values outside that range are clamped). 2. **Arc appearance** (`colors`, `arcWidth`, `nrOfLevels`): segment colors, relative thickness, and segment count. 3. **Center label** (`hideText`): percentage text in the center of the gauge (hidden when `hideText` is `true`). 4. **Accessibility** (`id`): stable id wired into SVG labels (defaults to `mdk-gauge-chart`). 5. **Layout** (`height`, `maxWidth`, `className`): container height, max width, and host root class. The `GaugeChart` is SVG-based; strokes and labels may paint past the host element’s layout bounds. For a hard edge, wrap the gauge in an element with **`overflow: hidden`**, or add vertical spacing. [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) does **not** set overflow clipping on the chart slot—it is for title, loading/empty, and footer chrome like other charts (see [Composition](/reference/ui/react/core/components/charts/composition)); it may add spacing that makes overlap less visible, but it is not a substitute for clipping when you need it. ### Import ```tsx ``` The gauge is driven by a **normalized** `percent` in the range **0–1** (for example `0.75` is 75%). It is not a `value` / `max` API, and it does not accept `label` or `unit` props (see [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) for layout notes). ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `percent` | Required | `number` | none | Fill level from `0` to `1` (clamped) | | `colors` | Optional | `string[]` | green → soft green → red (theme) | Arc segment colors as HEX strings | | `arcWidth` | Optional | `number` | `0.2` | Arc thickness as a fraction of the gauge radius (`0`–`1`) | | `nrOfLevels` | Optional | `number` | `3` | Number of colored segments on the arc | | `hideText` | Optional | `boolean` | `false` | Hide the percentage text in the center | | `id` | Optional | `string` | `'mdk-gauge-chart'` | Stable id for SVG accessibility labels | | `height` | Optional | `number` \| `string` | `200` | Container height (pixels or CSS length, e.g. `'50%'`) | | `maxWidth` | Optional | `number` | `500` | Maximum width in pixels | | `className` | Optional | `string` | none | Root class name from the host app | ### Basic usage ```tsx ``` ### In a chart card (same shell as other charts) [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) adds title, loading, and empty chrome; it does **not** apply `overflow: hidden` to the chart body. When you still see bleed next to siblings or footers, wrap `GaugeChart` in an extra element with **`overflow: hidden`**. ```tsx

``` ### Custom colors and arc ```tsx ``` ## `LineChart` The `LineChart` component renders time-series lines. It manages: 1. **Series data** (`data`): `LineChartData` with millisecond `x` values (see [data shape](#data-shape-for-line-charts)). 2. **Context** (`timeline`, `unit`): timeline identifier and unit label for tooltips. 3. **Formatting** (`yTicksFormatter`, `priceFormatter`, `customLabel`): tick and tooltip text. 4. **Presentation** (`backgroundColor`, `beginAtZero`, `showPointMarkers`, `showDateInTooltip`, `uniformDistribution`): axis and marker behavior. 5. **Size** (`height`): chart height in pixels. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `LineChartData` | none | Object with a `datasets` array (see [data shape](#data-shape-for-line-charts)) | | `timeline` | Optional | `string` | none | Timeline identifier | | `yTicksFormatter` | Optional | `function` | none | Format Y-axis ticks | | `priceFormatter` | Optional | `function` | none | Format tooltip values | | `customLabel` | Optional | `string` | none | Custom tooltip label | | `unit` | Optional | `string` | `''` | Unit label for values | | `backgroundColor` | Optional | `string` | none | Chart background color | | `beginAtZero` | Optional | `boolean` | `false` | Start Y-axis at zero | | `showPointMarkers` | Optional | `boolean` | `false` | Show data point markers | | `showDateInTooltip` | Optional | `boolean` | `false` | Show date in tooltip | | `uniformDistribution` | Optional | `boolean` | `false` | Uniform time distribution | | `height` | Optional | `number` | `240` | Chart height in pixels | #### Data shape for line charts `LineChartData` is `{ datasets: LineDataset[] }`. Each `LineDataset` has `label`, `borderColor`, optional `visible` / `borderWidth` / `extraTooltipData`, and `data: { x, y }[]` where `x` is a time value in **milliseconds** (for example from `Date.prototype.valueOf()`) and `y` is the series value (number, or `null` / `undefined` for gaps). ### Basic usage ```tsx const data = { datasets: [ { label: 'Hashrate', borderColor: '#72F59E', data: [ { x: 1704067200000, y: 150 }, { x: 1704153600000, y: 155 }, { x: 1704240000000, y: 160 }, ], }, ], } ``` ### Multiple lines ```tsx const hashrateData = [ { x: 1704067200000, y: 150 }, { x: 1704153600000, y: 155 }, ] const targetData = [ { x: 1704067200000, y: 140 }, { x: 1704153600000, y: 145 }, ] const data = { datasets: [ { label: 'Hashrate', borderColor: '#72F59E', data: hashrateData, }, { label: 'Target', borderColor: '#FFD700', data: targetData, }, ], } ``` ## `AverageDowntimeChart` Stacked bar chart showing monthly average downtime broken into **Curtailment** and **Op. Issues** series. Wraps [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) and [`BarChart`](#barchart). It manages: 1. **Data** (`data`): period labels and per-series rate arrays (values are fractions 0–1). 2. **Formatting** (`yTicksFormatter`): formats Y-axis ticks, tooltips, and optional bar data labels. 3. **Presentation** (`showDataLabels`, `title`, `unit`): bar data labels and header text. 4. **Layout** (`height`, `barWidth`): chart height and bar width in pixels. 5. **State** (`isLoading`, `emptyMessage`): loading overlay and empty-state copy. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `AverageDowntimeChartData` | none | Period labels and downtime rate arrays (see [data shape](#data-shape-for-averagedowntimechart)) | | `yTicksFormatter` | Optional | `function` | `defaultAverageDowntimeRateFormatter` | Formats Y-axis ticks, tooltips, and data labels; input values are 0–1 rates | | `showDataLabels` | Optional | `boolean` | `false` | Show formatted rate values above each bar segment | | `title` | Optional | `string` | `'Monthly Average Downtime'` | Header title | | `unit` | Optional | `string` | `'%'` | Unit label shown beneath the title | | `height` | Optional | `number` | `280` | Chart height in pixels | | `barWidth` | Optional | `number` | `38` | Bar width in pixels | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows a loading overlay | | `emptyMessage` | Optional | `string` | `'No data available'` | Copy shown in the empty state | | `className` | Optional | `string` | none | Root class name from the host app | #### Data shape for `AverageDowntimeChart` Pass `data` as an `AverageDowntimeChartData` object: | Field | Type | Description | |-------|------|-------------| | `labels` | `string[]` | Period labels (e.g. month names) | | `curtailment` | `number[]` | Curtailment downtime rates (0–1) per period | | `operationalIssues` | `number[]` | Operational issue downtime rates (0–1) per period | Both series arrays are optional; absent series are omitted from the chart. ### Basic usage ```tsx ``` ### Custom formatter `yTicksFormatter` receives raw 0–1 rate values and must return a display string. The default, `defaultAverageDowntimeRateFormatter`, multiplies by 100 and appends `%`: ```tsx AverageDowntimeChart, defaultAverageDowntimeRateFormatter, } from '@tetherto/mdk-react-devkit/core' // Override: show one decimal place `${(rate * 100).toFixed(1)}%`} showDataLabels /> ``` ### Exported helpers | Export | Role | |--------|------| | `buildAverageDowntimeBarChartData` | Converts `AverageDowntimeChartData` into Chart.js `data` | | `buildAverageDowntimeTooltip` | Builds the HTML tooltip config for the stacked bars | | `defaultAverageDowntimeRateFormatter` | Default Y-axis / label formatter (rate × 100, `%` suffix) | | `hasAverageDowntimeData` | Returns `true` when `data` has at least one non-empty series | ## `ThresholdLineChart` Time-series line chart with optional horizontal threshold bands. Wraps [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) and [`LineChart`](#linechart). It manages: 1. **Data** (`data`): one or more line series plus optional threshold lines. 2. **Formatting** (`yTicksFormatter`): formats Y-axis ticks. 3. **Presentation** (`title`, `unit`, `isTall`, `isLegendVisible`): header, height variant, and legend toggle. 4. **Layout** (`height`): explicit chart height in pixels (overrides `isTall`). 5. **State** (`emptyMessage`): empty-state copy. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `ThresholdLineChartData` | none | Series and optional thresholds (see [data shape](#data-shape-for-thresholdlinechart)) | | `yTicksFormatter` | Optional | `function` | unit-aware default | Formats Y-axis tick labels; defaults to `"${value} ${unit}"` when `unit` is set, otherwise `String(value)` | | `title` | Optional | `string` | none | Header title; rendered as `"${title} (${unit})"` when both are set | | `unit` | Optional | `string` | none | Unit appended to the title and used by the default tick formatter | | `isTall` | Optional | `boolean` | `false` | When `true`, uses a taller default height of `360px` instead of `280px` | | `isLegendVisible` | Optional | `boolean` | `true` | Show the interactive legend with dataset visibility toggles | | `height` | Optional | `number` | `280` (`360` when `isTall`) | Chart height in pixels; explicit value overrides `isTall` | | `emptyMessage` | Optional | `string` | `'No data available'` | Copy shown in the empty state | | `className` | Optional | `string` | none | Root class name from the host app | #### Data shape for `ThresholdLineChart` `ThresholdLineChartData` holds series and optional threshold lines: | Field | Type | Description | |-------|------|-------------| | `series` | `ThresholdLineChartSeries[]` | Line series to render | | `thresholds` | `ThresholdLineChartThreshold[]` | Optional horizontal reference lines | Each `ThresholdLineChartSeries`: | Field | Type | Description | |-------|------|-------------| | `label` | `string` | Series label shown in the legend | | `points` | `ThresholdLineChartPoint[]` | Data points (`{ timestamp: string \| number, value: number }`) | | `color` | `string` | Optional line color | | `fill` | `boolean` | Optional area fill below the line | Each `ThresholdLineChartThreshold`: | Field | Type | Description | |-------|------|-------------| | `label` | `string` | Label shown in the legend | | `value` | `number` | Y-axis value at which the horizontal line is drawn | | `color` | `string` | Optional line color | ### Basic usage ```tsx ``` ### Tall variant ```tsx ``` ### Exported helpers | Export | Role | |--------|------| | `toThresholdLineChartData` | Converts `ThresholdLineChartData` into `LineChartData` for the underlying `LineChart` | | `hasNonZeroData` | Returns `true` when `data` contains at least one series with a non-zero value | ## `OperationsEnergyCostChart` Doughnut chart comparing operational costs against energy costs in USD per MWh. Wraps [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) and [`DoughnutChart`](#doughnutchart). It manages: 1. **Data** (`data`): operational and energy cost values in USD. 2. **Presentation** (`title`, `unit`): header text and unit label. 3. **Layout** (`height`): chart height in pixels. 4. **State** (`isLoading`, `emptyMessage`): loading overlay and empty-state copy. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `OperationsEnergyCostChartData` | none | Cost values in USD (see [data shape](#data-shape-for-operationsenergycostchart)) | | `title` | Optional | `string` | `'Operations vs Energy Cost'` | Header title | | `unit` | Optional | `string` | `'$/MWh'` | Unit label shown beneath the title | | `height` | Optional | `number` | `200` | Chart height in pixels | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows a loading overlay | | `emptyMessage` | Optional | `string` | `'No data available'` | Copy shown in the empty state | | `className` | Optional | `string` | none | Root class name from the host app | #### Data shape for `OperationsEnergyCostChart` `OperationsEnergyCostChartData` has two optional numeric fields: | Field | Type | Description | |-------|------|-------------| | `operationalCostsUSD` | `number` | Operational costs in USD | | `energyCostsUSD` | `number` | Energy costs in USD | Both fields are optional. Slices with a zero or absent value are omitted from the doughnut. ### Basic usage ```tsx ``` ### Exported helpers | Export | Role | |--------|------| | `buildOperationsEnergyCostSlices` | Converts `OperationsEnergyCostChartData` into `DoughnutChartDataset[]` slices, omitting zero-value entries | | `buildOperationsEnergyCostTooltip` | Builds the HTML tooltip config with two-decimal formatting | | `hasOperationsEnergyCostData` | Returns `true` when at least one cost field is a positive number | # Chart composition (/reference/ui/react/core/components/charts/composition) Compose chart types from [Chart components](/reference/ui/react/core/components) with wrappers and helpers. `ChartContainer` adds title, loading, and empty states; `ChartStatsFooter` and `DetailLegend` add summary rows and rich legends (for example [`LineChartCard`](/reference/ui/react/foundation/dashboard/charts#linechartcard)). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## Components ## `ChartContainer` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `children` | Required | `ReactNode` | none | Chart body (for example a `BarChart` or `LineChart`) | | `title` | Optional | `string` | none | Title text | | `titleExtra` | Optional | `ReactNode` | none | Node rendered immediately after the title text (e.g. an info tooltip); only shown when `title` is set and `header` is not | | `header` | Optional | `ReactNode` | none | Custom header node | | `headerAction` | Optional | `ReactNode` | none | Action rendered on the right side of the header row (e.g. an expand toggle); sits alongside the range selector when both are present | | `legendData` | Optional | `LegendItem[]` | none | Legend entries rendered in the container chrome | | `highlightedValue` | Optional | `object` | none | Highlighted metric (`value`, `unit`, `className`, `style`); highlight chrome renders only when this prop is set and the chart body is visible (not `loading` / not `empty`) | | `rangeSelector` | Optional | `object` | none | Range selector props (`options`, `value`, `onChange`, `className`, `style`, `buttonClassName`) | | `loading` | Optional | `boolean` | none | When `true`, shows a centered `Loader` overlay over the chart area | | `empty` | Optional | `boolean` | none | When `true`, shows empty state | | `emptyMessage` | Optional | `string` | `'No data available'` | Copy shown in the empty overlay when `empty` is `true` and `loading` is not `true` | | `minMaxAvg` | Optional | `object` | none | Min / max / avg strings for the summary row | | `timeRange` | Optional | `string` | none | Time range label | | `footer` | Optional | `ReactNode` | none | Footer slot | | `footerClassName` | Optional | `string` | none | Class name on the footer wrapper | | `onToggleDataset` | Optional | `function` | none | Called with dataset index when legend toggles visibility | | `className` | Optional | `string` | none | Root class name from the host app | ### Basic usage ```tsx ``` ## `ChartStatsFooter` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `minMaxAvg` | Optional | `object` | none | Min, max, and average strings shown in the primary row when provided | | `stats` | Optional | `ChartStatsFooterItem[]` | none | Additional stat rows (`label`, `value`) in a columnar grid | | `statsPerColumn` | Optional | `number` | `1` | Number of stat items per column when `stats` is set | | `secondaryLabel` | Optional | `object` | none | Secondary block with `title` and `value` when provided | | `className` | Optional | `string` | none | Root class name from the host app | The component renders **nothing** when `minMaxAvg`, `stats`, and `secondaryLabel` are all absent or empty. ### Basic usage ```tsx ``` ## `DetailLegend` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `items` | Required | `DetailLegendItem[]` | none | Legend rows (`label`, `color`, optional `icon`, `currentValue`, `percentChange`, `hidden`) | | `onToggle` | Optional | `function` | none | Called with `label` and index when a row is toggled | | `className` | Optional | `string` | none | Root class name from the host app | ### Basic usage ```tsx ``` ## `MinMaxAvg` Compact summary row displaying min, max, and average values with consistent MDK label and value styling. Rendered automatically by [`ChartContainer`](#chartcontainer) when its `minMaxAvg` prop is set, and by [`ChartStatsFooter`](#chartstatsfooter) in the same way. Use it directly when you need the summary row outside of a `ChartContainer` or `ChartStatsFooter`. The component renders **nothing** when all three values are absent or empty strings. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `min` | Optional | `string` | none | Minimum value label (for example `'65 TH/s'`) | | `max` | Optional | `string` | none | Maximum value label | | `avg` | Optional | `string` | none | Average value label | | `className` | Optional | `string` | none | Root class name from the host app | ### `MinMaxAvgValues` type ```tsx type MinMaxAvgValues = Partial<{ min: string max: string avg: string }> ``` `MinMaxAvgValues` is the shape accepted by the `minMaxAvg` prop on both `ChartContainer` and `ChartStatsFooter`. ### Basic usage ```tsx ``` ### Usage with `ChartContainer` ```tsx const stats = computeStats(values) ``` ## Chart utilities Pure functions for building Chart.js data and options. Import from the package root alongside components. ```tsx defaultChartOptions, defaultChartColors, buildBarChartData, buildBarChartOptions, buildChartTooltip, computeStats, } from '@tetherto/mdk-react-devkit/core' ``` | Export | Role | |--------|------| | `defaultChartOptions` | Shared Chart.js defaults used by MDK chart components | | `defaultChartColors` | Default dataset color palette | | `buildBarChartData` | Map MDK bar input into Chart.js `data` | | `buildBarChartOptions` | Build bar chart options (stacking, axes, formatters) | | `buildChartTooltip` | HTML tooltip config for Chart.js | | `computeStats` | Min, max, and average for a numeric array | Types `BarChartInput`, `BarChartSeries`, `BarChartLine`, and `BarChartConstant` are exported from the same package for hook-shaped bar data. ### Hook-shaped bar data App and reporting hooks often return declarative bar input instead of Chart.js `data`. `buildBarChartData` converts that shape into `{ labels, datasets }` for [`BarChart`](/reference/ui/react/core/components/charts#barchart). The pipeline: 1. **Input** (`BarChartInput`): optional `labels`, required `series`, optional `lines` and `constants` for mixed bar/line overlays. 2. **Build** (`buildBarChartData`): returns Chart.js `data` with MDK gradient styling and layout defaults (`barWidth`, `categoryPercentage`, `barPercentage` are optional on the input). 3. **Data labels** (optional): per-series overrides on the input (`formatter`, `anchor`, `align`, `offset`, `font`, `padding`, `display`, `clamp`, `clip`) map to each built dataset’s Chart.js `datalabels` by series index. 4. **Render** (``): pass the built object to the component; pair with `buildBarChartOptions` when you need stacking, axes, or formatters. `BarChartInput` shape | Field | Status | Type | Description | |-------|--------|------|-------------| | `series` | Required | `BarChartSeries[]` | Bar datasets (`label`, `values`, optional `color`, `stack`, `gradient`, bar layout props) | | `labels` | Optional | `string[]` | Category labels; omitted labels are derived from series `values` keys or indices | | `lines` | Optional | `BarChartLine[]` | Line overlays on the same chart | | `constants` | Optional | `BarChartConstant[]` | Horizontal reference lines | Each `BarChartSeries` uses `values` as either `number[]` (positional) or `Record` (keyed by category label). #### Example Hook output to `BarChart` example: ```tsx BarChart, buildBarChartData, ChartContainer, } from '@tetherto/mdk-react-devkit/core' // Typical shape returned by app/reporting data hooks const hookOutput = { labels: ['Q1', 'Q2', 'Q3'], series: [ { label: 'Revenue', values: [4.2, 3.8, 5.1], color: '#72F59E', dataLabels: { formatter: (v: number) => `${v.toFixed(1)}M`, anchor: 'end', align: 'top', }, }, { label: 'OpEx', values: [1.8, 2.0, 1.6], color: '#FFD700', }, ], } const cleanSeries = hookOutput.series.map(({ dataLabels: _dl, ...s }) => s) const base = buildBarChartData({ labels: hookOutput.labels, series: cleanSeries }) const chartData = { labels: base.labels, datasets: base.datasets.map((dataset, i) => { const overrides = hookOutput.series[i]?.dataLabels return overrides ? { ...dataset, datalabels: overrides } : dataset }), } const isEmpty = !hookOutput.series.length || hookOutput.series.every((s) => { const vals = Array.isArray(s.values) ? s.values : Object.values(s.values) return !vals.length || vals.every((v) => v === 0) }) ``` #### Empty and all-zero series Treat bar data as empty when any of the following is true: - `series` is missing or has length `0` - Every series has empty `values` (array or record) - Every numeric value across all series is `0` Prefer `ChartContainer` `empty` or a placeholder instead of rendering a flat chart. After building Chart.js `data`, you can also use [`useChartDataCheck`](/reference/app-toolkit/hooks/components#usechartdatacheck) from `@tetherto/mdk-react-devkit/foundation` with `{ data: chartData }`. # Data display (/reference/ui/react/core/components/data-display) Components for displaying data in cards, tables, badges, tags, and other visual formats. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## `DataTable` ### Import ```tsx // Types for column definitions DataTableColumnDef, DataTableSortingState, DataTablePaginationState, DataTableRowSelectionState, } from '@tetherto/mdk-react-devkit/core' ``` ### Basic usage ```tsx type Miner = { id: string name: string hashrate: number status: string } const columns: DataTableColumnDef[] = [ { accessorKey: 'name', header: 'Name', }, { accessorKey: 'hashrate', header: 'Hashrate', cell: ({ row }) => `${row.original.hashrate} TH/s`, }, { accessorKey: 'status', header: 'Status', }, ] function MinersTable() { return } ``` ### With sorting and pagination ```tsx const [sorting, setSorting] = useState([]) const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10, }) ``` ### With row selection ```tsx const [rowSelection, setRowSelection] = useState({}) ``` ### Styling - `.mdk-data-table`: Root container - `.mdk-data-table__header`: Header row - `.mdk-data-table__body`: Table body - `.mdk-data-table__row`: Data row - `.mdk-data-table__cell`: Table cell ## `Card` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `className` | Optional | `string` | none | Additional CSS class | | `onClick` | Optional | `function` | none | Click handler (adds clickable styling) | | `children` | Optional | `ReactNode` | none | Card content | ### Basic usage ```tsx Title Content goes here Actions ``` Default children are automatically wrapped in the body slot: ```tsx Title This content goes to the body automatically ``` ### Clickable card ```tsx navigate('/details')}> Click me Navigates on click ``` ### Styling - `.mdk-card`: Root container - `.mdk-card--clickable`: Applied when `onClick` is provided - `.mdk-card__header`: Header slot - `.mdk-card__body`: Body slot - `.mdk-card__footer`: Footer slot ## `LabeledCard` A generic card container with a header label, an optional navigation link on the label, and a set of layout modifiers. Useful for compact stat or metadata blocks. ### Import ```tsx ``` ### Props All props are optional. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `ReactNode` | none | Header content shown above the card body | | `children` | Optional | `ReactNode` | none | Card body content | | `getNavigateOptions` | Optional | `(label: string) => { href?: string; target?: string }` | none | Returns a link `href`/`target` for the label; only activates when `label` is a plain string | | `isDark` | Optional | `boolean` | `false` | Applies a dark background modifier | | `isFullWidth` | Optional | `boolean` | `false` | Stretches the card to full container width | | `isFullHeight` | Optional | `boolean` | `false` | Stretches the card to full container height | | `isRelative` | Optional | `boolean` | `false` | Sets `position: relative` on the container | | `isScrollable` | Optional | `boolean` | `false` | Enables vertical scroll on the card body | | `hasNoWrap` | Optional | `boolean` | `false` | Prevents content from wrapping | | `hasNoMargin` | Optional | `boolean` | `false` | Removes default margin | | `hasNoBorder` | Optional | `boolean` | `false` | Removes the card border | | `className` | Optional | `string` | none | Additional class for the root element | ### Basic usage ```tsx
Content goes here.
``` ### With a navigation link on the label ```tsx ({ href: '/miners?filter=error' })} > ``` When `label` is the string `'Miners with error'`, an informational tooltip is added automatically, explaining that minor errors not affecting hashrate are excluded. ## `Accordion` ### Import ```tsx Accordion, AccordionItem, AccordionTrigger, AccordionContent, } from '@tetherto/mdk-react-devkit/core' ``` ### `Accordion` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `title` | Optional | `string` | `''` | Accordion header title | | `isOpened` | Optional | `boolean` | `false` | Initially expanded | | `isRow` | Optional | `boolean` | `false` | Row layout for content | | `unpadded` | Optional | `boolean` | `false` | Remove content padding | | `noBorder` | Optional | `boolean` | `false` | Remove trigger border | | `solidBackground` | Optional | `boolean` | `false` | Solid background color | | `showToggleIcon` | Optional | `boolean` | `true` | Show expand/collapse icon | | `toggleIconPosition` | Optional | `'left' \| 'right'` | `'left'` | Icon position | | `customLabel` | Optional | `ReactNode` | none | Custom label next to title | | `onValueChange` | Optional | `function` | none | Callback when state changes | ### Basic usage ```tsx
This content can be expanded or collapsed.
``` ### With custom label ```tsx Active} showToggleIcon={false} >
All systems operational.
``` ### Multiple items ```tsx Section 1 Content 1 Section 2 Content 2 ``` ### Styling - `.mdk-accordion`: Root container - `.mdk-accordion--solid-background`: Solid background variant - `.mdk-accordion__item`: Individual item - `.mdk-accordion__trigger`: Clickable header - `.mdk-accordion__content`: Collapsible content area ## `Badge` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `count` | Optional | `number` | `0` | Number to display | | `overflowCount` | Optional | `number` | `99` | Max count before showing "99+" | | `showZero` | Optional | `boolean` | `false` | Show badge when count is 0 | | `dot` | Optional | `boolean` | `false` | Show as dot instead of number | | `text` | Optional | `string` | none | Custom text content | | `color` | Optional | [`ColorVariant`](/reference/app-toolkit/ui-devkit/types#colorvariant) | `'primary'` | Badge color | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'md'` | Badge size | | `status` | Optional | `'success' \| 'processing' \| 'error' \| 'warning' \| 'default'` | none | Status variant | | `square` | Optional | `boolean` | `false` | Square badge (no border-radius) | | `offset` | Optional | `[number, number]` | `[0, 0]` | Position offset [x, y] | ### Basic usage ```tsx // Number badge on content // Overflow // Shows "99+" ``` ### Dot badge ```tsx ``` ### Status badge ```tsx ``` ### Standalone badge ```tsx ``` ### Styling - `.mdk-badge`: Badge element - `.mdk-badge--{color}`: Color variant - `.mdk-badge--{size}`: Size variant - `.mdk-badge--dot`: Dot variant - `.mdk-badge--status`: Status variant - `.mdk-badge-wrapper`: Wrapper when wrapping content ## `Pagination` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `current` | Optional | `number` | `1` | Current page number | | `total` | Optional | `number` | `0` | Total number of items | | `pageSize` | Optional | `number` | `20` | Items per page | | `pageSizeOptions` | Optional | `number[]` | `[10, 20, 50, 100]` | Page size options | | `showSizeChanger` | Optional | `boolean` | `true` | Show page size dropdown | | `showTotal` | Optional | `boolean` | `false` | Show total count text | | `disabled` | Optional | `boolean` | `false` | Disable pagination | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'sm'` | Size variant | | `onChange` | Optional | `(page: number, pageSize: number) => void` | none | Callback when the page number or page size changes | | `onSizeChange` | Optional | `(current: number, size: number) => void` | none | Callback when the page size changes | ### Basic usage ```tsx const [page, setPage] = useState(1) const [pageSize, setPageSize] = useState(20) { setPage(newPage) setPageSize(newSize) }} /> ``` ### With total display ```tsx // Shows "1-20 of 100" ``` ### Styling - `.mdk-pagination`: Root container - `.mdk-pagination__pages`: Page buttons container - `.mdk-pagination__button`: Navigation button - `.mdk-pagination__button--active`: Active page - `.mdk-pagination__total`: Total count text - `.mdk-pagination__size-changer`: Page size select ## `Tag` ### Import ```tsx ``` ### Basic usage ```tsx Default Tag Primary Success handleRemove()}>Removable ``` ## `Avatar` ### Import ```tsx ``` ### Basic usage ```tsx JD ``` ## `SkeletonBlock` ### Import ```tsx ``` ### Basic usage ```tsx // Text skeleton // Circle skeleton // Card skeleton ``` ## `EmptyState` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `description` | Optional | `ReactNode` | none | **Required.** Description text | | `image` | Optional | `'default' \| 'simple' \| ReactNode` | `'default'` | Image/icon to display | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant | ### Basic usage ```tsx ``` ### Custom image ```tsx } /> ``` ### Styling - `.mdk-empty-state`: Root container - `.mdk-empty-state--{size}`: Size variant - `.mdk-empty-state__image`: Image container - `.mdk-empty-state__description`: Description text ## `BtcAveragePrice` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `price` | Optional | `number \| null` | none | BTC price in USD; formatted with grouping and no decimal places. Shows `-` when `null`, `undefined`, non-finite, or negative | | `label` | Optional | `string` | `'BTC Average Price'` | Label shown before the price | ### Basic usage ```tsx ``` ## `Typography` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `variant` | Optional | `'heading1' \| 'heading2' \| 'heading3' \| 'body' \| 'secondary' \| 'caption'` | none | Typography variant | | `size` | Optional | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'` | none | Text size | | `weight` | Optional | `'light' \| 'normal' \| 'medium' \| 'semibold' \| 'bold'` | none | Font weight | | `align` | Optional | `TextAlign` | none | Text alignment | | `color` | Optional | `'default' \| 'muted' \| 'primary' \| 'success' \| 'warning' \| 'error'` | none | Text color variant | | `truncate` | Optional | `boolean` | `false` | Truncate text with ellipsis | | `className` | Optional | `string` | none | Custom class name | ### Basic usage ```tsx Operations dashboard Sites Primary site operations are running within expected parameters. Last refreshed 12 seconds ago. Updated 2 minutes ago Site #1 ``` ## `Indicator` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `color` | Optional | `'gray' \| 'slate' \| 'red' \| 'amber' \| 'yellow' \| 'green' \| 'blue' \| 'purple'` | none | Color variant of the indicator dot | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | none | Size variant of the indicator | | `vertical` | Optional | `boolean` | `false` | When `true`, adds extra spacing between child elements and stacks them vertically | | `onClick` | Optional | `function` | none | Click handler | | `children` | Optional | `ReactNode` | none | Label content (text, icons, or multiple elements) | | `className` | Optional | `string` | none | Custom class name | ### Basic usage ```tsx Online Offline Maintenance Running Running 142 ``` ## `CurrencyToggler` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `currencies` | Required | `(string \| CurrencyItem)[]` | none | Currencies to toggle between, as codes or `CurrencyItem` objects | | `value` | Required | `string` | none | Currently selected currency code | | `onChange` | Required | `(currency: string) => void` | none | Called with the newly selected currency code | | `className` | Optional | `string` | none | Custom class name for the root element | ### Basic usage ```tsx ``` ## `ListViewFilter` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `CascaderOption[]` | none | Cascader options for filtering | | `onChange` | Required | `(selections: CascaderValue[]) => void` | none | Callback when filters change | | `localFilters` | Optional | `LocalFilters` | none | Current filter values as key-value pairs (e.g. `{ status: ['active'] }`) | | `filterKey` | Optional | `string` | none | Key to force re-mounting the Cascader when filters change (resets its internal state) | | `className` | Optional | `string` | none | Custom class name for the filter button | ### Basic usage ```tsx const FILTER_OPTIONS = [ { value: 'type', label: 'Type', children: [ { value: 'Antminer S19XP', label: 'Antminer S19XP' }, { value: 'Avalon A1346', label: 'Avalon A1346' }, ], }, { value: 'status', label: 'Status', children: [ { value: 'active', label: 'Active' }, { value: 'offline', label: 'Offline' }, ], }, ] const [filters, setFilters] = useState({}) setFilters(selectionToFilters(selections))} /> ``` ## `Mosaic` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `template` | Required | `string[] \| string[][]` | none | Grid layout template — area names per row that map child `MosaicItem`s to grid regions | | `children` | Required | `ReactNode` | none | `MosaicItem` elements placed into the named grid areas | | `columns` | Optional | `string \| string[]` | none | Column track sizes (e.g. `'1fr 2fr 1fr'`); defaults to equal columns derived from the template | | `gap` | Optional | `string` | `'12px'` | Gap between grid cells (any CSS length) | | `rowHeight` | Optional | `string` | `'auto'` | Height applied to each grid row (any CSS length) | | `className` | Optional | `string` | none | Custom class name for the root element | ### Basic usage ```tsx Hashrate Active miners Power usage ``` # Errors (/reference/ui/react/core/components/errors) Components for displaying errors, alerts, and handling error states. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## `CoreAlert` ### Import ```tsx ``` The component is authored as `Alert` in `@tetherto/mdk-react-devkit/core` but re-exported as `CoreAlert` at the package barrel to avoid collisions with other `Alert` primitives (for example Radix `AlertDialog`). ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `type` | Optional | `'success' \| 'info' \| 'warning' \| 'error'` | `'info'` | Alert type | | `title` | Optional | `ReactNode` | none | Main message | | `description` | Optional | `ReactNode` | none | Additional description | | `showIcon` | Optional | `boolean` | `false` | Show type icon | | `icon` | Optional | `ReactNode` | none | Custom icon | | `closable` | Optional | `boolean` | `false` | Show close button | | `onClose` | Optional | `function` | none | Close callback | | `banner` | Optional | `boolean` | `false` | Full-width banner style | | `action` | Optional | `ReactNode` | none | Action element | ### Basic usage ```tsx ``` ### With action ```tsx View Details} /> ``` ### Banner style ```tsx ``` ### Styling - `.mdk-alert`: Root container - `.mdk-alert--{type}`: Type variant - `.mdk-alert--banner`: Banner variant - `.mdk-alert__icon`: Icon container - `.mdk-alert__content`: Content wrapper - `.mdk-alert__title`: Title text - `.mdk-alert__description`: Description text - `.mdk-alert__action`: Action container - `.mdk-alert__close`: Close button ## `ErrorBoundary` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `fallback` | Optional | `ReactNode` | none | Custom fallback UI | | `componentName` | Optional | `string` | none | Component name for error display | | `onError` | Optional | `function` | none | Error callback | | `children` | Required | `ReactNode` | none | Children to wrap | ### Basic usage ```tsx Something went wrong}> ``` ### With component name ```tsx console.error(error)} > ``` ### Higher-order component ```tsx const SafeChart = withErrorBoundary( Chart, 'Chart', (error) => logError(error) ) ``` #### Styling - `.mdk-error-boundary`: Root container - `.mdk-error-boundary__title`: Error title - `.mdk-error-boundary__message`: Error message - `.mdk-error-boundary__details`: Expandable details - `.mdk-error-boundary__stack`: Stack trace ## `ErrorCard` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `error` | Required | `string` | none | Error message (supports `\n` for line breaks) | | `title` | Optional | `string` | `'Errors'` | Title displayed above the error message | | `variant` | Optional | `'card' \| 'inline'` | `'card'` | Display variant — `card` shows a bordered container, `inline` shows flat text | | `className` | Optional | `string` | none | Additional CSS class | ### Basic usage ```tsx ``` ### Styling - `.mdk-error-card`: Root container - `.mdk-error-card--{variant}`: Variant modifier (`card` / `inline`) - `.mdk-error-card__title`: Title text - `.mdk-error-card__message`: Message text ## `NotFoundPage` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `onGoHome` | Optional | `VoidFunction` | none | Callback fired when the "Go Home" button is clicked (button only renders when provided) | | `title` | Optional | `string` | none | Page title | | `message` | Optional | `string` | none | Message displayed below the title | | `className` | Optional | `string` | none | Additional CSS class | ### Basic usage ```tsx navigate('/')} /> navigate('/')} /> ``` ### Styling - `.mdk-not-found-page`: Root container - `.mdk-not-found-page__title`: Title text - `.mdk-not-found-page__message`: Message text - `.mdk-not-found-page__button`: Go Home button # Form components (/reference/ui/react/core/components/forms) Form components handle user input and form submission. All components are built with accessibility in mind and support keyboard navigation. The category splits into three groups: - [Controls](#controls): raw inputs you can drop in standalone or compose inside `
` - [Composition](/reference/ui/react/core/components/forms/composition): the `` provider and the low-level building blocks (`FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`) - [Prebuilt fields](/reference/ui/react/core/components/forms/fields): one-tag wrappers that bind a control to React hook form ## Prerequisites Before using these components, complete the [@tetherto/mdk-react-devkit installation](/reference/ui/react/core#prerequisites). ## Controls Standalone form controls. Manage `value` and `onChange`, or compose them inside [``](/reference/ui/react/core/components/forms/composition#form) with [`FormField`](/reference/ui/react/core/components/forms/composition#formfield). ### `ActionButton` Triggers an action after **confirmation** in either an inline **popover** (default) or a modal **dialog**. Set **variant** so the trigger [`Button`](#button) matches severity (for example `danger` for destructive flows). After the user confirms, run your side effects there. Consider showing feedback with [`Toast`](/reference/ui/react/core/components/overlays#toast) and **`Toaster`** from the same Toast setup as in [`overlays`](/reference/ui/react/core/components/overlays). This is the pattern the [demo app(../quickstart) applies. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `string` | none | Trigger button label | | `variant` | Optional | `'primary' \| 'secondary' \| 'danger'` | `'secondary'` | Visual variant of the trigger [`Button`](#button) | | `loading` | Optional | `boolean` | `false` | Loading state on the trigger | | `disabled` | Optional | `boolean` | `false` | Disable the trigger | | `className` | Optional | `string` | none | Class on the trigger | | `mode` | Optional | `'popover' \| 'dialog'` | `'popover'` | **`popover`**: confirmation UI in an anchored popover. **`dialog`**: confirmation UI in a modal [`Dialog`](/reference/ui/react/core/components/overlays#dialog). | | `confirmation` | Required | `ActionButtonConfirmation` | none | title, body copy, and confirm/cancel handlers. See [Confirmation object](#confirmation-object). | #### Confirmation object Nested inside `confirmation`: | Field | Type | Description | |-------|------|-------------| | `title` | `string` | Heading shown in the confirmation UI | | `description` | `ReactNode` | Optional body (text or JSX) | | `onConfirm` | `() => void` | Called when the user confirms | | `onCancel` | `() => void` | Called when the user cancels | | `confirmLabel` | `string` | Optional confirm button label (defaults vary by `mode`) | | `cancelLabel` | `string` | Optional cancel button label (defaults to **Cancel**) | | `icon` | `ReactNode` | Optional icon in **popover** header (popover mode only; dialog layout uses title and body) | #### Basic usage (popover) Default `mode` is **`popover`**: compact confirmation next to the trigger. ```tsx { void restartService() }, }} /> ``` #### Dialog mode Set **`mode="dialog"`** when you want a full modal confirmation (for example irreversible or high-impact actions). ```tsx { void factoryReset() }, }} /> ``` ### `Button` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `variant` | Optional | `'primary' \| 'secondary' \| 'danger' \| 'tertiary' \| 'link' \| 'icon' \| 'outline' \| 'ghost'` | `'secondary'` | Visual variant | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | none | Button size | | `loading` | Optional | `boolean` | `false` | Show loading spinner | | `fullWidth` | Optional | `boolean` | `false` | Expand to container width | | `icon` | Optional | `ReactNode` | none | Icon element | | `iconPosition` | Optional | `'left' \| 'right'` | `'left'` | Icon placement | | `contentClassName` | Optional | `string` | none | Class names applied to the inner content wrapper | | `disabled` | Optional | `boolean` | `false` | Disable interaction | #### Basic usage ```tsx ``` #### With icon ```tsx ``` #### Loading state ```tsx ``` #### Styling - `.mdk-button`: Root element - `.mdk-button--variant-{variant}`: Variant modifier - `.mdk-button--size-{size}`: Size modifier - `.mdk-button--full-width`: Full width modifier - `.mdk-button--loading`: Loading state ### `Cascader` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `CascaderOption[]` | none | Hierarchical options; parent options with children render in the left panel | | `value` | Optional | `CascaderValue \| CascaderValue[]` | none | Current selected value(s) | | `onChange` | Optional | `(value: CascaderValue \| CascaderValue[] \| null) => void` | none | Callback when the selection changes | | `multiple` | Optional | `boolean` | `false` | Enable multiple selection (shows checkboxes; selected items render as tags) | | `placeholder` | Optional | `string` | none | Placeholder text shown when no selections are made | | `disabled` | Optional | `boolean` | `false` | Disable the entire cascader | | `dropdownClassName` | Optional | `string` | none | Custom class name for the dropdown panels container | | `className` | Optional | `string` | none | Custom class name for the root element | #### Basic usage ```tsx ``` ### `Checkbox` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `size` | Optional | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Checkbox size | | `color` | Optional | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error'` | `'primary'` | Color when checked | | `radius` | Optional | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'` | `'none'` | Border radius | | `checked` | Optional | `boolean \| 'indeterminate'` | none | Checked state (controlled) | | `onCheckedChange` | Optional | `function` | none | Change callback | #### Basic usage ```tsx I agree to the terms ``` #### Sizes and colors ```tsx ``` #### Styling - `.mdk-checkbox`: Root element - `.mdk-checkbox--{size}`: Size modifier - `.mdk-checkbox--{color}`: Color modifier - `.mdk-checkbox__indicator`: Check mark container ### `DatePicker` #### Import ```tsx ``` #### Basic usage ```tsx ``` ### `DateRangePicker` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `selected` | Optional | `DateRange` | none | Selected `{ from, to }` range (controlled) | | `onSelect` | Optional | `(range: DateRange \| undefined) => void` | none | Called when the user applies a range | | `placeholder` | Optional | `string` | `'Pick a date range'` | Trigger text when no range is selected | | `dateFormat` | Optional | `string` | `'MM/dd/yyyy'` | `date-fns` format used in the trigger label | | `disabled` | Optional | `boolean` | `false` | Disable interaction | | `showPresets` | Optional | `boolean` | `true` | Show the default preset buttons for the last 7, 14, 30, and 90 days | | `presets` | Optional | `PresetItem[]` | none | Override the default preset list | | `allowFutureDates` | Optional | `boolean` | `false` | When `false`, dates after today are disabled | | `triggerClassName` | Optional | `string` | none | Extra classes for the trigger button | | `calendarClassName` | Optional | `string` | none | Extra classes for the calendar | | `modalClassName` | Optional | `string` | none | Extra classes for the popover modal | Any other [`react-day-picker` props](https://daypicker.dev/) (excluding `mode` and `selected`) are forwarded to the underlying calendar. #### Basic usage ```tsx const [range, setRange] = useState() ``` #### Custom presets ```tsx const presets: PresetItem[] = [ { label: 'This week', value: { from: startOfWeek(new Date()), to: new Date() } }, { label: 'This month', value: { from: startOfMonth(new Date()), to: new Date() } }, ] ``` #### Allowing future dates ```tsx ``` #### Styling - `.mdk-date-picker__trigger`: Trigger button - `.mdk-date-picker__modal`: Popover modal container - `.mdk-date-picker__calendar`: Calendar grid - `.mdk-date-picker__summary`: Selected-range summary block - `.mdk-date-picker__presets`: Preset button row ### `Input` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `string` | none | Visible label for the field | | `variant` | Optional | `'default' \| 'search'` | `'default'` | Input variant | | `size` | Optional | `'default' \| 'medium'` | `'default'` | Input size | | `error` | Optional | `string` | none | Error message (shows red border) | | `prefix` | Optional | `ReactNode` | none | Element before input | | `suffix` | Optional | `ReactNode` | none | Element after input | | `wrapperClassName` | Optional | `string` | none | Wrapper element class | #### Basic usage ```tsx ``` #### With prefix/suffix ```tsx } placeholder="Username" /> ``` #### Error state ```tsx setMac(e.target.value)} /> ``` #### Styling - `.mdk-input`: Input element - `.mdk-input__wrapper`: Wrapper container - `.mdk-input__wrapper--error`: Error state - `.mdk-input__label`: Label element - `.mdk-input__prefix`: Prefix element - `.mdk-input__suffix`: Suffix element - `.mdk-input__error`: Error message ### `Label` #### Import ```tsx ``` #### Basic usage ```tsx Email Password ``` ### `MultiSelect` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `MultiSelectOption[]` | none | Selectable options (`{ value, label }`) | | `value` | Optional | `string[]` | none | Controlled selected values; omit to use `defaultValue` for uncontrolled mode | | `defaultValue` | Optional | `string[]` | none | Initial values for uncontrolled mode; ignored when `value` is provided | | `onValueChange` | Optional | `(next: string[]) => void` | none | Called with the updated selection | | `placeholder` | Optional | `ReactNode` | none | Trigger placeholder shown when nothing is selected | | `emptyMessage` | Optional | `ReactNode` | none | Rendered inside the popover when `options` is empty | | `maxSelectedDisplay` | Optional | `number` | none | Max selected chips shown in the trigger before collapsing the rest into a "+N more" badge | | `disabled` | Optional | `boolean` | `false` | Disable the control | | `size` | Optional | `MultiSelectSize` | none | Size variant | | `variant` | Optional | `MultiSelectVariant` | none | Visual variant | | `aria-label` | Optional | `string` | none | Accessible label applied to the trigger button | | `className` | Optional | `string` | none | Custom class name for the root element | | `contentClassName` | Optional | `string` | none | Custom class name for the popover content panel | #### Basic usage ```tsx const MINER_TYPES: MultiSelectOption[] = [ { value: 'miner-am-s19xp', label: 'Antminer S19XP' }, { value: 'miner-wm-m56s', label: 'WhatsMiner M56S' }, { value: 'miner-av-a1346', label: 'Avalon A1346' }, ] function MinerTypeFilter() { const [selected, setSelected] = useState([]) return ( ) } ``` ### `Radio` #### Radio composition parts | Part | Role | |------|------| | `RadioGroup` | Root that holds the selected value and calls `onValueChange` when it changes. | | `Radio` | Default circular radio item; use `label` or children for visible text. | | `RadioCard` | Card-styled option for horizontal or compact layouts; uses the same item primitive as `Radio`. | #### Import ```tsx ``` #### `Radio` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `string` | none | Label text (or use children for custom content) | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | none | Size variant of the radio | | `color` | Optional | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error'` | none | Color variant when checked | | `radius` | Optional | `BorderRadius` | none | Border radius variant (`full` makes it circular) | | `children` | Optional | `ReactNode` | none | Custom content (takes precedence over `label`) | | `indicatorClassName` | Optional | `string` | none | Custom class name for the indicator element | | `className` | Optional | `string` | none | Custom class name for the root element | #### Basic usage ```tsx Small Medium Large ``` **RadioCard** suits card-style, horizontal groups: ```tsx ``` ### `Select` #### Import ```tsx Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, } from '@tetherto/mdk-react-devkit/core' ``` #### `Select` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `allowClear` | Optional | `boolean` | `false` | Show a clear button when a value is selected | #### `SelectTrigger` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'lg'` | Trigger size | | `variant` | Optional | `'default' \| 'colored'` | `'default'` | Visual variant | | `color` | Optional | `string` | none | Custom color for colored variant (hex) | #### Basic usage ```tsx ``` #### With groups ```tsx ``` #### Colored variant ```tsx ``` #### Styling - `.mdk-select__trigger`: Trigger button - `.mdk-select__trigger--{size}`: Size modifier - `.mdk-select__trigger--colored`: Colored variant - `.mdk-select__content`: Dropdown content - `.mdk-select__item`: Option item ### `Switch` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'md'` | Switch size | | `color` | Optional | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error'` | `'default'` | Color when checked | | `radius` | Optional | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'` | `'none'` | Border radius | | `checked` | Required | `boolean` | none | Checked state (controlled) | | `onCheckedChange` | Required | `function` | none | Change callback | #### Basic usage ```tsx Dark Mode ``` #### Sizes and colors ```tsx ``` #### Styling - `.mdk-switch`: Root element - `.mdk-switch--{size}`: Size modifier - `.mdk-switch--{color}`: Color modifier - `.mdk-switch__thumb`: Toggle thumb ### `TagInput` #### Import ```tsx ``` #### Basic usage ```tsx ``` ### `TextArea` #### Import ```tsx ``` #### Basic usage ```tsx setValue(e.target.value)} /> ``` ## Composition The `<Form>` provider plus the low-level compound components for assembling custom form fields. Use these when no [prebuilt field](/reference/ui/react/core/components/forms/fields) fits, or when you need full control over the field's layout. <ComponentTable category="Forms" subcategory="Composition" pkg="core" /> See the [Composition page](/reference/ui/react/core/components/forms/composition) for `<Form>`, the seven compound parts, and built-in validators. ## Prebuilt fields Form-bound fields pre-wired to React hook form. Each combines `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, and `FormMessage` so you can render a labelled, validated field from a single component. <ComponentTable category="Forms" subcategory="Fields" pkg="core" /> See the [Prebuilt fields page](/reference/ui/react/core/components/forms/fields) for the full prop reference and component-specific examples. # Form composition (/reference/ui/react/core/components/forms/composition) The `<Form>` provider plus the seven compound parts (`FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`) are the building blocks for any form. Use them when no [prebuilt field](/reference/ui/react/core/components/forms/fields) fits, or when you need full control over a field's layout. For standalone inputs that you can drop in without `<Form>`, see [Controls](/reference/ui/react/core/components/forms#controls). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) - Familiarity with [React hook form](https://react-hook-form.com/) ## Components <ComponentTable category="Forms" subcategory="Composition" pkg="core" /> ## `Form` <ComponentDescription name="Form" /> The package includes a complete form system built on [React hook form](https://react-hook-form.com/). `<Form>` is the context provider; the other six components on this page are the building blocks you compose inside it. See [Prebuilt fields](/reference/ui/react/core/components/forms/fields) for ready-made wrappers that render a labelled, validated field in a single tag. ### Import ```tsx Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage, useFormField, } from '@tetherto/mdk-react-devkit/core' ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `form` | Required | `UseFormReturn` | none | The instance returned by `useForm()` | | `children` | Required | `ReactNode` | none | Form content | | `onSubmit` | Required | `function` | none | Submit handler. Wrap with `form.handleSubmit(...)` to get parsed values | Any other standard `<form>` element attribute (`id`, `action`, `noValidate`, `onReset`, `ref`, `data-*`, `aria-*`, etc.) is forwarded to the underlying DOM element. ### Basic usage ```tsx function MyForm() { const form = useForm({ defaultValues: { email: '' }, }) const onSubmit = (values) => { console.log(values) } return ( <Form form={form} onSubmit={form.handleSubmit(onSubmit)}> <FormField control={form.control} name="email" render={({ field }) => ( <FormItem> <FormLabel>Email</FormLabel> <FormControl> <Input placeholder="email@example.com" {...field} /> </FormControl> <FormMessage /> </FormItem> )} /> <Button type="submit">Submit</Button> </Form> ) } ``` ### Built-in validators The package re-exports common Zod schemas and validator helpers so you can wire `useForm` to a resolver without rolling your own. ```tsx ``` ### Styling - `.mdk-form`: Root `<form>` element ## `FormField` <ComponentDescription name="FormField" /> ### Import ```tsx ``` ### Props `FormField` is a thin wrapper over [React hook form's `Controller`](https://react-hook-form.com/docs/usecontroller/controller) and accepts the same props (`control`, `name`, `defaultValue`, `rules`, `render`, etc.). It additionally provides field context to descendants like `FormLabel` and `FormControl` so they can wire up ARIA attributes automatically. ### Basic usage ```tsx <FormField control={form.control} name="username" render={({ field }) => ( <FormItem> <FormLabel>Username</FormLabel> <FormControl> <Input {...field} /> </FormControl> <FormMessage /> </FormItem> )} /> ``` ## `FormItem` <ComponentDescription name="FormItem" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `className` | Optional | `string` | none | Extra classes merged onto the wrapper | Any other standard `<div>` attribute (`id`, `ref`, `data-*`, `aria-*`, etc.) is forwarded to the underlying DOM element. ### Basic usage ```tsx <FormField control={form.control} name="bio" render={({ field }) => ( <FormItem> <FormLabel>Bio</FormLabel> <FormControl> <TextArea {...field} /> </FormControl> <FormDescription>Max 200 characters</FormDescription> <FormMessage /> </FormItem> )} /> ``` ### Styling - `.mdk-form-item`: Root element ## `FormLabel` <ComponentDescription name="FormLabel" /> ### Import ```tsx ``` ### Props Accepts every prop the underlying [`FormLabel`](#formlabel) accepts. The `htmlFor` attribute is set automatically from the `FormItem` context, and an error modifier class is applied when the field has a validation error. ### Basic usage ```tsx <FormItem> <FormLabel>Email address</FormLabel> <FormControl> <Input type="email" {...field} /> </FormControl> </FormItem> ``` ### Styling - `.mdk-form-label`: Root element - `.mdk-form-label--error`: Applied when the field has a validation error ## `FormControl` <ComponentDescription name="FormControl" /> ### Import ```tsx ``` ### Props `FormControl` uses [Radix `Slot`](https://www.radix-ui.com/primitives/docs/utilities/slot) to merge its props onto its single child without adding an extra DOM node. It autoinjects `id`, `aria-describedby`, and `aria-invalid` based on the surrounding `FormItem`/`FormField` context. ### Basic usage ```tsx <FormItem> <FormLabel>Phone</FormLabel> <FormControl> <Input type="tel" {...field} /> </FormControl> <FormMessage /> </FormItem> ``` `FormControl` must wrap exactly one child element. ## `FormDescription` <ComponentDescription name="FormDescription" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `className` | Optional | `string` | none | Extra classes merged onto the wrapper | Any other standard `<p>` attribute (`id`, `ref`, `data-*`, `aria-*`, etc.) is forwarded to the underlying DOM element. ### Basic usage ```tsx <FormItem> <FormLabel>Password</FormLabel> <FormControl> <Input type="password" {...field} /> </FormControl> <FormDescription>Must be at least 8 characters</FormDescription> <FormMessage /> </FormItem> ``` ### Styling - `.mdk-form-description`: Root element ## `FormMessage` <ComponentDescription name="FormMessage" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `children` | Required | `ReactNode` | none | Fallback content shown when the field has no validation error | | `className` | Optional | `string` | none | Extra classes merged onto the wrapper | Any other standard `<p>` attribute (`id`, `ref`, `data-*`, `aria-*`, etc.) is forwarded to the underlying DOM element. `FormMessage` always renders to prevent layout shift. When an error is present it shows the validation message and applies `role="alert"`; otherwise it shows `children` (or a non-breaking space placeholder) and adds the `--empty` modifier class. ### Basic usage ```tsx <FormItem> <FormLabel>Email</FormLabel> <FormControl> <Input type="email" {...field} /> </FormControl> <FormMessage /> </FormItem> ``` ### Styling - `.mdk-form-message`: Root element - `.mdk-form-message--empty`: Applied when no error and no children are present # Prebuilt form fields (/reference/ui/react/core/components/forms/fields) Form-bound fields pre-wired to React hook form. Each combines [`FormField`](/reference/ui/react/core/components/forms/composition#formfield), [`FormItem`](/reference/ui/react/core/components/forms/composition#formitem), [`FormLabel`](/reference/ui/react/core/components/forms/composition#formlabel), [`FormControl`](/reference/ui/react/core/components/forms/composition#formcontrol), [`FormDescription`](/reference/ui/react/core/components/forms/composition#formdescription), and [`FormMessage`](/reference/ui/react/core/components/forms/composition#formmessage) so you can render a labelled, validated field from a single component. For raw inputs without form binding, see [Controls](/reference/ui/react/core/components/forms#controls). To assemble a custom field from the building blocks, see [Composition](/reference/ui/react/core/components/forms/composition). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) - Wrap your form in [`<Form>`](/reference/ui/react/core/components/forms/composition#form) and pass `form.control` to each field ## Components <ComponentTable category="Forms" subcategory="Fields" pkg="core" /> ## Common props Every prebuilt field accepts the [`Controller`](https://react-hook-form.com/docs/usecontroller/controller) props from React hook form (`control`, `name`, `defaultValue`, `rules`, `shouldUnregister`, `disabled`) plus three presentation props: | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `string` | none | Label displayed above the field | | `description` | Optional | `string` | none | Helper text below the field | | `placeholder` | Optional | `string` | none | Placeholder text (ignored by `FormCheckbox` and `FormSwitch`) | Component-specific props are listed under each field below. ## `FormCascader` <ComponentDescription name="FormCascader" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `CascaderOption[]` | none | Hierarchical options tree | | `multiple` | Optional | `boolean` | `false` | Allow multiple selection | | `cascaderProps` | Required | `object` | none | Pass-through props for the underlying `Cascader` | ### Basic usage ```tsx <FormCascader control={form.control} name="category" label="Category" placeholder="Select category..." options={[ { value: 'electronics', label: 'Electronics', children: [ { value: 'phones', label: 'Phones' }, { value: 'laptops', label: 'Laptops' }, ], }, ]} description="Choose a category and subcategory" /> ``` ### Multiple selection ```tsx <FormCascader control={form.control} name="categories" label="Categories" placeholder="Select categories..." options={categoryOptions} multiple description="Select multiple categories" /> ``` ## `FormCheckbox` <ComponentDescription name="FormCheckbox" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `layout` | Optional | `'row' \| 'column'` | `'row'` | Whether the label sits inline with the checkbox or above it | | `checkboxProps` | Required | `object` | none | Pass-through props for the underlying `Checkbox` | ### Basic usage ```tsx <FormCheckbox control={form.control} name="terms" label="Accept terms and conditions" description="You must agree to continue" /> ``` ## `FormDatePicker` <ComponentDescription name="FormDatePicker" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `datePickerProps` | Required | `object` | none | Pass-through props for the underlying `DatePicker` (excluding `selected` and `onSelect`, which are bound to the form) | ### Basic usage ```tsx <FormDatePicker control={form.control} name="startDate" label="Start Date" placeholder="Pick a date" description="When should this take effect?" /> ``` ## `FormInput` <ComponentDescription name="FormInput" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `type` | Optional | `'text' \| 'email' \| 'password' \| 'number' \| ...` | `'text'` | HTML input type | | `variant` | Optional | `'default' \| 'search'` | `'default'` | Input variant | | `inputProps` | Required | `object` | none | Pass-through props for the underlying `Input` (excluding `type` and `variant`) | ### Basic usage ```tsx <FormInput control={form.control} name="email" label="Email" type="email" placeholder="user@example.com" description="We'll never share your email" /> ``` ## `FormRadioGroup` <ComponentDescription name="FormRadioGroup" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `FormRadioOption[]` | none | Array of `{ value, label, disabled? }` items | | `orientation` | Optional | `'horizontal' \| 'vertical'` | `'vertical'` | Radio layout direction | | `radioGroupProps` | Required | `object` | none | Pass-through props for the underlying `RadioGroup` | ### Basic usage ```tsx <FormRadioGroup control={form.control} name="priority" label="Priority" options={[ { value: 'low', label: 'Low' }, { value: 'medium', label: 'Medium' }, { value: 'high', label: 'High' }, ]} orientation="horizontal" /> ``` ## `FormSelect` <ComponentDescription name="FormSelect" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `FormSelectOption[]` | none | Array of `{ value, label, disabled? }` items | | `selectProps` | Required | `object` | none | Pass-through props for the underlying `Select` (excluding `onValueChange` and `defaultValue`, which are bound to the form) | ### Basic usage ```tsx <FormSelect control={form.control} name="role" label="Role" placeholder="Select a role" options={[ { value: 'admin', label: 'Admin' }, { value: 'user', label: 'User' }, ]} description="Your access level" /> ``` ## `FormSwitch` <ComponentDescription name="FormSwitch" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `layout` | Optional | `'row' \| 'column'` | `'row'` | Whether the label sits inline with the switch or above it | | `switchProps` | Required | `object` | none | Pass-through props for the underlying `Switch` (excluding `checked` and `onCheckedChange`) | ### Basic usage ```tsx <FormSwitch control={form.control} name="notifications" label="Enable notifications" description="Receive alerts when miners go offline" /> ``` ## `FormTagInput` <ComponentDescription name="FormTagInput" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `TagInputOption[]` | none | Suggested tags offered as autocomplete options | | `allowCustomTags` | Optional | `boolean` | `true` | Let users type tags not present in `options` | | `variant` | Optional | `'default' \| 'search'` | `'search'` | Visual variant | | `tagInputProps` | Required | `object` | none | Pass-through props for the underlying `TagInput` | ### Basic usage ```tsx <FormTagInput control={form.control} name="tags" label="Tags" placeholder="Add tags..." options={['React', 'TypeScript', 'Node.js']} description="Select or type tags" /> ``` ## `FormTextArea` <ComponentDescription name="FormTextArea" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `textAreaProps` | Required | `object` | none | Pass-through props for the underlying `TextArea` | ### Basic usage ```tsx <FormTextArea control={form.control} name="bio" label="Bio" placeholder="Tell us about yourself" description="Max 200 characters" /> ``` # Loading (/reference/ui/react/core/components/loading) Components for indicating loading and progress states. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## `Spinner` <ComponentDescription name="Spinner" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'md'` | Spinner size | | `color` | Optional | `'primary' \| 'secondary'` | none | Color variant of the spinner | | `type` | Optional | `'circle' \| 'square'` | none | Type of spinner animation | | `speed` | Optional | `'slow' \| 'normal' \| 'fast'` | none | Speed of the animation | | `label` | Optional | `string` | none | Optional label text displayed below the spinner | | `fullScreen` | Optional | `boolean` | `false` | Display in fullscreen mode | | `className` | Optional | `string` | none | Additional CSS class | ### Basic usage ```tsx <Spinner /> <Spinner size="sm" /> <Spinner size="lg" /> <Spinner type="circle" speed="fast" /> <Spinner label="Loading miners..." /> ``` ### With content ```tsx <Button disabled> <Spinner size="sm" /> Loading... </Button> ``` ### Styling - `.mdk-spinner`: Root element - `.mdk-spinner--{size}`: Size modifier ## `Loader` <ComponentDescription name="Loader" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `count` | Optional | `3 \| 5 \| 7` | `5` | Number of dots to display | | `color` | Optional | `'red' \| 'gray' \| 'blue' \| 'amber' \| 'orange'` | `'orange'` | Color variant of the loader | | `size` | Optional | `number` | `10` | Size of each dot in pixels | | `className` | Optional | `string` | none | Additional CSS class | ### Basic usage ```tsx <Loader /> <Loader color="blue" /> <Loader count={3} size={8} color="amber" /> <Loader count={7} size={12} color="red" /> ``` ### In a container ```tsx <div className="relative min-h-[200px]"> {isLoading && <Loader />} {data && <DataDisplay data={data} />} </div> ``` ### Styling - `.mdk-loader`: Root container - `.mdk-loader__dot`: Individual dot - `.mdk-loader__dot--{color}`: Dot color modifier # Log components (/reference/ui/react/core/components/logs) Components for displaying log entries, activity feeds, and event histories. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## `LogsCard` <ComponentDescription name="LogsCard" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `logsData` | Required | `LogData[]` | `[]` | Array of log entries | | `type` | Required | `string` | none | Log type identifier | | `label` | Required | `string` | none | Card label | | `isLoading` | Required | `boolean` | `false` | Show loading skeleton | | `isDark` | Required | `boolean` | `false` | Dark theme variant | | `emptyMessage` | Required | `string` | `'No incidents'` | Empty state message | | `skeletonRows` | Required | `number` | `5` | Number of skeleton rows | | `pagination` | Required | `LogPagination` | none | Pagination configuration | | `onLogClicked` | Required | `function` | none | Log click callback | ### `LogData` type ```tsx type LogData = { uuid: string body: string title: string status: string subtitle: string } ``` ### `LogPagination` type ```tsx type LogPagination = { current: number total: number pageSize: number handlePaginationChange: (page: number) => void } ``` ### Basic usage ```tsx const logs = [ { uuid: '1', title: 'Miner Offline', subtitle: 'Site A - Rack 12', body: 'Miner 001 went offline at 14:32', status: 'error', }, { uuid: '2', title: 'Hashrate Drop', subtitle: 'Site B - Rack 5', body: 'Hashrate dropped below threshold', status: 'warning', }, ] <LogsCard label="Recent Incidents" logsData={logs} type="incident" onLogClicked={(uuid) => handleLogClick(uuid)} /> ``` ### With pagination ```tsx const [page, setPage] = useState(1) <LogsCard label="Activity Log" logsData={logs} type="activity" pagination={{ current: page, total: 100, pageSize: 10, handlePaginationChange: setPage, }} /> ``` ### Loading state ```tsx <LogsCard label="Loading..." isLoading skeletonRows={5} /> ``` ### Styling - `.mdk-logs-card`: Root container - `.mdk-logs-card__inner-container`: Content wrapper - `.mdk-logs-card__list-container`: Log list container - `.mdk-logs-card__pagination`: Pagination area - `.mdk-logs-card__empty`: Empty state container ## `LogRow` <ComponentDescription name="LogRow" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `log` | Required | `LogData` | none | Log entry data | | `type` | Required | `string` | none | Log type identifier | | `style` | Optional | `CSSProperties` | none | Custom styles | | `onLogClicked` | Optional | `function` | none | Click callback | ### Basic usage ```tsx <LogRow log={{ uuid: '1', title: 'System Alert', subtitle: 'High temperature detected', body: 'Rack 5 temperature exceeded 80°C', status: 'warning', }} type="alert" onLogClicked={(uuid) => viewDetails(uuid)} /> ``` ## `LogItem` <ComponentDescription name="LogItem" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `LogData` | none | Log entry data | | `onLogClicked` | Optional | `function` | none | Click callback | ### Basic usage ```tsx <LogItem data={{ uuid: '1', title: 'Configuration Change', subtitle: 'Pool settings updated', body: 'Primary pool changed to us-east', status: 'info', }} /> ``` ## `LogDot` <ComponentDescription name="LogDot" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `type` | Required | `string` | none | Log type identifier | | `status` | Required | `string` | none | Status value | ### Basic usage ```tsx <LogDot type="incident" status="error" /> <LogDot type="activity" status="success" /> <LogDot type="alert" status="warning" /> ``` ## `LogActivityIcon` <ComponentDescription name="LogActivityIcon" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `status` | Required | `string` | none | Status value | ### Basic usage ```tsx <LogActivityIcon status="online" /> <LogActivityIcon status="offline" /> <LogActivityIcon status="warning" /> ``` ## Status values Log components support the following status values: | Status | Color | Use case | |--------|-------|----------| | `success` | Green | Successful operations | | `error` | Red | Errors, failures | | `warning` | Yellow | Warnings, alerts | | `info` | Blue | Informational | | `default` | Gray | Neutral/unknown | # Navigation (/reference/ui/react/core/components/navigation) Components for navigating between views and organizing content. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## `AppHeader` <ComponentDescription name="AppHeader" /> ### Import ```tsx ``` ### Props `AppHeader` is a three-slot top-bar shell. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `logo` | Optional | `ReactNode` | none | Left-most slot — typically the app's brand lockup / logo | | `start` | Optional | `ReactNode` | none | Left-edge content — e.g. a sidebar collapse toggle button | | `children` | Optional | `ReactNode` | none | Middle slot — typically the dashboard's stats strip | | `actions` | Optional | `ReactNode` | none | Right-edge action cluster — e.g. alarms bell, profile menu | | `sticky` | Optional | `boolean` | `true` | Render the header sticky to the top of its scroll container | | `className` | Optional | `string` | none | Class hook for the outer `<header>` element | ### Basic usage ```tsx <AppHeader start={<strong>MDK</strong>} actions={<Button size="sm">Sign out</Button>} > <div>Header content</div> </AppHeader> ``` ## `Sidebar` <ComponentDescription name="Sidebar" /> ### Import ```tsx Sidebar, useSidebarExpandedState, useSidebarSectionState, clearSidebarState, } from '@tetherto/mdk-react-devkit/core' ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `items` | Required | `SidebarMenuItem[]` | none | **Required.** Menu items array | | `activeId` | Required | `string` | none | Currently active item ID | | `expanded` | Required | `boolean` | none | Controlled expanded state | | `defaultExpanded` | Optional | `boolean` | `false` | Initial expanded state | | `visible` | Optional | `boolean` | `true` | Sidebar visibility | | `overlay` | Optional | `boolean` | `false` | Overlay mode (mobile) | | `header` | Optional | `ReactNode` | none | Header content | | `onItemClick` | Required | `function` | none | Item click callback | | `onExpandedChange` | Required | `function` | none | Expand state callback | | `onClose` | Required | `function` | none | Close callback (overlay mode) | ### `SidebarMenuItem` type ```tsx type SidebarMenuItem = { id: string label: string icon?: ReactNode href?: string children?: SidebarMenuItem[] disabled?: boolean } ``` ### Basic usage ```tsx const items = [ { id: 'dashboard', label: 'Dashboard', icon: <DashboardIcon /> }, { id: 'settings', label: 'Settings', icon: <SettingsIcon /> }, { id: 'reports', label: 'Reports', icon: <ReportsIcon />, children: [ { id: 'daily', label: 'Daily' }, { id: 'weekly', label: 'Weekly' }, ], }, ] <Sidebar items={items} activeId="dashboard" onItemClick={(item) => navigate(item.href)} /> ``` ### With persisted state ```tsx function App() { const [expanded, setExpanded] = useSidebarExpandedState(true) return ( <Sidebar items={items} expanded={expanded} onExpandedChange={setExpanded} /> ) } ``` ### Styling - `.mdk-sidebar`: Root container - `.mdk-sidebar--expanded`: Expanded state - `.mdk-sidebar--hidden`: Hidden state - `.mdk-sidebar--overlay`: Overlay mode - `.mdk-sidebar__toggle`: Expand/collapse button - `.mdk-sidebar__menu`: Menu container - `.mdk-sidebar__backdrop`: Overlay backdrop ## `Tabs` <ComponentDescription name="Tabs" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `defaultValue` | Optional | `string` | none | Initially active tab | | `value` | Optional | `string` | none | Controlled active tab | | `onValueChange` | Optional | `function` | none | Tab change callback | | `variant` | Optional | `'default' \| 'side'` | `'default'` | Tab layout variant | ### Basic usage ```tsx <Tabs defaultValue="overview"> <TabsList> <TabsTrigger value="overview">Overview</TabsTrigger> <TabsTrigger value="settings">Settings</TabsTrigger> <TabsTrigger value="logs" disabled>Logs</TabsTrigger> </TabsList> <TabsContent value="overview"> Overview content here </TabsContent> <TabsContent value="settings"> Settings content here </TabsContent> </Tabs> ``` ### Side variant ```tsx <Tabs defaultValue="tab1" variant="side"> <TabsList variant="side"> <TabsTrigger value="tab1" variant="side">Tab 1</TabsTrigger> <TabsTrigger value="tab2" variant="side">Tab 2</TabsTrigger> </TabsList> <TabsContent value="tab1">Content 1</TabsContent> <TabsContent value="tab2">Content 2</TabsContent> </Tabs> ``` ### Styling - `.mdk_tabs`: Root container - `.mdk_tabs__list`: Tab button container - `.mdk_tabs__list--side`: Side variant list - `.mdk_tabs__trigger`: Individual tab button - `.mdk_tabs__content`: Tab panel content ## `LazyTabWrapper` <ComponentDescription name="LazyTabWrapper" /> ### Import ```tsx ``` ### Usage ```tsx <TabsContent value="heavy-content"> <LazyTabWrapper> <ExpensiveComponent /> </LazyTabWrapper> </TabsContent> ``` ## `Breadcrumbs` <ComponentDescription name="Breadcrumbs" /> ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `items` | Required | `BreadcrumbItem[]` | none | Breadcrumb entries to render; each item is `{ label, href?, onClick? }` | | `showBack` | Optional | `boolean` | `false` | Render a back button before the breadcrumb trail | | `backLabel` | Optional | `string` | `'Back'` | Accessible label / text for the back button | | `onBackClick` | Optional | `VoidFunction` | none | Callback fired when the back button is clicked | | `separator` | Optional | `ReactNode` | `'/'` | Custom node rendered between items | | `itemClassName` | Optional | `string` | none | Custom class name applied to each breadcrumb item | | `backClassName` | Optional | `string` | none | Custom class name applied to the back button | | `className` | Optional | `string` | none | Custom class name for the root element | ### Basic usage ```tsx const items: BreadcrumbItem[] = [ { label: 'Home', href: '/' }, { label: 'Miners', href: '/miners' }, { label: 'Details' }, ] <Breadcrumbs items={items} /> ``` ### Styling - `.mdk-breadcrumbs`: Root container - `.mdk-breadcrumbs__item`: Individual item - `.mdk-breadcrumbs__separator`: Separator between items # Overlays (/reference/ui/react/core/components/overlays) Overlay components display content above the main interface. All components are built on [Radix UI](https://www.radix-ui.com/) primitives for accessibility. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## `Dialog` <ComponentDescription name="Dialog" /> ### Import ```tsx Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose, } from '@tetherto/mdk-react-devkit/core' ``` ## `DialogContent` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `title` | Optional | `string` | none | Dialog title | | `description` | Optional | `string` | none | Dialog description | | `closable` | Optional | `boolean` | `false` | Show close button | | `onClose` | Optional | `function` | none | Close callback | | `closeOnClickOutside` | Optional | `boolean` | `true` | Close when clicking outside | | `closeOnEscape` | Optional | `boolean` | `true` | Close on Escape key | | `bare` | Optional | `boolean` | `false` | Minimal header styling | ## Basic usage ```tsx <Dialog> <DialogTrigger asChild> <Button>Open Dialog</Button> </DialogTrigger> <DialogContent title="Confirm Action" closable onClose={() => {}}> <p>Are you sure you want to proceed?</p> <DialogFooter> <DialogClose asChild> <Button variant="secondary">Cancel</Button> </DialogClose> <Button>Confirm</Button> </DialogFooter> </DialogContent> </Dialog> ``` ## Styling - `.mdk-dialog__overlay`: Background overlay - `.mdk-dialog__content`: Dialog container - `.mdk-dialog__header`: Header area - `.mdk-dialog__title`: Title text - `.mdk-dialog__description`: Description text - `.mdk-dialog__footer`: Footer area ## `DropdownMenu` <ComponentDescription name="DropdownMenu" /> ### Import ```tsx DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuLabel, DropdownMenuGroup, } from '@tetherto/mdk-react-devkit/core' ``` ### Basic usage ```tsx <DropdownMenu> <DropdownMenuTrigger asChild> <Button>Options</Button> </DropdownMenuTrigger> <DropdownMenuContent> <DropdownMenuLabel>Actions</DropdownMenuLabel> <DropdownMenuItem onClick={() => {}}>Edit</DropdownMenuItem> <DropdownMenuItem onClick={() => {}}>Duplicate</DropdownMenuItem> <DropdownMenuSeparator /> <DropdownMenuItem onClick={() => {}} className="text-red-500"> Delete </DropdownMenuItem> </DropdownMenuContent> </DropdownMenu> ``` ### Styling - `.mdk-dropdown-menu__content`: Menu container - `.mdk-dropdown-menu__item`: Menu item - `.mdk-dropdown-menu__label`: Label text - `.mdk-dropdown-menu__separator`: Divider line ## `Popover` <ComponentDescription name="Popover" /> ### Import ```tsx Popover, PopoverTrigger, PopoverContent, } from '@tetherto/mdk-react-devkit/core' ``` #### Basic usage ```tsx <Popover> <PopoverTrigger asChild> <Button>Show Details</Button> </PopoverTrigger> <PopoverContent> <p>Additional information goes here.</p> </PopoverContent> </Popover> ``` ### Styling - `.mdk-popover__content`: Popover container ## `Toast` <ComponentDescription name="Toast" /> ### Import ```tsx ``` ### `Toast` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `title` | Required | `string` | none | **Required.** Toast title | | `description` | Optional | `string` | none | Additional description | | `variant` | Optional | `'success' \| 'error' \| 'warning' \| 'info'` | `'info'` | Toast variant | | `icon` | Optional | `ReactElement` | none | Custom icon | ### `ToastViewport` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `position` | Optional | `ToastPosition` | `'bottom-right'` | Toast position | Available positions: `'top-left'`, `'top-center'`, `'top-right'`, `'bottom-left'`, `'bottom-center'`, `'bottom-right'` ### Setup ```tsx function App() { return ( <ToastProvider> <ToastViewport position="bottom-right" /> </ToastProvider> ) } ``` ### Basic usage ```tsx function MyComponent() { const [open, setOpen] = useState(false) return ( <> <Button onClick={() => setOpen(true)}>Show Toast</Button> <Toast open={open} onOpenChange={setOpen} title="Success!" description="Your changes have been saved." variant="success" /> </> ) } ``` ### Styling - `.mdk_toast`: Toast container - `.mdk_toast__header`: Header section - `.mdk_toast__title`: Title text - `.mdk_toast__description`: Description text - `.mdk_toast__close`: Close button ## `Tooltip` <ComponentDescription name="Tooltip" /> ### Import ```tsx Tooltip, TooltipTrigger, TooltipContent, TooltipProvider, } from '@tetherto/mdk-react-devkit/core' ``` ### Basic usage ```tsx <TooltipProvider> <Tooltip> <TooltipTrigger asChild> <Button variant="icon"> <InfoIcon /> </Button> </TooltipTrigger> <TooltipContent> Additional information </TooltipContent> </Tooltip> </TooltipProvider> ``` ### Styling - `.mdk-tooltip__content`: Tooltip container # Icons (/reference/ui/react/core/icons) The `@tetherto/mdk-react-devkit/core` package includes **70+ icons** to simplify development of Bitcoin mining applications. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## Import ```tsx // Import individual icons // Import the factory function // Import types ``` ### Icon props All icons accept the `IconProps` interface: | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `size` | Optional | `number \| string` | `24` | Sets both width and height | | `color` | Optional | `string` | `'currentColor'` | Icon color (single-color icons only) | | `width` | Optional | `number \| string` | none | Override width | | `height` | Optional | `number \| string` | none | Override height | | `className` | Optional | `string` | none | CSS class | | `style` | Optional | `CSSProperties` | none | Inline styles | ### Basic usage ```tsx // Default size (24px) <DashboardNavIcon /> // Custom size <HashrateStatIcon size={32} /> // Custom color <MiningStatusIcon color="#72F59E" /> // With className <SettingsNavIcon className="sidebar-icon" /> ``` ## Available icons ### Navigation icons Icons for sidebar and navigation menus: | Icon | Name | Description | |------|------|-------------| | ![dashboard-nav-icon](/images/ui-kit/icons/dashboard-nav-icon.svg) | `DashboardNavIcon` | Dashboard/home | | <DocIcon src="/images/ui-kit/icons/farms-nav-icon.svg" scale={75} /> | `FarmsNavIcon` | Mining farms | | ![financials-nav-icon](/images/ui-kit/icons/financials-nav-icon.svg) | `FinancialsNavIcon` | Financial reports | | ![inventory-nav-icon](/images/ui-kit/icons/inventory-nav-icon.svg) | `InventoryNavIcon` | Equipment inventory | | ![miners-overview-nav-icon](/images/ui-kit/icons/miners-overview-nav-icon.svg) | `MinersOverviewNavIcon` | Miner overview | | ![operations-nav-icon](/images/ui-kit/icons/operations-nav-icon.svg) | `OperationsNavIcon` | Operations | | ![pool-manager-nav-icon](/images/ui-kit/icons/pool-manager-nav-icon.svg) | `PoolManagerNavIcon` | Pool Manager | | ![reporting-nav-icon](/images/ui-kit/icons/reporting-nav-icon.svg) | `ReportingNavIcon` | Reporting | | ![settings-nav-icon](/images/ui-kit/icons/settings-nav-icon.svg) | `SettingsNavIcon` | Settings | | ![user-management-nav-icon](/images/ui-kit/icons/user-management-nav-icon.svg) | `UserManagementNavIcon` | User management | | ![explorer-nav-icon](/images/ui-kit/icons/explorer-nav-icon.svg) | `ExplorerNavIcon` | Explorer | | ![alerts-nav-icon](/images/ui-kit/icons/alerts-nav-icon.svg) | `AlertsNavIcon` | Alerts | | ![cabinet-widget-nav-icon](/images/ui-kit/icons/cabinet-widget-nav-icon.svg) | `CabinetWidgetNavIcon` | Cabinet widgets | | ![container-widgets-nav-icon](/images/ui-kit/icons/container-widgets-nav-icon.svg) | `ContainerWidgetsNavIcon` | Container widgets | ### Status icons Icons for displaying operational status: | Icon | Name | Description | |------|------|-------------| | ![mining-status-icon](/images/ui-kit/icons/mining-status-icon.svg) | `MiningStatusIcon` | Active mining | | ![offline-status-icon](/images/ui-kit/icons/offline-status-icon.svg) | `OfflineStatusIcon` | Offline | | ![sleep-status-icon](/images/ui-kit/icons/sleep-status-icon.svg) | `SleepStatusIcon` | Sleep/standby mode | | <DocIcon src="/images/ui-kit/icons/error-status-icon.svg" scale={50} /> | `ErrorStatusIcon` | Error state | | ![live-icon](/images/ui-kit/icons/live-icon.svg) | `LiveIcon` | Live/active | ### Alarm icons Icons for alerts and alarms: | Icon | Name | Description | |------|------|-------------| | ![temperature-alarm-icon](/images/ui-kit/icons/temperature-alarm-icon.svg) | `TemperatureAlarmIcon` | Temperature alarm | | ![pressure-alarm-icon](/images/ui-kit/icons/pressure-alarm-icon.svg) | `PressureAlarmIcon` | Pressure alarm | | ![fluid-alarm-icon](/images/ui-kit/icons/fluid-alarm-icon.svg) | `FluidAlarmIcon` | Fluid/coolant alarm | | ![offline-alarm-icon](/images/ui-kit/icons/offline-alarm-icon.svg) | `OfflineAlarmIcon` | Offline alarm | | ![other-alarm-icon](/images/ui-kit/icons/other-alarm-icon.svg) | `OtherAlarmIcon` | Generic alarm | | ![alert-triangle-icon](/images/ui-kit/icons/alert-triangle-icon.svg) | `AlertTriangleIcon` | Warning triangle | ### Weather icons Icons for environmental conditions: | Icon | Name | Description | |------|------|-------------| | <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/sunny-icon.svg" alt="sunny-icon" /></span> | `SunnyIcon` | Sunny/clear | | ⛅ | `CloudyIcon` | Cloudy | | <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/rainy-icon.svg" alt="rainy-icon" /></span> | `RainyIcon` | Rain | | <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/snowy-icon.svg" alt="snowy-icon" /></span> | `SnowyIcon` | Snow | | <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/partly-cloudy-icon.svg" alt="partly-cloudy-icon" /></span> | `PartlyCloudyIcon` | Partly cloudy | | <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/rain-thunder-icon.svg" alt="rain-thunder-icon" /></span> | `RainThunderIcon` | Thunderstorm | ### Mining/stats icons Icons for mining metrics and statistics: | Icon | Name | Description | |------|------|-------------| | ![hashrate-card-icon](/images/ui-kit/icons/hashrate-card-icon.svg) | `HashrateCardIcon` | Hashrate display | | ![hashrate-stat-icon](/images/ui-kit/icons/hashrate-stat-icon.svg) | `HashrateStatIcon` | Hashrate statistic | | ![miners-stat-icon](/images/ui-kit/icons/miners-stat-icon.svg) | `MinersStatIcon` | Miner count | | ![farm-star-icon](/images/ui-kit/icons/farm-star-icon.svg) | `FarmStarIcon` | Farm highlight | | ![farm-alert-icon](/images/ui-kit/icons/farm-alert-icon.svg) | `FarmAlertIcon` | Farm alert | | ![miner-overview-icon](/images/ui-kit/icons/miner-overview-icon.svg) | `MinerOverviewIcon` | Miner overview | | ![miner-explorer-icon](/images/ui-kit/icons/miner-explorer-icon.svg) | `MinerExplorerIcon` | Miner explorer | | ![pools-icon](/images/ui-kit/icons/pools-icon.svg) | `PoolsIcon` | Mining pools | | <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/production-data-icon.svg" alt="production-data-icon" /></span> | `ProductionDataIcon` | Production data | ### Measurement icons Icons for measurements and readings: | Icon | Name | Description | |------|------|-------------| | ![power-icon](/images/ui-kit/icons/power-icon.svg) | `PowerIcon` | Power consumption | | ![fan-icon](/images/ui-kit/icons/fan-icon.svg) | `FanIcon` | Fan/cooling | | ![frequency-icon](/images/ui-kit/icons/frequency-icon.svg) | `FrequencyIcon` | Frequency | | ![efficiency-icon](/images/ui-kit/icons/efficiency-icon.svg) | `EfficiencyIcon` | Efficiency | | ![consumption-icon](/images/ui-kit/icons/consumption-icon.svg) | `ConsumptionIcon` | Consumption | | ![temperature-celsius-icon](/images/ui-kit/icons/temperature-celsius-icon.svg) | `TemperatureCelsiusIcon` | Temperature (°C) | | ![temperature-indicator-icon](/images/ui-kit/icons/temperature-indicator-icon.svg) | `TemperatureIndicatorIcon` | Temperature indicator | | <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/temperature-weather-icon.svg" alt="temperature-weather-icon" /></span> | `TemperatureWeatherIcon` | Temperature/weather | | ![cooling-drop-icon](/images/ui-kit/icons/cooling-drop-icon.svg) | `CoolingDropIcon` | Cooling/liquid | ### UI icons General UI icons: | Icon | Name | Description | |------|------|-------------| | ![arrow-icon](/images/ui-kit/icons/arrow-icon.svg) | `ArrowIcon` | Arrow (direction) | | ![right-arrow-icon](/images/ui-kit/icons/right-arrow-icon.svg) | `RightArrowIcon` | Right arrow | | ![right-navigate-icon](/images/ui-kit/icons/right-navigate-icon.svg) | `RightNavigateIcon` | Navigate right | | <DocIcon src="/images/ui-kit/icons/pin-icon.svg" scale={50} /> | `PinIcon` | Pin/favorite | | <DocIcon src="/images/ui-kit/icons/unpin-icon.svg" scale={50} /> | `UnPinIcon` | Unpin | | ![menu-icon](/images/ui-kit/icons/menu-icon.svg) | `MenuIcon` | Menu hamburger | | ![export-icon](/images/ui-kit/icons/export-icon.svg) | `ExportIcon` | Export data | | ![google-icon](/images/ui-kit/icons/google-icon.svg) | `GoogleIcon` | Google logo | | ![notification-bell-icon](/images/ui-kit/icons/notification-bell-icon.svg) | `NotificationBellIcon` | Notifications | | ![settings-header-icon](/images/ui-kit/icons/settings-header-icon.svg) | `SettingsHeaderIcon` | Settings gear | | ![sign-out-icon](/images/ui-kit/icons/sign-out-icon.svg) | `SignOutIcon` | Sign out | | ![user-avatar-icon](/images/ui-kit/icons/user-avatar-icon.svg) | `UserAvatarIcon` | User avatar | | ![volume-on-icon](/images/ui-kit/icons/volume-on-icon.svg) | `VolumeOnIcon` | Volume on | | ![volume-off-icon](/images/ui-kit/icons/volume-off-icon.svg) | `VolumeOffIcon` | Volume off | | ![comment-icon](/images/ui-kit/icons/comment-icon.svg) | `CommentIcon` | Comment | | ![comment-icon-common](/images/ui-kit/icons/comment-icon-common.svg) | `CommentIconCommon` | Comment (common variant) | | ![increase-icon](/images/ui-kit/icons/increase-icon.svg) | `IncreaseIcon` | Increase/up | | ![decrease-icon](/images/ui-kit/icons/decrease-icon.svg) | `DecreaseIcon` | Decrease/down | | ![profit-arrow-icon](/images/ui-kit/icons/profit-arrow-icon.svg) | `ProfitArrowIcon` | Profit indicator | | ![btc-card-icon](/images/ui-kit/icons/btc-card-icon.svg) | `BtcCardIcon` | Bitcoin card | | ![mode-icon](/images/ui-kit/icons/mode-icon.svg) | `ModeIcon` | Mode toggle | | ![scale-control-icon](/images/ui-kit/icons/scale-control-icon.svg) | `ScaleControlIcon` | Scale control | | ![site-overview-icon](/images/ui-kit/icons/site-overview-icon.svg) | `SiteOverviewIcon` | Site overview | | ![actions-tick-icon](/images/ui-kit/icons/actions-tick-icon.svg) | `ActionsTickIcon` | Action complete | ## Create custom icons Use `createIcon` to create custom icons following the same pattern: ```tsx displayName: 'MyCustomIcon', viewBox: '0 0 24 24', defaultWidth: 24, defaultHeight: 24, path: ( <path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" /> ), }) ``` ### `CreateIconOptions` | Option | Type | Default | Description | |--------|------|---------|-------------| | `displayName` | `string` | none | **Required:** Component display name | | `viewBox` | `string` | none | **Required:** SVG `viewBox` | | `defaultWidth` | `number` | `24` | Default width | | `defaultHeight` | `number` | `24` | Default height | | `multiColor` | `boolean` | `false` | Multi-color icon flag | | `path` | `ReactNode \| function` | none | **Required:** SVG path content | ### Dynamic color icons For icons that need dynamic colors: ```tsx displayName: 'DynamicColorIcon', viewBox: '0 0 24 24', path: ({ color }) => ( <circle cx="12" cy="12" r="10" fill={color} /> ), }) ``` # Theme (/reference/ui/react/core/theme) The `@tetherto/mdk-react-devkit/core` package provides a theme system with design tokens and utilities for consistent styling across your application. Import `@tetherto/mdk-react-devkit/styles.css` once in your app entry (before your own CSS). The compiled stylesheet declares `@layer base`, `mdk`, `app` — so unlayered or `@layer app` styles in your application always win against devkit component styles. MDK ships with `--mdk-color-primary: #f7931a`; override tokens in `:root` only when reskinning. ```css /* app.css — imported AFTER @tetherto/mdk-react-devkit/styles.css */ :root { --mdk-color-primary: #f7931a; --mdk-radius: 6px; } @layer app { .mdk-button--variant-primary { letter-spacing: 0.04em; } } ``` ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## Import ```tsx // Import tokens // Import utilities getSystemTheme, applyTheme, getStoredTheme, setStoredTheme, } from '@tetherto/mdk-react-devkit/core' // Import types ``` ## Design tokens ### Colors Primary and gray color scales with 10 shades each (50-900). ```tsx colors.primary[500] // 'hsl(222, 47%, 50%)' colors.gray[900] // 'hsl(222, 47%, 11%)' ``` #### Primary scale | Token | Value | Usage | |-------|-------|-------| | `primary.50` | `hsl(222, 47%, 95%)` | Lightest background | | `primary.100` | `hsl(222, 47%, 90%)` | Light background | | `primary.200` | `hsl(222, 47%, 80%)` | Hover states | | `primary.300` | `hsl(222, 47%, 70%)` | Borders | | `primary.400` | `hsl(222, 47%, 60%)` | Secondary text | | `primary.500` | `hsl(222, 47%, 50%)` | Primary color | | `primary.600` | `hsl(222, 47%, 40%)` | Hover on primary | | `primary.700` | `hsl(222, 47%, 30%)` | Active states | | `primary.800` | `hsl(222, 47%, 20%)` | Dark backgrounds | | `primary.900` | `hsl(222, 47%, 11.2%)` | Darkest | #### Gray scale | Token | Value | Usage | |-------|-------|-------| | `gray.50` | `hsl(210, 40%, 98%)` | Page background | | `gray.100` | `hsl(210, 40%, 96.1%)` | Card background | | `gray.200` | `hsl(214, 32%, 91.4%)` | Borders | | `gray.300` | `hsl(213, 27%, 84.1%)` | Dividers | | `gray.400` | `hsl(215, 20%, 65.1%)` | Placeholder text | | `gray.500` | `hsl(215, 16%, 47%)` | Secondary text | | `gray.600` | `hsl(215, 19%, 35%)` | Body text | | `gray.700` | `hsl(215, 25%, 27%)` | Headings | | `gray.800` | `hsl(217, 33%, 17%)` | Dark mode card | | `gray.900` | `hsl(222, 47%, 11%)` | Dark mode `bg` | ### Spacing Consistent spacing scale for margins, padding, and gaps. ```tsx spacing[4] // '1rem' (16px) spacing[8] // '2rem' (32px) ``` | Token | Value | Pixels | |-------|-------|--------| | `0` | `0` | 0px | | `1` | `0.25rem` | 4px | | `2` | `0.5rem` | 8px | | `3` | `0.75rem` | 12px | | `4` | `1rem` | 16px | | `5` | `1.25rem` | 20px | | `6` | `1.5rem` | 24px | | `8` | `2rem` | 32px | | `10` | `2.5rem` | 40px | | `12` | `3rem` | 48px | | `16` | `4rem` | 64px | | `20` | `5rem` | 80px | | `24` | `6rem` | 96px | ### Border radius Border radius scale for rounded corners. ```tsx borderRadius.md // '0.375rem' borderRadius.full // '9999px' ``` | Token | Value | |-------|-------| | `none` | `0` | | `sm` | `0.125rem` | | `DEFAULT` | `0.25rem` | | `md` | `0.375rem` | | `lg` | `0.5rem` | | `xl` | `0.75rem` | | `2xl` | `1rem` | | `full` | `9999px` | ### Font size Font size scale for typography. ```tsx fontSize.base // '1rem' fontSize.lg // '1.125rem' ``` | Token | Value | |-------|-------| | `xs` | `0.75rem` | | `sm` | `0.875rem` | | `base` | `1rem` | | `lg` | `1.125rem` | | `xl` | `1.25rem` | | `2xl` | `1.5rem` | | `3xl` | `1.875rem` | | `4xl` | `2.25rem` | | `5xl` | `3rem` | ## Theme utilities ### Theme type ```tsx type Theme = 'light' | 'dark' | 'system' ``` ### `getSystemTheme` Get the user's system theme preference. ```tsx const systemTheme = getSystemTheme() // 'light' or 'dark' ``` ### `applyTheme` Apply a theme to the document root. ```tsx applyTheme('dark') // Sets dark mode applyTheme('light') // Sets light mode applyTheme('system') // Uses system preference ``` This function: - Removes existing `light`/`dark` classes from `<html>` - Adds the resolved theme class - Sets the `color-scheme` CSS property ### `getStoredTheme` Get the stored theme from `localStorage`. ```tsx const storedTheme = getStoredTheme() // Theme | null const customKey = getStoredTheme('my-theme-key') ``` ### `setStoredTheme` Store the theme in `localStorage`. ```tsx setStoredTheme('dark') setStoredTheme('light', 'my-theme-key') // Custom storage key ``` ## Usage example ```tsx applyTheme, getStoredTheme, setStoredTheme, getSystemTheme, } from '@tetherto/mdk-react-devkit/core' function ThemeProvider({ children }) { const [theme, setTheme] = useState<Theme>(() => { return getStoredTheme() || 'system' }) useEffect(() => { applyTheme(theme) setStoredTheme(theme) }, [theme]) return ( <ThemeContext.Provider value={{ theme, setTheme }}> {children} </ThemeContext.Provider> ) } ``` ## CSS custom properties The theme system uses CSS custom properties that can be overridden: ```css :root { --mdk-color-primary: #f7931a; --mdk-color-background: hsl(210, 40%, 98%); --mdk-color-foreground: hsl(222, 47%, 11%); /* ... more properties */ } .dark { --mdk-color-background: hsl(222, 47%, 11%); --mdk-color-foreground: hsl(210, 40%, 98%); } ``` # @tetherto/mdk-react-devkit (/reference/ui/react/foundation) The [foundation entrypoint](/support/resources/repositories) (`@tetherto/mdk-react-devkit/foundation`) provides **domain-specific React components, hooks, and constants** assembled from [`@tetherto/mdk-react-devkit/core`](/reference/ui/react/core). These are higher-level blocks for common Bitcoin mining application use cases. <Callout type="info"> Generic primitives (buttons, tables, charts) import from [`/core`](/reference/ui/react/core). Both subpaths ship from `@tetherto/mdk-react-devkit`. Connected foundation components expect `<MdkProvider>` from [`@tetherto/mdk-react-adapter`](/tutorials/ui/react) and adapter store hooks. </Callout> ## Prerequisites - Complete the installation <Accordions> <Accordion title="Show steps"> ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` </Accordion> </Accordions> - Add the dependency to your app's `package.json` <Tabs> <Tab value="workspace" label="Monorepo workspace" default> ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` </Tab> <Tab value="npm" label="🚧 Registry install"> > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` </Tab> </Tabs> Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. ## What's included | Feature | Description | |---------|-------------| | [Operations centre](/reference/ui/react/foundation/operations) | Bitcoin mining operations monitoring and management components | | [Reporting tool](/reference/ui/react/foundation/reporting) | Operational reporting surfaces | | [Settings](/reference/ui/react/foundation/settings) | Administrative settings views | | [Hooks](#hooks) | Reusable React hooks | | [Constants](#constants) | Shared constants and configurations | ### Operations centre Domain-specific components for Bitcoin mining operations monitoring and management, including device explorers, vendor container UIs, dashboard widgets, charts, pool management, and data export. See the [operations centre reference](/reference/ui/react/foundation/operations) for the full component list with demo links. ### Settings Pre-built settings UI for common administrative tasks: - [`SettingsDashboard`](/reference/ui/react/foundation/settings): main settings container with accordion sections - [`FeatureFlagsSettings`](/reference/ui/react/foundation/settings/feature-flags): toggle feature flags on/off - [`HeaderControlsSettings`](/reference/ui/react/foundation/settings/header-controls): configure header display options - [`ImportExportSettings`](/reference/ui/react/foundation/settings/import-export): import/export configuration data - [`RBACControlSettings`](/reference/ui/react/foundation/settings/access-control): role-based access control settings - [User management modals](/reference/ui/react/foundation/settings/user-management): add, manage, and confirm user changes ### Hooks Reusable React hooks for [notifications and shell layout](/reference/app-toolkit/hooks/components#notifications) and [chart/dashboard transforms](/reference/app-toolkit/hooks/components#charts) — see the full [Hooks reference](/reference/app-toolkit/hooks). ### Constants Shared [constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants) for consistency across your application: permission definitions, role configurations, settings defaults, and error codes. ## Import examples ```tsx // Import components // Import from domain subpath when you only need settings-domain exports ``` ## Next steps Consider the detailed [reference material](/reference) for the foundation entrypoint: - [Constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants): permissions, roles, header controls, settings error codes - [Hooks: Components](/reference/app-toolkit/hooks/components) and [Hooks: Utilities > Domain transforms](/reference/app-toolkit/hooks/utilities#domain-transforms) - [Types](/reference/app-toolkit/ui-devkit/types#foundation-types): [`Device`](/reference/app-toolkit/ui-devkit/types#device), [`Container`](/reference/app-toolkit/ui-devkit/types#container), [`Alert`](/reference/app-toolkit/ui-devkit/types#alert), [`MinerStats`](/reference/app-toolkit/ui-devkit/types#minerstats), settings shapes - [Utilities](/reference/app-toolkit/ui-devkit/utilities#foundation-utilities): `settings-utils` (filtering, formatting, import/export) # Alerts (/reference/ui/react/foundation/alerts) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> Alerts components cover the full alarm surface: `AlarmsBellButton` in the app header, the `Alerts` feature composite (current and historical tabs), and the standalone `HistoricalAlerts` table. Pair with the [dashboard](/reference/ui/react/foundation/dashboard) for live context. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - Wrap your app in `<MdkProvider>` — see [foundation prerequisites](/reference/ui/react/foundation#prerequisites) ## Components <ComponentTable category="Alerts" pkg="foundation" /> ### `AlarmsBellButton` <ComponentDescription name="AlarmsBellButton" /> Header bell button that renders severity-bucketed alarm counts in a stacked badge. Typically placed in the [`AppHeader`](/reference/ui/react/core/components/navigation#appheader) actions cluster. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `counts` | Optional | `AlarmsBellButtonCounts` | none | Severity-bucketed alarm counts rendered in the stacked badge | | `onClick` | Optional | `(event: React.MouseEvent<HTMLButtonElement>) => void` | none | Click handler — typically opens an alerts panel or routes to `/alerts` | | `onSeverityClick` | Optional | `(severity: AlarmSeverity, event: React.MouseEvent<HTMLButtonElement>) => void` | none | Click handler for an individual severity count; when provided, each badge row becomes its own button | | `label` | Optional | `string` | `'Active alarms'` | Accessible label | | `className` | Optional | `string` | none | Root class name from the host app | #### Basic usage ```tsx <AlarmsBellButton counts={{ critical: 171, high: 72, medium: 322 }} /> <AlarmsBellButton counts={{ critical: 2, high: 5 }} onSeverityClick={(severity) => router.push(`/alerts?severity=${severity}`)} /> ``` ### `Alerts` <ComponentDescription name="Alerts" /> Full-page alerts surface that wraps [`CurrentAlerts`](#currentalerts) and (when `isHistoricalAlertsEnabled`) [`HistoricalAlerts`](#historicalalerts), coordinating their shared filter state, date range, and alert click handling. It manages: 1. **Current alerts** (`devices`, `isCurrentAlertsLoading`): raw devices payload and loading flag passed to `CurrentAlerts`. 2. **Historical alerts** (`historicalAlerts`, `isHistoricalAlertsLoading`, `isHistoricalAlertsEnabled`): log data and visibility toggle. 3. **Filtering** (`selectedAlertId`, `initialSeverity`, `typeFiltersForSite`): deep-link focus, severity pre-selection, and site type filters. 4. **Callbacks** (`onAlertClick`, `onDateRangeChange`): row navigation and date range updates. 5. **Sound** (`isSoundEnabled`, `isDemoMode`): critical-alert beep toggle and demo/preview mode. 6. **Layout** (`header`, `className`): optional header slot and root class. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `devices` | Optional | `Device[][]` | none | Raw devices payload for current alerts (see [`useCurrentAlertDevices`](/reference/app-toolkit/hooks/data#usecurrentalertdevices)) | | `isCurrentAlertsLoading` | Optional | `boolean` | `false` | When `true`, shows the loading state in `CurrentAlerts` | | `historicalAlerts` | Optional | `Alert[]` | none | Pre-fetched historical alerts (see [`useHistoricalAlerts`](/reference/app-toolkit/hooks/data#usehistoricalalerts)) | | `isHistoricalAlertsLoading` | Optional | `boolean` | `false` | When `true`, shows the loading state in `HistoricalAlerts` | | `isHistoricalAlertsEnabled` | Optional | `boolean` | `false` | When `true`, renders the historical alerts log section | | `selectedAlertId` | Optional | `string` | none | Focuses the table on a single alert (deep-link from URL) | | `initialSeverity` | Optional | `string` | none | Pre-selects a severity filter (typically from a `?severity=` URL param) | | `onAlertClick` | Optional | `function` | none | Called with device `id` and alert `uuid` when the user opens an alert row | | `onDateRangeChange` | Optional | `function` | none | Called when the user picks a new date range in the historical log | | `dateRange` | Optional | `HistoricalAlertsRange` | last 14 days | Controlled date range (`{ start: number, end: number }` in ms) | | `isSoundEnabled` | Optional | `boolean` | `false` | Enables the critical-alert audible beep when a critical alert is present | | `isDemoMode` | Optional | `boolean` | `false` | When `true`, skips sound notifications (safe for preview environments) | | `typeFiltersForSite` | Optional | `CascaderOption[]` | none | Site-specific overrides for the `TagFilterBar` type filter | | `header` | Optional | `ReactNode` | none | Optional header (e.g. breadcrumbs) rendered above the alerts tables | | `className` | Optional | `string` | none | Root class name from the host app | #### Hook integration Wire `Alerts` with the MDK adapter hooks for live data (see [`useCurrentAlertDevices`](/reference/app-toolkit/hooks/data#usecurrentalertdevices) and [`useHistoricalAlerts`](/reference/app-toolkit/hooks/data#usehistoricalalerts)): ```tsx function AlertsPage() { const { filterTags } = useDevices() const devices = useCurrentAlertDevices({ filterTags }) const [range, setRange] = useState(() => getDefaultHistoricalAlertsRange()) const historical = useHistoricalAlerts(range) return ( <Alerts devices={devices.data} isCurrentAlertsLoading={devices.isLoading} historicalAlerts={historical.data} isHistoricalAlertsLoading={historical.isLoading} isHistoricalAlertsEnabled dateRange={range} onDateRangeChange={setRange} onAlertClick={(id, uuid) => router.push(`/alerts/${uuid}`)} /> ) } ``` <Callout type="tip">See [`useCurrentAlertDevices`](/reference/app-toolkit/hooks/data#usecurrentalertdevices) and [`useHistoricalAlerts`](/reference/app-toolkit/hooks/data#usehistoricalalerts) for hook options.</Callout> ### `CurrentAlerts` <ComponentDescription name="CurrentAlerts" /> Sortable, searchable data table of active alerts derived from a raw devices payload. Plays an audible beep when a critical alert is present and sound notifications are enabled — after the user confirms via [`AlertConfirmationModal`](#alertconfirmationmodal). The [`Alerts`](#alerts) feature wrapper manages all state for most use cases; use `CurrentAlerts` directly when you need a standalone current-alerts table. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `localFilters` | Required | `AlertLocalFilters` | none | Controlled filter state shared with other alerts components (see [type](#alertlocalfilters-type)) | | `onLocalFiltersChange` | Required | `function` | none | Called with the updated `AlertLocalFilters` when filters change | | `filterTags` | Required | `string[]` | none | Active search tags; mirrors the devices-store tag slice | | `onFilterTagsChange` | Required | `function` | none | Called with updated tags when the user adds or removes a search chip | | `devices` | Optional | `Device[][]` | none | Raw devices payload; drives alert row derivation | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows the table loading state | | `selectedAlertId` | Optional | `string` | none | Focuses the table on a single alert | | `onAlertClick` | Optional | `function` | none | Called with device `id` and alert `uuid` when the user opens an alert row | | `isSoundEnabled` | Optional | `boolean` | `false` | Enables the critical-alert audible beep | | `isDemoMode` | Optional | `boolean` | `false` | When `true`, skips sound notifications | | `typeFiltersForSite` | Optional | `CascaderOption[]` | none | Site-specific overrides for the type filter in `TagFilterBar` | | `className` | Optional | `string` | none | Root class name from the host app | #### `AlertLocalFilters` type ```tsx type AlertLocalFilters = { severity?: string[] | string status?: string[] type?: string[] id?: string[] thing?: { id?: string } [key: string]: unknown } ``` #### Basic usage ```tsx function AlertsView({ devices, isLoading }) { const [localFilters, setLocalFilters] = useState<AlertLocalFilters>({}) const [filterTags, setFilterTags] = useState<string[]>([]) return ( <CurrentAlerts devices={devices} isLoading={isLoading} localFilters={localFilters} onLocalFiltersChange={setLocalFilters} filterTags={filterTags} onFilterTagsChange={setFilterTags} onAlertClick={(id, uuid) => console.log('Alert clicked', id, uuid)} /> ) } ``` ### `HistoricalAlerts` <ComponentDescription name="HistoricalAlerts" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `alerts` | Optional | `Alert[]` | `[]` | Pre-fetched historical alert entries | | `isLoading` | Optional | `boolean` | `false` | Show table loading state | | `localFilters` | Required | `AlertLocalFilters` | none | Filters and search state shared with `CurrentAlerts` | | `filterTags` | Required | `string[]` | none | Active filter tags | | `dateRange` | Required | `HistoricalAlertsRange` | none | Controlled start/end timestamps (ms) | | `onDateRangeChange` | Required | `function` | none | Fires when the user picks a new range | | `onAlertClick` | Optional | `function` | none | Row click handler | | `className` | Optional | `string` | none | Additional CSS class | #### `HistoricalAlertsRange` type ```tsx type HistoricalAlertsRange = { start: number end: number } ``` #### Basic usage ```tsx <HistoricalAlerts alerts={historicalAlerts} localFilters={localFilters} filterTags={filterTags} dateRange={{ start: rangeStart, end: rangeEnd }} onDateRangeChange={({ start, end }) => setRange({ start, end })} onAlertClick={(id, uuid) => console.log('Alert clicked', id, uuid)} /> ``` #### Loading state ```tsx <HistoricalAlerts alerts={[]} isLoading localFilters={localFilters} filterTags={filterTags} dateRange={dateRange} onDateRangeChange={onDateRangeChange} /> ``` #### Behavior notes - The component wires a `DateRangePicker` into the table title via `AlertsTableTitle`, so date range changes come back through `onDateRangeChange`. - Rows are sorted by severity (descending) then creation date (descending) by default - Timestamps are formatted through `useTimezoneFormatter()`'s `getFormattedDate` ### `TagFilterBar` <ComponentDescription name="TagFilterBar" /> Strip of removable filter chips and a tag-input search field for narrowing the alerts table by severity, status, type, and device tags. Used as the subtitle slot of [`AlertsTableTitle`](#alertstabletitle) inside [`CurrentAlerts`](#currentalerts). #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `filterTags` | Required | `string[]` | none | Active search tag chips | | `localFilters` | Required | `AlertLocalFilters` | none | Controlled filter state (severity, status, type) | | `onSearchTagsChange` | Required | `function` | none | Called with updated tags when the user adds or removes a chip | | `onLocalFiltersChange` | Required | `function` | none | Called with updated `AlertLocalFilters` when a cascader selection changes | | `typeFiltersForSite` | Optional | `CascaderOption[]` | default filter list | Site-specific overrides for the "Type" cascader children | | `placeholder` | Optional | `string` | none | Placeholder text for the tag-input field | | `className` | Optional | `string` | none | Root class name from the host app | #### Basic usage ```tsx <TagFilterBar filterTags={filterTags} localFilters={localFilters} onSearchTagsChange={setFilterTags} onLocalFiltersChange={setLocalFilters} /> ``` ### `AlertsTableTitle` <ComponentDescription name="AlertsTableTitle" /> Heading strip for an alerts table — renders the section title and an optional subtitle slot (typically used for `TagFilterBar` or `DateRangePicker`). Used internally by [`CurrentAlerts`](#currentalerts) and [`HistoricalAlerts`](#historicalalerts). #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `title` | Required | `ReactNode` | none | Section heading content | | `subtitle` | Optional | `ReactNode` | none | Optional content rendered below the title (e.g. `TagFilterBar` or `DateRangePicker`) | | `className` | Optional | `string` | none | Root class name from the host app | #### Basic usage ```tsx <AlertsTableTitle title="Current Alerts" subtitle={ <TagFilterBar filterTags={filterTags} localFilters={localFilters} onSearchTagsChange={setFilterTags} onLocalFiltersChange={setLocalFilters} /> } /> ``` ### `AlertConfirmationModal` <ComponentDescription name="AlertConfirmationModal" /> One-time consent dialog that appears before critical-alert sound notifications are activated. Renders a non-dismissible `Dialog` with an "Understood" button. Once confirmed (tracked in `sessionStorage`), `CurrentAlerts` begins playing the beep. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `isOpen` | Required | `boolean` | none | Controls modal visibility | | `onOk` | Required | `function` | none | Called when the user clicks "Understood" | #### Basic usage ```tsx <AlertConfirmationModal isOpen={showConfirmation} onOk={() => setShowConfirmation(false)} /> ``` ### `AlarmContents` <ComponentDescription name="AlarmContents" /> Building block of the alarm card — renders the body region with the alert details and recommended next actions. Compose it inside your own card chrome when you need a custom alarm layout. #### Import ```tsx ``` ### `AlarmRow` <ComponentDescription name="AlarmRow" /> Building block of the alarm feed — a single row with a severity dot, timestamp, source device, and the alert message. Map your alert list to a stack of `AlarmRow`s for a custom feed. #### Import ```tsx ``` ## Next steps - For live incident context, see [`ActiveIncidentsCard`](/reference/ui/react/foundation/dashboard/feeds#activeincidentscard) on the dashboard Feeds page - For alert data hooks, see [`useCurrentAlertDevices`](/reference/app-toolkit/hooks/data#usecurrentalertdevices) and [`useHistoricalAlerts`](/reference/app-toolkit/hooks/data#usehistoricalalerts) # Dashboard (/reference/ui/react/foundation/dashboard) The dashboard is the top-level operations surface. It composes live feeds, summary widgets, and chart cards into a single overview of fleet health, pool context, and power trends. The docs group these components into three intuitive buckets: - [Feeds](/reference/ui/react/foundation/dashboard/feeds): active incidents and activity logs - [Stats](/reference/ui/react/foundation/dashboard/stats): at-a-glance summary cards for containers, pool details, and export controls - [Charts](/reference/ui/react/foundation/dashboard/charts): line, timeline, and multi-series chart cards ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## All dashboard components <ComponentTable category="Dashboard" pkg="foundation" /> ## Next steps For past alerts paired with the dashboard's active-incidents view, see [`HistoricalAlerts`(../alerts#historicalalerts). # Charts (/reference/ui/react/foundation/dashboard/charts) Chart components specialized for Bitcoin mining operations data visualization, including hashrate trends, power consumption, power mode timelines, and multi-container comparisons. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ### `ChartWrapper` <ComponentDescription name="ChartWrapper" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `children` | Optional | `ReactNode` | none | Chart content rendered when data is present | | `data` | Optional | `object \| array` | none | Chart data for LineChart-style datasets; used by `useChartDataCheck` | | `dataset` | Optional | `object \| array` | none | Chart dataset for BarChart-style data; used by `useChartDataCheck` | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows the loading overlay with default `<Loader />` (animated dots) or `customLoader`, and hides chart children | | `showNoDataPlaceholder` | Optional | `boolean` | `true` | When `true`, shows empty placeholder when data/dataset has no values | | `customLoader` | Optional | `ReactNode` | `<Loader />` | Node shown in the loading overlay (default core `Loader`) | | `customNoDataMessage` | Optional | `string \| ReactNode` | none | Custom empty state message or component | | `minHeight` | Optional | `number` | `400` | Minimum height in pixels for empty state | | `loadingMinHeight` | Optional | `number` | `minHeight` | Minimum height in pixels for the loading overlay (default `<Loader />` or `customLoader`) | | `className` | Optional | `string` | none | Root class name from the host app | Chart children (`LineChart`, `BarChart`) come from `@tetherto/mdk-react-devkit/core`. ```tsx const CustomSpinner = () => <div className="my-spinner" aria-hidden /> ``` #### Basic usage ```tsx <ChartWrapper data={chartData} isLoading={isLoading} minHeight={400} > <LineChart data={chartData} /> </ChartWrapper> ``` #### With custom loader ```tsx <ChartWrapper data={chartData} isLoading={isLoading} customLoader={<CustomSpinner />} minHeight={300} > <LineChart data={chartData} /> </ChartWrapper> ``` #### With custom empty message Pass an empty dataset so `ChartWrapper` shows the empty placeholder instead of the chart. With non-empty `dataset`, children render and the custom message is not shown. ```tsx const emptyBarData = { labels: [], datasets: [] } <ChartWrapper dataset={emptyBarData} isLoading={false} customNoDataMessage="No hashrate data available for this period" minHeight={300} > <BarChart data={emptyBarData} /> </ChartWrapper> ``` #### States The component handles three states automatically. Chart **children** are hidden while `isLoading` is `true` or when `data` / `dataset` is empty (and `showNoDataPlaceholder` is `true`): 1. **Loading**: Shows default `<Loader />` (animated dots) or `customLoader` 2. **No data**: Shows `EmptyState` placeholder (or `customNoDataMessage`) 3. **Has data**: Shows chart content #### Styling - `.mdk-chart-wrapper`: Root element - `.mdk-chart-wrapper__content`: Chart content container - `.mdk-chart-wrapper__content--hidden`: Hidden content state - `.mdk-chart-wrapper__empty`: Empty state container - `.mdk-chart-wrapper__loading`: Loading state container ### `ContainerCharts` <ComponentDescription name="ContainerCharts" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `featureEnabled` | Optional | `boolean` | `true` | When `false`, shows `disabledMessage` instead of charts | | `combinations` | Required | \{ value: string; label: string \}[] | none | Select options (`value` / `label` pairs) | | `chartRawData` | Optional | `ChartEntry[]` | `null` | Raw time-series rows; shape depends on selected container type | | `selectedCombination` | Optional | `string \| null` | none | Controlled selected `combinations[].value` | | `defaultSelectedCombination` | Optional | `string \| null` | `null` | Initial selection when uncontrolled | | `onSelectedCombinationChange` | Optional | `function` | none | Called with the new combination `value` (or `null`) when the user changes selection | | `isLoadingCombinations` | Optional | `boolean` | `false` | When `true`, shows loading state on the combination selector | | `isLoadingCharts` | Optional | `boolean` | `false` | When `true`, shows loading state on the chart grid | | `disabledMessage` | Optional | `string` | `'Container Charts feature is not enabled'` | Message when `featureEnabled` is `false` | | `title` | Optional | `string` | `'Container Charts'` | Section heading | | `getDatasetBorderColor` | Optional | `function` | none | Resolver for dataset border colors; receives dataset metadata from the builder | #### `ChartEntry` type ```tsx type EntryData = { [key: string]: number | null | undefined } type ChartEntry = { ts: number | string container_specific_stats_group_aggr: Record<string, EntryData | null | undefined> } ``` Each row’s `container_specific_stats_group_aggr` keys use complete container type ids (for example `container-bd-d40-m30`, `container-as-hk3`). Stat field names inside each entry depend on the container family. **Bitdeer** (`container-bd-…` keys) — field names per chart block: | Chart block | Stat field pattern | |-------------|-------------------| | Liquid Temp H | `hot_temp_c_w_{n}_group` | | Liquid Temp L | `cold_temp_c_w_{n}_group` | | Oil Temp | `cold_temp_c_{n}_group` (no `_w_`) | | Pressure | `tank{n}_bar_group` | **Hydro** (`container-as-hk3`): `supply_liquid_temp_group`, `supply_liquid_pressure_group`. Combination `value` strings must contain the real prefix patterns the component detects (`bd-…`, `as-hk3…`, `as-immersion…`, `mbt-…`). Values such as `bitmain_hydro_b2` (underscores) do not match `isAntspaceHydro()` and show the wrong chart blocks. ```tsx const chartData: ChartEntry[] = [ { ts: 1700000000, container_specific_stats_group_aggr: { 'container-bd-d40-m30': { hot_temp_c_w_1_group: 52, hot_temp_c_w_2_group: 54, cold_temp_c_w_1_group: 38, cold_temp_c_w_2_group: 39, cold_temp_c_1_group: 36, cold_temp_c_2_group: 37, tank1_bar_group: 2.4, tank2_bar_group: 2.5, }, 'container-as-hk3': { supply_liquid_temp_group: 44, supply_liquid_pressure_group: 2.8, }, }, }, ] ``` #### Basic usage ```tsx <ContainerCharts combinations={[ { value: 'bd-d40-m30_wm-m30sp', label: 'Bitdeer M30SP' }, { value: 'as-hk3_am-s19xp_h', label: 'Bitmain Hydro S19XP' }, ]} defaultSelectedCombination="bd-d40-m30_wm-m30sp" chartRawData={chartData} onSelectedCombinationChange={setSelected} /> ``` #### Container type charts Charts displayed vary by container type: - **Bitdeer**: Liquid Temp H, Liquid Temp L, Oil Temp, Pressure - **Bitmain Hydro**: Liquid Temp L, Pressure - **Bitmain Immersion**: Liquid Temp L, Oil Temp - **MicroBT**: Liquid Temp L, Pressure #### Styling - `.mdk-container-charts`: Root element - `.mdk-container-charts__title`: Section title - `.mdk-container-charts__select-row`: Combination selector row - `.mdk-container-charts__select-label`: Selector label - `.mdk-container-charts__select`: Select dropdown - `.mdk-container-charts__layout`: Charts grid layout - `.mdk-container-charts__chart-block`: Individual chart container - `.mdk-container-charts__chart-title`: Chart block title - `.mdk-container-charts__loading`: Loading state container ### `LineChartCard` <ComponentDescription name="LineChartCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `LineChartCardData` | none | Pre-processed chart payload passed to the inner line chart | | `rawData` | Optional | `unknown` | none | Raw API payload; use with `dataAdapter` instead of `data` | | `dataAdapter` | Optional | `function` | none | Maps `rawData` to `LineChartCardData` | | `timelineOptions` | Optional | `TimelineOption[]` | none | Timeline range buttons | | `timeline` | Optional | `string` | none | Controlled active timeline value | | `defaultTimeline` | Optional | `string` | `'5m'` | Initial timeline when uncontrolled | | `onTimelineChange` | Optional | `function` | none | Called when the user selects a new timeline range | | `title` | Optional | `string` | none | Chart title in the card header | | `titleExtra` | Optional | `ReactNode` | none | Node rendered inline beside the title — use for a secondary label or unit badge | | `headerAction` | Optional | `ReactNode` | none | Node rendered at the trailing edge of the header row — use for action buttons such as an expand toggle | | `detailLegends` | Optional | `boolean` | `false` | When `true`, shows detailed legends below the title | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows loading state | | `shouldResetZoom` | Optional | `boolean` | `true` | When `true`, resets chart zoom when the timeline changes | | `minHeight` | Optional | `number` | `350` | Minimum chart body height in pixels | | `className` | Optional | `string` | none | Root class name from the host app | #### Basic usage ```tsx <LineChartCard title="Temperature" data={chartData} timelineOptions={[ { label: '5m', value: '5m' }, { label: '1h', value: '1h' }, { label: '24h', value: '24h' }, ]} defaultTimeline="1h" /> ``` #### With data adapter ```tsx <LineChartCard title="Power Consumption" rawData={rawStats} dataAdapter={(raw) => processStatsToChartData(raw)} timelineOptions={timelineOptions} defaultTimeline="24h" isLoading={isLoading} /> ``` #### Styling - `.mdk-line-chart-card`: Root element - `.mdk-line-chart-card__legends`: Detail legends container ### `PowerModeTimelineChart` <ComponentDescription name="PowerModeTimelineChart" /> Mining-specific wrapper around [`TimelineChart`](#timelinechart). Use `TimelineChart` directly when you supply custom row labels and segment data. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `PowerModeTimelineEntry[]` | `[]` | Historical power mode segments for `TimelineChart` | | `dataUpdates` | Optional | `PowerModeTimelineEntry[]` | `[]` | New segments merged into the chart when updates arrive | | `timezone` | Optional | `string` | `'UTC'` | IANA timezone for segment timestamps | | `title` | Optional | `string` | `'Power Mode Timeline'` | Chart title passed to the inner timeline | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows loading state inside the chart card | #### `PowerModeTimelineEntry` type ```tsx type PowerModeTimelineEntry = { ts?: number power_mode_group_aggr?: Record<string, string> status_group_aggr?: Record<string, string> } ``` #### Basic usage ```tsx <PowerModeTimelineChart data={powerModeHistory} timezone="America/New_York" isLoading={isLoading} /> ``` #### With real-time updates ```tsx <PowerModeTimelineChart data={powerModeHistory} dataUpdates={realtimeUpdates} timezone={userTimezone} /> ``` ### `TimelineChart` <ComponentDescription name="TimelineChart" /> Gantt-like timeline for multiple rows. `labels` lists row names (Y axis). Each dataset groups colored segments; each segment's `y` must match one of `labels`, and `x` is `[startMs, endMs]`. #### Import ```tsx ``` #### Empty initial state Use `emptyTimelineChartData` (`{ labels: [], datasets: [] }`) for the first render before live timeline data arrives. Pair with `isLoading` while fetching if needed. ```tsx <TimelineChart initialData={emptyTimelineChartData} title="Miner state" isLoading={isLoading} /> ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `initialData` | Required | `TimelineChartData` | none | Row labels and segment datasets shown on first render | | `newData` | Optional | `TimelineChartData` | none | Extra labels and datasets merged when `skipUpdates` is false | | `skipUpdates` | Optional | `boolean` | `false` | When `true`, ignores `newData` | | `range` | Optional | `ChartRange` | none | Visible time window (`min` / `max` as `Date` or epoch ms) | | `axisTitleText` | Optional | `AxisTitleText` | `{ x: 'Time', y: '' }` | Axis title strings | | `isLoading` | Optional | `boolean` | `false` | Shows loading state inside `ChartContainer` | | `title` | Optional | `string` | none | Chart title passed to `ChartContainer` | | `height` | Optional | `number \| string` | none | Root height (CSS length or pixels) | #### `TimelineChartData` type See also [Timeline chart types](/reference/app-toolkit/ui-devkit/types#timeline-chart-types). ```tsx type TimelineChartDataPoint = { x: [number, number] // segment start and end (epoch ms) y: string | undefined // must match an entry in labels } type TimelineChartDataset = { label: string data: TimelineChartDataPoint[] borderColor?: string[] backgroundColor?: string[] color?: string } type TimelineChartData = { labels: string[] datasets: TimelineChartDataset[] } type ChartRange = { min: Date | number max: Date | number } ``` #### Basic usage ```tsx const start = Date.now() - 2 * 60 * 60 * 1000 <TimelineChart initialData={{ labels: ['Task A', 'Task B', 'Task C'], datasets: [ { label: 'In Progress', color: '#22afff', data: [ { x: [start, start + 30 * 60 * 1000], y: 'Task A' }, { x: [start + 20 * 60 * 1000, start + 50 * 60 * 1000], y: 'Task B' }, ], }, { label: 'Completed', color: '#72f59e', data: [{ x: [start + 30 * 60 * 1000, start + 60 * 60 * 1000], y: 'Task A' }], }, ], }} title="Project timeline" axisTitleText={{ x: 'Time', y: 'Tasks' }} /> ``` #### With `newData` updates ```tsx <TimelineChart initialData={baseline} newData={streamingUpdate} skipUpdates={false} /> ``` When `newData` arrives, labels are unioned and datasets are appended. Set `skipUpdates` to keep only `initialData`. #### Styling - `.mdk-timeline-chart`: Root element - `.mdk-timeline-chart__loading`: Loading container - `.mdk-timeline-chart__legend`, `.mdk-timeline-chart__legend-item`, `.mdk-timeline-chart__legend-color`, `.mdk-timeline-chart__legend-label`: Legend row - `.mdk-timeline-chart__visualization`: Scrollable chart body ### `WidgetTopRow` <ComponentDescription name="WidgetTopRow" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `title` | Required | `string` | none | Widget title shown in the header row | | `power` | Optional | `number` | none | Power consumption value; formatted with `unit` when set | | `unit` | Optional | `string` | none | Unit suffix for `power` (for example `kW`) | | `statsErrorMessage` | Optional | `string \| ErrorWithTimestamp[]` | none | Replaces the power readout with `-` and a `formatErrors` tooltip | | `alarms` | Optional | `object` | none | Map keyed by `liquidAlarms`, `leakageAlarms`, `pressureAlarms`, `otherAlarms`; values are [`Alert`](/reference/app-toolkit/ui-devkit/types#alert) arrays | | `className` | Optional | `string` | none | Root class name from the host app | #### Composition `WidgetTopRow` renders the title, then four fixed alarm slots in order (liquid, leakage, pressure, other), then the power readout. Each slot reads the matching `alarms` key from the table below; when the array is missing or empty, that slot is not shown. Tooltip text lists each [`Alert`](/reference/app-toolkit/ui-devkit/types#alert) with timestamp and description. | Slot label | `alarms` key | Icon role | |------------|--------------|-----------| | Liquid | `liquidAlarms` | Temperature / liquid alarm | | Leakage | `leakageAlarms` | Fluid / leakage alarm | | Pressure | `pressureAlarms` | Pressure alarm | | Other | `otherAlarms` | Other alarm | When `power` and `unit` are set and `statsErrorMessage` is unset, the power label shows `formatNumber(unitToKilo(power))` followed by the unit in a nested `<span>`. #### Basic usage ```tsx <WidgetTopRow title="Container A1" power={125000} unit="kW" /> ``` #### More examples <Accordions> <Accordion title="With alarms"> Each `alarms` key must match the table above (`liquidAlarms`, `leakageAlarms`, `pressureAlarms`, `otherAlarms`), not generic names like `temperature`. Items use the [`Alert`](/reference/app-toolkit/ui-devkit/types#alert) shape. ```tsx <WidgetTopRow title="Container A1" power={125000} unit="kW" alarms={{ liquidAlarms: [ { severity: 'critical', createdAt: Date.now(), name: 'Al.Liq.#1', description: '1st Liquid Alarm', }, ], leakageAlarms: [ { severity: 'high', createdAt: Date.now(), name: 'Al.Lkg.#1', description: '1st Leakage Alarm', }, ], pressureAlarms: [ { severity: 'medium', createdAt: Date.now(), name: 'Al.Prs.#1', description: '1st Pressure Alarm', }, ], otherAlarms: [ { severity: 'low', createdAt: Date.now(), name: 'Al.Oth.#1', description: '1st Other Alarm', }, ], }} /> ``` </Accordion> <Accordion title="With stats error"> When `statsErrorMessage` is set, the power label is hidden and `-` is shown with a tooltip built from `formatErrors` (string or [`ErrorWithTimestamp`](/reference/app-toolkit/ui-devkit/types#errorwithtimestamp) array). ```tsx <WidgetTopRow title="Container A1" statsErrorMessage="Example Error Message" /> ``` </Accordion> </Accordions> #### Styling - `.mdk-widget-top-row`: Root element - `.mdk-widget-top-row__inner`: Inner container - `.mdk-widget-top-row__title`: Title text - `.mdk-widget-top-row__alarm-info-icon`: Alarm slot icon (tooltip trigger) - `.mdk-widget-top-row__alarm-info-title`: Alarm tooltip heading (`{slot} issues`) - `.mdk-widget-top-row__power`: Power display or error placeholder ## Related hooks The following adapter and component hooks supply data to the chart components on this page. | Hook | Supplies | |------|---------| | [`useHashrateChartData`](/reference/app-toolkit/hooks/data#usehashratechartdata) | `ChartCardData` combining site and per-pool hashrate series for `<LineChartCard />` | | [`useSiteConsumptionChartData`](/reference/app-toolkit/hooks/data#usesiteconsumptionchartdata) | Consumption `ChartCardData` in MW for `<LineChartCard />` | | [`usePowerModeTimelineData`](/reference/app-toolkit/hooks/data#usepowermodetimelinedata) | `PowerModeTimelineEntry[]` for `<PowerModeTimelineChart />` | | [`useChartDataCheck`](/reference/app-toolkit/hooks/components#usechartdatacheck) | Empty-state guard used by `<ChartWrapper />` to decide when to render the no-data placeholder | # Feeds (/reference/ui/react/foundation/dashboard/feeds) Feeds surface streams of operational events on the dashboard. `ActiveIncidentsCard` renders the current alerts feed; `LogsCard` (from `@tetherto/mdk-react-devkit/core`) renders activity and event logs. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ### `ActiveIncidentsCard` <ComponentDescription name="ActiveIncidentsCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `string` | `'Active Alerts'` | Card header label | | `items` | Optional | `TIncidentRowProps[]` | `[]` | Array of incident items to display | | `isLoading` | Optional | `boolean` | `false` | Show skeleton loading state | | `skeletonRows` | Optional | `number` | `4` | Number of skeleton rows when loading | | `emptyMessage` | Required | `string` | none | Message when no incidents | | `onItemClick` | Required | `function` | none | Callback when an incident row is clicked | | `className` | Optional | `string` | none | Additional CSS class | #### `TIncidentRowProps` Each incident item requires these properties: | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `id` | Optional | `string` | none | Unique incident identifier | | `title` | Required | `string` | none | Incident title | | `subtitle` | Required | `string` | none | Secondary text (e.g., timestamp or source) | | `body` | Required | `string` | none | Incident description | | `severity` | Required | `'critical' \| none | 'high' \| 'medium'` | Severity level | #### Basic usage ```tsx <ActiveIncidentsCard label="Active Alerts" items={[ { id: '1', title: 'High Temperature Alert', subtitle: 'Miner #A2341', body: 'Temperature exceeded 85°C threshold', severity: 'critical', }, { id: '2', title: 'Network Connection Lost', subtitle: 'Pool: pool.example.com', body: 'Connection timeout after 30 seconds', severity: 'high', }, ]} onItemClick={(id) => console.log('Clicked:', id)} /> ``` #### Loading state ```tsx <ActiveIncidentsCard label="Active Alerts" isLoading skeletonRows={4} /> ``` #### Empty state ```tsx <ActiveIncidentsCard label="Active Alerts" items={[]} emptyMessage="No active incidents" /> ``` #### Styling - `.mdk-active-incidents-card`: Root element - `.mdk-active-incidents-card__header`: Header container - `.mdk-active-incidents-card__label`: Header label text - `.mdk-active-incidents-card__list`: Incidents list container - `.mdk-active-incidents-card__row`: Individual incident row - `.mdk-active-incidents-card__row--clickable`: Clickable row modifier - `.mdk-active-incidents-card__row-title`: Incident title - `.mdk-active-incidents-card__row-subtitle`: Incident subtitle - `.mdk-active-incidents-card__row-body`: Incident body text - `.mdk-active-incidents-card__empty`: Empty state container - `.mdk-active-incidents-card__skeleton-container`: Loading skeleton container ### `LogsCard` [`LogsCard`](/reference/ui/react/core/components/logs#logscard) is a `@tetherto/mdk-react-devkit/core` component used on the dashboard to render paginated activity and event log feeds.. Import from `@tetherto/mdk-react-devkit/core`: ```tsx ``` ## Related hooks | Hook | Supplies | |------|---------| | [`useActiveIncidents`](/reference/app-toolkit/hooks/data#useactiveincidents) | Returns `IncidentRow[]` ready for `<ActiveIncidentsCard items={...} />` | ## Next steps For past alerts to pair with the active incidents feed, see [`HistoricalAlerts`](/reference/ui/react/foundation/alerts#historicalalerts). # Stats (/reference/ui/react/foundation/dashboard/stats) Stat widgets are the compact, at-a-glance cards that line the dashboard. They summarize container health, pool configuration, liquid supply, tanks, miner roll-ups, and export controls. For the persistent app header bar components (HeaderStatsBar, HeaderConsumptionBox, etc.) see [Settings › Header controls › Header items](/reference/ui/react/foundation/settings/header-controls/header-items). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - Most widgets expect a container [`Device`](/reference/app-toolkit/ui-devkit/types#device) record; read the individual Props sections for field shapes - In TypeScript, import the type from the foundation barrel: `import type { Device } from '@tetherto/mdk-react-devkit/foundation'`. Snippet fixtures may be plain objects that satisfy `Device` without an import ## Supported widgets | Scope | Components | |-------|------------| | All vendors | [`MinersSummaryBox`](./generic-widgets#minerssummarybox), [`PoolDetailsCard`](./generic-widgets#pooldetailscard), [`PoolDetailsPopover`](./generic-widgets#pooldetailspopover), [`StatsExport`](./generic-widgets#statsexport), [`SupplyLiquidBox`](./generic-widgets#supplyliquidbox), [`TanksBox`](./generic-widgets#tanksbox) | | Bitmain Immersion | [`BitMainImmersionSummaryBox`](./bitmain#bitmainimmersionsummarybox) | | MicroBT | [`MicroBTWidgetBox`](./microbt#microbtwidgetbox) | ## Widget groups - [Generic widgets](./generic-widgets): vendor-agnostic summary cards for containers, pool details, and data export - [Bitmain](./bitmain): summary widget for Bitmain Immersion containers - [MicroBT](./microbt): summary widget for MicroBT containers ## All stat components <ComponentTable category="Dashboard" subcategory="Generic widgets" pkg="foundation" /> <ComponentTable category="Dashboard" subcategory="Bitmain" pkg="foundation" /> <ComponentTable category="Dashboard" subcategory="MicroBT" pkg="foundation" /> # Bitmain (/reference/ui/react/foundation/dashboard/stats/bitmain) Summary widget for Bitmain Immersion containers. For other vendor widgets see [MicroBT](/reference/ui/react/foundation/dashboard/stats/microbt). For vendor-agnostic cards see [Generic widgets](/reference/ui/react/foundation/dashboard/stats/generic-widgets). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - A [`Device`](/reference/app-toolkit/ui-devkit/types#device) record of type `bitmain-immersion` ## Components <ComponentTable category="Dashboard" subcategory="Bitmain" pkg="foundation" /> ### `BitMainImmersionSummaryBox` <ComponentDescription name="BitMainImmersionSummaryBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `Device` | none | Bitmain immersion container device record; returns `null` when omitted | | `containerSettings` | Optional | `BitMainImmersionSummaryBoxContainerSettings \| null` | `null` | Custom temperature thresholds passed to immersion color helpers | #### `BitMainImmersionSummaryBoxContainerSettings` type ```tsx type BitMainImmersionSummaryBoxContainerSettings = { thresholds?: Record<string, unknown> } ``` ```tsx const immersionContainer: Device = { id: 'bitmain-immersion-1', type: 'bitmain-immersion', last: { snap: { stats: { status: 'running', container_specific: { second_supply_temp1: 40, second_supply_temp2: 41, primary_supply_temp: 42, second_pump1: true, second_pump2: true, second_pump1_fault: false, second_pump2_fault: false, one_pump: true, }, }, }, }, } const customThresholds = { oilTemperature: { COLD: 30, LIGHT_WARM: 34, WARM: 38, HOT: 42, SUPERHOT: 45, }, } ``` #### Basic usage ```tsx <BitMainImmersionSummaryBox data={immersionContainer} /> ``` #### More examples <Accordions> <Accordion title="With custom thresholds"> ```tsx <BitMainImmersionSummaryBox data={immersionContainer} containerSettings={{ thresholds: customThresholds }} /> ``` </Accordion> <Accordion title="Oil pump fault"> When `second_pump1_fault` is `true`, oil pump #1 shows an `Error` indicator while pump #2 can remain `Running`. ```tsx const immersionWithPump1Fault: Device = { id: 'bitmain-immersion-1', type: 'bitmain-immersion', last: { snap: { stats: { status: 'running', container_specific: { second_pump1: true, second_pump2: true, second_pump1_fault: true, one_pump: true, primary_supply_temp: 42, second_supply_temp1: 40, second_supply_temp2: 41, }, }, }, }, } <BitMainImmersionSummaryBox data={immersionWithPump1Fault} /> ``` </Accordion> </Accordions> #### Composition - Oil pump #1 and oil pump #2 indicators derived from `second_pump1` / `second_pump2` and their `_fault` flags - Water pump indicator derived from `one_pump` - Three `SingleStatCard`s for primary supply temp, secondary supply Temp1, and secondary supply Temp2, each colored and flashed via `getImmersionTemperatureColor` and `shouldImmersionTemperatureFlash` #### Styling - `.mining-sdk-bitmain-immersion-summary-box`: Root element - `.mining-sdk-bitmain-immersion-summary-box__pumps`: Pumps row - `.mining-sdk-bitmain-immersion-summary-box__pump`: Single pump cell - `.mining-sdk-bitmain-immersion-summary-box__pump-title`: Pump label text - `.mining-sdk-bitmain-immersion-summary-box__liquid-stats`: Liquid stat cards row # Generic widgets (/reference/ui/react/foundation/dashboard/stats/generic-widgets) Widgets that work with any container vendor and pool configuration. For header bar controls see [Header items](/reference/ui/react/foundation/settings/header-controls/header-items). For vendor-specific summary boxes see [Bitmain](/reference/ui/react/foundation/dashboard/stats/bitmain) and [MicroBT](/reference/ui/react/foundation/dashboard/stats/microbt). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - Most widgets expect a container [`Device`](/reference/app-toolkit/ui-devkit/types#device) record; read the individual Props sections for field shapes ## Components <ComponentTable category="Dashboard" subcategory="Generic widgets" pkg="foundation" /> ### `MinersSummaryBox` <ComponentDescription name="MinersSummaryBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `params` | Required | `MinersSummaryParam[]` | none | Label-value pairs rendered in a two-column grid | | `className` | Optional | `string` | none | Additional CSS class | #### `MinersSummaryParam` type ```tsx type MinersSummaryParam = { label: string // Parameter name value: string // Pre-formatted display value (including units) } ``` #### Basic usage ```tsx <MinersSummaryBox params={[ { label: 'Efficiency', value: '32.5 W/TH/S' }, { label: 'Hash Rate', value: '1.24 PH/s' }, { label: 'Max Temp', value: '72 °C' }, { label: 'Avg Temp', value: '65 °C' }, ]} /> ``` #### Notes - Values must be pre-formatted strings (the component does not format data) - Text size automatically adjusts for long values (>12 or >15 characters) #### Styling - `.mdk-miners-summary-box`: Root element - `.mdk-miners-summary-box__param`: Individual parameter row - `.mdk-miners-summary-box__label`: Parameter label - `.mdk-miners-summary-box__label--small`: Smaller text for long values - `.mdk-miners-summary-box__label--tiny`: Tiny text for very long values - `.mdk-miners-summary-box__value`: Parameter value ### `PoolDetailsCard` <ComponentDescription name="PoolDetailsCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `details` | Required | `PoolDetailItem[]` | none | Pool metadata rows; an empty array shows "No data available" | | `label` | Optional | `string` | none | Card header label | | `underline` | Optional | `boolean` | `false` | Underline the header | | `className` | Optional | `string` | none | Additional CSS class | #### `PoolDetailItem` type ```tsx type PoolDetailItem = { title: string value?: string | number } ``` #### Basic usage ```tsx <PoolDetailsCard label="Pool Configuration" details={[ { title: 'Pool URL', value: 'stratum+tcp://pool.example.com:3333' }, { title: 'Worker', value: 'worker001' }, { title: 'Algorithm', value: 'SHA-256' }, ]} /> ``` #### More examples <Accordions> <Accordion title="With underline"> ```tsx <PoolDetailsCard label="Primary Pool" underline details={[ { title: 'URL', value: 'stratum://pool1.example.com:3333' }, { title: 'Status', value: 'Active' }, { title: 'Hashrate', value: '95.2 TH/s' }, { title: 'Accepted', value: 12847 }, { title: 'Rejected', value: 23 }, ]} /> ``` </Accordion> <Accordion title="Empty state"> When `details` is an empty array, displays "No data available": ```tsx <PoolDetailsCard label="Backup Pool" details={[]} /> ``` </Accordion> </Accordions> #### Styling - `.mdk-pool-details-card`: Root element - `.mdk-pool-details-card__header`: Header container - `.mdk-pool-details-card__header--underline`: Underlined header modifier - `.mdk-pool-details-card__label`: Header label text - `.mdk-pool-details-card__list`: Details list container - `.mdk-pool-details-card__item`: Individual detail row - `.mdk-pool-details-card__item-title`: Detail title - `.mdk-pool-details-card__item-value`: Detail value - `.mdk-pool-details-card__empty`: Empty state container ### `PoolDetailsPopover` <ComponentDescription name="PoolDetailsPopover" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `details` | Required | `PoolDetailItem[]` | none | Rows rendered inside the dialog via `PoolDetailsCard` | | `title` | Optional | `string` | none | Dialog title | | `description` | Optional | `string` | none | Dialog description | | `triggerLabel` | Optional | `string` | none | Trigger button label | | `disabled` | Optional | `boolean` | `false` | Disable the trigger button | | `className` | Optional | `string` | none | Additional CSS class | #### Basic usage ```tsx <PoolDetailsPopover triggerLabel="View Pool Details" title="Primary Pool" details={[ { title: 'URL', value: 'stratum://pool.example.com:3333' }, { title: 'Worker', value: 'worker001' }, { title: 'Status', value: 'Active' }, ]} /> ``` #### More examples <Accordions> <Accordion title="With description"> ```tsx <PoolDetailsPopover triggerLabel="Pool Info" title="Pool Configuration" description="Current mining pool settings" details={poolDetails} /> ``` </Accordion> <Accordion title="Disabled state"> ```tsx <PoolDetailsPopover triggerLabel="View Details" details={[]} disabled={!hasPoolData} /> ``` </Accordion> </Accordions> #### Styling - `.mdk-pool-details-popover`: Root element - `.mdk-pool-details-popover__body`: Dialog body container ### `StatsExport` <ComponentDescription name="StatsExport" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `onCsvExport` | Required | `function` | none | Called when CSV is selected; awaited while a spinner is shown | | `onJsonExport` | Required | `function` | none | Called when JSON is selected; awaited while a spinner is shown | | `disabled` | Optional | `boolean` | `false` | Disable the trigger button | | `showLabel` | Optional | `boolean` | `false` | When `false` (default), shows the "Export" text label next to the icon; when `true`, hides the label (icon-only trigger) | `fetchStats`, `downloadCsv`, and `downloadJson` are **app-level** helpers—you implement them (or call your API) inside `onCsvExport` and `onJsonExport`. They are not exported from `@tetherto/mdk-react-devkit`. #### Basic usage ```tsx <StatsExport onCsvExport={async () => { const data = await yourApp.fetchDashboardStats() yourApp.downloadCsv(data, 'mining-stats.csv') }} onJsonExport={async () => { const data = await yourApp.fetchDashboardStats() yourApp.downloadJson(data, 'mining-stats.json') }} /> ``` #### More examples <Accordions> <Accordion title="Disabled state"> ```tsx <StatsExport disabled={!hasData} onCsvExport={handleCsvExport} onJsonExport={handleJsonExport} /> ``` </Accordion> <Accordion title="With loading state"> The component automatically shows a loading spinner during export operations: ```tsx <StatsExport onCsvExport={async () => { await generateAndDownloadCsv() }} onJsonExport={async () => { await generateAndDownloadJson() }} /> ``` </Accordion> <Accordion title="Export formats"> The dropdown provides two export options: 1. **CSV**: Comma-separated values for spreadsheet applications 2. **JSON**: JavaScript Object Notation for programmatic use </Accordion> </Accordions> #### Styling - `.stats-export__button`: Trigger button - `.stats-export__button--disabled`: Disabled state - `.stats-export__label`: Button label text - `.stats-export__divider`: Divider between icon and arrow - `.stats-export__dropdown`: Dropdown menu container - `.stats-export__item`: Dropdown menu item - `.stats-export__item--bordered`: Item with bottom border ### `SupplyLiquidBox` <ComponentDescription name="SupplyLiquidBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `Device` | none | Container device record with supply liquid snap stats | | `containerSettings` | Optional | `SupplyLiquidBoxContainerSettings \| null` | `null` | Hydro threshold overrides (`waterTemperature`, `supplyLiquidPressure`) for color and flash | #### `SupplyLiquidBoxContainerSettings` type ```tsx type SupplyLiquidBoxContainerSettings = { thresholds?: Record<string, Record<string, number>> } ``` Use hydro keys under `thresholds` (not snap stat names such as `supply_liquid_temp`). ```tsx const containerDevice: Device = { id: 'bitmain-hydro-1', type: 'bitmain-hydro', last: { snap: { stats: { status: 'running', supply_liquid_temp: 35, supply_liquid_set_temp: 32, supply_liquid_pressure: 2.5, }, }, }, } ``` #### Basic usage ```tsx <SupplyLiquidBox data={containerDevice} /> ``` #### More examples <Accordions> <Accordion title="With threshold settings"> `containerSettings.thresholds` uses hydro keys `waterTemperature` and `supplyLiquidPressure`. Snap fields such as `supply_liquid_temp` on the device record are separate and are not threshold config keys. ```tsx <SupplyLiquidBox data={containerDevice} containerSettings={{ thresholds: { waterTemperature: { criticalLow: 21, alarmLow: 21, normal: 30, alarmHigh: 37, criticalHigh: 40, }, supplyLiquidPressure: { criticalLow: 2, alarmLow: 2, normal: 2.3, alarmHigh: 3.5, criticalHigh: 4, }, }, }} /> ``` </Accordion> </Accordions> #### Features The component displays three `SingleStatCard` items: - **Supply Liquid** / subtitle **Temp**: current liquid temperature - **Supply Liquid** / subtitle **Set Temp**: target set temperature - **Supply Liquid** / subtitle **Pressure**: current pressure Each stat automatically shows color and flash indicators based on threshold settings. #### Styling - `.mdk-supply-liquid-box`: Root element - `.mdk-supply-liquid-box__stats`: Stats container ### `TanksBox` <ComponentDescription name="TanksBox" /> For the per-row primitive and standalone usage, see [`TankRow`](/reference/ui/react/foundation/operations/containers#tankrow) on the containers page. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `TanksBoxData` | none | Oil pump, water pump, and pressure tank readings; renders nothing when omitted | #### `TanksBoxData` type ```tsx type Tank = { cold_temp_c: number enabled: boolean color?: string // Visual indicator color flash?: boolean // Enable flash animation tooltip?: string // Tooltip text } type TanksBoxData = { oil_pump: Tank[] water_pump: { enabled: boolean }[] pressure: { value?: number; flash?: boolean; color?: string; tooltip?: string }[] } ``` #### Composition `TanksBox` maps each `oil_pump` entry to one [`TankRow`](/reference/ui/react/foundation/operations/containers#tankrow) by array index: ```tsx // Per-row mapping (index i): oil_pump[i].enabled -> oilPumpEnabled oil_pump[i].cold_temp_c -> temperature (always Celsius) water_pump[i]?.enabled -> waterPumpEnabled pressure[i] ?? {} -> pressure oil_pump[i].{color,flash,tooltip} -> temperature cell hints ``` #### Basic usage ```tsx <TanksBox data={{ oil_pump: [ { cold_temp_c: 45, enabled: true }, { cold_temp_c: 42, enabled: true }, ], water_pump: [ { enabled: true }, { enabled: false }, ], pressure: [ { value: 1.2 }, { value: 1.1 }, ], }} /> ``` #### More examples <Accordions> <Accordion title="With visual alerts"> ```tsx <TanksBox data={{ oil_pump: [ { cold_temp_c: 85, enabled: true, color: 'red', flash: true, tooltip: 'High temp!' }, ], water_pump: [{ enabled: true }], pressure: [{ value: 2.5, color: 'orange', flash: true }], }} /> ``` </Accordion> <Accordion title="Multiple tanks"> ```tsx <TanksBox data={{ oil_pump: [ { cold_temp_c: 42, enabled: true }, { cold_temp_c: 44, enabled: true }, { cold_temp_c: 41, enabled: false }, ], water_pump: [{ enabled: true }, { enabled: false }, { enabled: true }], pressure: [{ value: 1.1 }, { value: 1.3 }, {}], }} /> ``` </Accordion> <Accordion title="With custom tooltips"> ```tsx <TanksBox data={{ oil_pump: [ { cold_temp_c: 42, enabled: true, tooltip: 'Within normal range' }, { cold_temp_c: 55, enabled: true, tooltip: 'Approaching threshold – consider cooling', }, ], water_pump: [{ enabled: true }, { enabled: true }], pressure: [{ value: 1.2 }, { value: 1.4, tooltip: 'Pressure slightly elevated' }], }} /> ``` </Accordion> <Accordion title="Mixed pump states"> ```tsx <TanksBox data={{ oil_pump: [ { cold_temp_c: 43, enabled: true }, { cold_temp_c: 44, enabled: false }, { cold_temp_c: 42, enabled: true }, ], water_pump: [{ enabled: false }, { enabled: true }, { enabled: false }], pressure: [{ value: 1.1 }, { value: 1.2 }, { value: 1.0 }], }} /> ``` </Accordion> <Accordion title="No data"> When `data` is omitted, `TanksBox` returns `null` and renders nothing: ```tsx <TanksBox /> ``` </Accordion> </Accordions> #### Styling - `.mdk-tanks-box`: Root element - Uses [`TankRow`](/reference/ui/react/foundation/operations/containers#tankrow) internally for each tank display ## Related hooks The following adapter data hooks supply the live values consumed by the widgets on this page. | Hook | Supplies | |------|---------| | [`useSiteHashrate`](/reference/app-toolkit/hooks/data#usesitehashrate) | Aggregate hashrate in PH/s for hashrate stat boxes | | [`useSiteMinerCounts`](/reference/app-toolkit/hooks/data#usesiteminercounts) | Online, offline, and error miner counts | | [`useSiteMinerStats`](/reference/app-toolkit/hooks/data#usesiteminerstats) | Live MOS total and realtime miner breakdown (stat-rtd) | | [`useSiteEfficiency`](/reference/app-toolkit/hooks/data#usesiteefficiency) | W/TH/s efficiency value | | [`useSiteConsumption`](/reference/app-toolkit/hooks/data#usesiteconsumption) | Latest site power consumption in MW | | [`usePoolStats`](/reference/app-toolkit/hooks/data#usepoolstats) | Aggregate pool worker counts and hashrate for pool summary cards | | [`useHashrateChartData`](/reference/app-toolkit/hooks/data#usehashratechartdata) | Site + per-pool hashrate time-series for chart widgets | # MicroBT (/reference/ui/react/foundation/dashboard/stats/microbt) Summary widget for MicroBT containers. For other vendor widgets see [Bitmain](/reference/ui/react/foundation/dashboard/stats/bitmain). For vendor-agnostic cards see [Generic widgets](/reference/ui/react/foundation/dashboard/stats/generic-widgets). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - A [`Device`](/reference/app-toolkit/ui-devkit/types#device) record of type `microbt` ## Components <ComponentTable category="Dashboard" subcategory="MicroBT" pkg="foundation" /> ### `MicroBTWidgetBox` <ComponentDescription name="MicroBTWidgetBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `Device` | none | MicroBT container device record; returns `null` when omitted | ```tsx const microbtContainer: Device = { id: 'microbt-1', type: 'microbt', last: { snap: { stats: { status: 'running', container_specific: { cdu: { circulation_pump_running_status: 'running', cooling_fan_control: true, }, }, }, }, }, } ``` #### Basic usage ```tsx <MicroBTWidgetBox data={microbtContainer} /> ``` #### Indicators rendered The label **`Cicle Pump`** matches the rendered UI and foundation source (typo for "Cycle Pump"); keep documentation aligned until the component string is corrected in code. - `Cicle Pump`: green `Running` when `cdu.circulation_pump_running_status` equals `CONTAINER_STATUS.RUNNING`, gray `Off` otherwise - `Cooling Fan`: green `Running` when `cdu.cooling_fan_control` is truthy, red `Error` otherwise #### Styling - `.mdk-micro-bt-widget-box`: Root grid element - `.mdk-micro-bt-widget-box__item`: Single indicator cell - `.mdk-micro-bt-widget-box__title`: Indicator label text # Inventory (/reference/ui/react/foundation/inventory) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> Inventory components display historical device movement details. Pair with the [Operations centre](/reference/ui/react/foundation/operations) for full device-management context. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Components <ComponentTable category="Inventory" pkg="foundation" /> ### `MovementDetailsModal` <ComponentDescription name="MovementDetailsModal" /> Modal showing the details of a historical device movement — the device summary plus the origin → destination transition of location and status. All three props are optional (the component renders `null` when `movement` is absent), so you can gate the modal on a selection without separate conditional rendering: 1. **Device details** (`movement.device`): code, type, site, container, serial number, MAC address. 2. **Movement preview**: side-by-side origin and destination panels showing location and status with colour-coded badges. 3. **Comments** (`movement.comments`): optional free-text or node rendered below the movement panels. The component does no data fetching — the parent is responsible for passing the selected movement. #### Import ```tsx MovementDetailsModalProps, MovementData, MovementDevice, } from '@tetherto/mdk-react-devkit/foundation' ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `isOpen` | Optional | `boolean` | `false` | When `true`, the modal is visible | | `onClose` | Optional | `function` | none | Called when the user dismisses the modal | | `movement` | Optional | `MovementData` | none | Movement record to display; modal renders `null` when absent | #### `MovementData` type ```tsx type MovementData = { origin: string destination: string previousStatus: string newStatus: string device?: MovementDevice comments?: ReactNode } ``` #### `MovementDevice` type ```tsx type MovementDevice = Partial<{ code: string tags: string[] type: string info: Partial<{ subType: string site: string container: string serialNum: string macAddress: string }> }> ``` #### Basic usage ```tsx function InventoryTable({ movements }) { const [selected, setSelected] = useState<MovementData | null>(null) return ( <> <MovementDetailsModal isOpen={selected !== null} movement={selected ?? undefined} onClose={() => setSelected(null)} /> </> ) } ``` #### Behavior notes - `movement` is the primary gate: when it is absent the component returns `null` and nothing is mounted, regardless of `isOpen`. `isOpen` only controls visibility once a `movement` is provided - Location and status badge colours come from the MDK design-token maps (`MINER_LOCATION_*`, `MINER_STATUS_*`) - The modal title is fixed: **"Historical Device Update"** ## Next steps - For device-level details, see the [Operations centre](/reference/ui/react/foundation/operations) pages # Operations centre (/reference/ui/react/foundation/operations) Domain-specific components for Bitcoin mining operations monitoring and management. <FoundationComponentTablesByCategory /> ## Next steps - **[@tetherto/mdk-react-devkit/core components](/reference/ui/react/core/components)**: Base components used by the operations centre (Cards, Charts, Tables) - **[Settings](/reference/ui/react/foundation/settings)**: Administrative settings UI for feature flags, user management, and configuration - **[Hooks](/reference/app-toolkit/hooks/components#charts)**: React hooks for real-time monitoring data # Container components (/reference/ui/react/foundation/operations/containers) Components for viewing, navigating, and controlling Bitcoin mining containers, racks, and associated hardware. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Container subpages Dedicated pages for the socket primitive and vendor-specific UI: - [Socket](/reference/ui/react/foundation/operations/containers/socket) — PDU socket tile primitive - [Bitdeer](/reference/ui/react/foundation/operations/containers/bitdeer) - [Bitmain](/reference/ui/react/foundation/operations/containers/bitmain) - [Bitmain Immersion](/reference/ui/react/foundation/operations/containers/bitmain-immersion) - [MicroBT](/reference/ui/react/foundation/operations/containers/microbt) ## All container components Every component in this category, including shared chrome and vendor-specific widgets. <ComponentTable category="Containers" pkg="foundation" /> ## Shared components Container-authoring primitives that work with any container device record. Use these as building blocks inside the vendor-specific pages above, or when composing your own container view. For the PDU socket tile, see the dedicated [Socket](/reference/ui/react/foundation/operations/containers/socket) page. ### `EnabledDisableToggle` <ComponentDescription name="EnabledDisableToggle" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `value` | Required | `unknown` | none | Current toggle value; boolean enables switch display | | `tankNumber` | Optional | `number \| string` | required | Tank identifier; empty falls back to "Air Exhaust System" | | `isButtonDisabled` | Required | `boolean` | none | Disables both Enable and Disable buttons | | `isOffline` | Required | `boolean` | none | Marks container offline and disables controls | | `onToggle` | Required | `function` | none | Fires when user clicks Enable or Disable | #### Basic usage ```tsx <EnabledDisableToggle value={tank.circulationEnabled} tankNumber={1} isButtonDisabled={false} isOffline={false} onToggle={({ tankNumber, isOn }) => submitToggle(tankNumber, isOn)} /> ``` #### More examples <Accordions> <Accordion title="Air exhaust variant"> ```tsx <EnabledDisableToggle value={exhaustEnabled} tankNumber="" isButtonDisabled={false} isOffline={false} onToggle={({ isOn }) => setExhaust(isOn)} /> ``` </Accordion> </Accordions> #### Styling - `.mdk-enabled-disable-toggle`: Root element - `.mdk-enabled-disable-toggle__toggle`: Label and `Switch` row shown when `value` is boolean ### `GenericDataBox` <ComponentDescription name="GenericDataBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `DataItem[]` | `[]` | Rows to render as label, value, and units | | `fallbackValue` | Optional | `unknown` | none | Value used when a row's `value` is undefined | #### `DataItem` type ```tsx type DataItem = { label?: string value?: unknown units?: string unit?: string // Alternative unit field isHighlighted?: boolean color?: string flash?: boolean } ``` #### Basic usage ```tsx <GenericDataBox data={[ { label: 'Temperature', value: 45, units: '°C' }, { label: 'Pressure', value: 2.5, units: 'bar', isHighlighted: true }, { label: 'Status', value: 'Running', color: 'green' }, ]} /> ``` #### Styling - `.mdk-generic-data-box`: Root element - Renders each row through `DataRow` ### `TankRow` <ComponentDescription name="TankRow" /> `TankRow` is composed by [`TanksBox`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#tanksbox) for dashboard tank status; use `TankRow` directly when building custom container layouts. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Required | `string` | none | Row label shown on the left | | `temperature` | Required | `number` | none | Temperature reading displayed in the row | | `unit` | Required | `string` | none | Unit suffix appended to the temperature | | `oilPumpEnabled` | Required | `boolean` | none | Drives the oil pump indicator state | | `waterPumpEnabled` | Required | `boolean` | none | Drives the water pump indicator state | | `color` | Required | `string` | none | Text color for temperature and pressure cells; empty string uses default theme colors | | `pressure` | Required | `TankRowPressure` | none | [`Pressure readout object`](#tankrowpressure-type); block not rendered when `value` is omitted | | `flash` | Optional | `boolean` | none | Enables flash animation on the temp cell | | `tooltip` | Optional | `string` | none | Overrides the default temperature tooltip | #### `TankRowPressure` type ```tsx type TankRowPressure = Partial<{ value: number flash: boolean color: string tooltip: string }> ``` #### Basic usage ```tsx <TankRow label="Tank 1" temperature={45} unit="°C" oilPumpEnabled waterPumpEnabled={false} color="" pressure={{ value: 1.2 }} /> ``` #### More examples <Accordions> <Accordion title="Temperature only"> ```tsx <TankRow label="Tank 1" temperature={42} unit="°C" oilPumpEnabled waterPumpEnabled color="" pressure={{}} /> ``` </Accordion> <Accordion title="With alert state"> ```tsx <TankRow label="Tank 2" temperature={82} unit="°C" oilPumpEnabled waterPumpEnabled color="red" flash tooltip="Oil temperature above threshold" pressure={{ value: 2.4, color: 'orange', flash: true }} /> ``` </Accordion> </Accordions> #### Styling - `.mdk-tanks-box__row`: Root row element - `.mdk-tanks-box__params`: Temperature and pressure group - `.mdk-tanks-box__param` / `__param-label` / `__param-value`: Individual readouts - `.mdk-tanks-box__pump-statuses`: Pump indicator group - `.mdk-tanks-box__pump-status` / `__pump-status-title`: Per-pump indicator ### `ContainerFanLegend` <ComponentDescription name="ContainerFanLegend" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `index` | Optional | `number \| null` | none | Fan number shown in the badge | | `enabled` | Optional | `boolean` | `false` | Renders on/off styling and icon color | | `className` | Optional | `string` | none | Additional CSS class on the root element | #### Basic usage ```tsx <ContainerFanLegend index={1} enabled /> <ContainerFanLegend index={2} enabled={false} /> ``` #### Styling - `.mdk-container-fan-legend`: Root element - `.mdk-container-fan-legend--on` / `--off`: On/off state modifier - `.mdk-container-fan-legend__number`: Fan number badge - `.mdk-container-fan-legend__icon` / `--on` / `--off`: Fan icon container ### `ContainerFansCard` <ComponentDescription name="ContainerFansCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `fansData` | Required | `PumpItem[]` | none | Fan entries; returns `null` when omitted | #### `PumpItem` type ```tsx type PumpItem = { enabled?: boolean index: number } ``` #### Basic usage ```tsx <ContainerFansCard fansData={[ { enabled: true, index: 0 }, { enabled: false, index: 1 }, { enabled: true, index: 2 }, ]} /> ``` #### Styling - `.mdk-container-fans-card`: Root grid element - Renders one `ContainerFanLegend` per entry ### `DryCooler` <ComponentDescription name="DryCooler" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `UnknownRecord` | none | Container device record with cooling system stats | ```tsx const containerDevice = { container_specific_stats: { cooling_system: { dry_cooler: [{ index: 0, enabled: true, fans: [{ enabled: true, index: 0 }] }], oil_pump: [{ enabled: true, index: 0 }], water_pump: [{ enabled: true, index: 0 }], }, }, } ``` #### Basic usage ```tsx <DryCooler data={containerDevice} /> ``` #### Expected data shape The component reads the following path from `data`: ```tsx // data.container_specific_stats.cooling_system { dry_cooler: [ { index: 0, enabled: true, fans: [{ enabled: true, index: 0 }] }, { index: 1, enabled: false, fans: [] }, ], oil_pump: [{ enabled: true, index: 0 }, { enabled: false, index: 1 }], water_pump: [{ enabled: true, index: 0 }, { enabled: true, index: 1 }], } ``` #### Styling - `.mdk-dry-cooler`: Root element - `.mdk-dry-cooler__segment`: Per-cooler group - `.mdk-dry-cooler__card`: Cooler card with status and fans - `.mdk-dry-cooler__status`: Title and indicator row - `.mdk-dry-cooler__title`: Cooler title - `.mdk-dry-cooler__pumps`: Oil and water pump column ### `PumpBox` <ComponentDescription name="PumpBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `pumpTitle` | Required | `string` | none | Pump label prefix (e.g. `"Oil"`, `"Water"`) | | `pumpItem` | Required | `PumpItem` | none | Pump entry; returns `null` without a boolean `enabled` | #### `PumpItem` type ```tsx type PumpItem = { enabled?: boolean index: number // zero-based; shown as index + 1 } ``` #### Basic usage ```tsx <PumpBox pumpTitle="Oil" pumpItem={{ enabled: true, index: 0 }} /> <PumpBox pumpTitle="Water" pumpItem={{ enabled: false, index: 1 }} /> ``` #### Styling - `.mdk-pump-box`: Root element - `.mdk-pump-box__status`: Title and indicator row - `.mdk-pump-box__title`: Pump title text ## Next steps - For browsing containers, racks, and miners, see the [device explorer](/reference/ui/react/foundation/operations/device-explorer). - For container-level controls, see [`ContainerControlsBox`](/reference/ui/react/foundation/operations/details-view/controls#containercontrolsbox) on the Controls page. - For container summary widgets that surface on the dashboard, see [`TanksBox`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#tanksbox), [`SupplyLiquidBox`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#supplyliquidbox), and [`MinersSummaryBox`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#minerssummarybox). # Bitdeer container components (/reference/ui/react/foundation/operations/containers/bitdeer) UI for Bitdeer containers. These components consume Bitdeer-shaped device records and render pump state, exhaust fan status, tank charts, and settings. For primitives shared across all container vendors (`EnabledDisableToggle`, `DryCooler`, etc.), see the [Containers overview](/reference/ui/react/foundation/operations). The PDU socket tile has its own [Socket](/reference/ui/react/foundation/operations/containers/socket) page. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - A Bitdeer container device record. The charts and pumps components read from `container_specific_stats.cooling_system`. ## Components <ComponentTable category="Containers" subcategory="Bitdeer" pkg="foundation" /> ### `BitdeerPumps` <ComponentDescription name="BitdeerPumps" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Bitdeer container record; must contain exhaust fan status | #### Basic usage ```tsx <BitdeerPumps data={bitdeerContainer} /> ``` #### Styling - `.mdk-bitdeer-pumps`: Root element - `.mdk-bitdeer-pumps__status`: Title and indicator row - `.mdk-bitdeer-pumps__title`: Label text (`"Exhaust Fan"`) ### `BitdeerSettings` <ComponentDescription name="BitdeerSettings" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `UnknownRecord` | `{}` | Bitdeer container device record | #### Basic usage ```tsx <BitdeerSettings data={bitdeerContainer} /> ``` #### Composition - Renders `ContainerParamsSettings` with container identity data - Renders `EditableThresholdForm` wired with Bitdeer-specific color, flash, and superflash helpers for oil temperature and tank pressure #### Styling - `.mdk-bitdeer-settings`: Root element - `.mdk-bitdeer-settings__params`: Container params section - `.mdk-bitdeer-settings__thresholds`: Editable threshold section ### `BitdeerTankPressureCharts` <ComponentDescription name="BitdeerTankPressureCharts" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `tag` | Required | `string` | none | Container tag used to scope chart data | | `chartTitle` | Optional | `string` | `'Tank Pressure'` | Chart header title | | `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot | | `timeline` | Optional | `string` | `'24h'` | Initial time range (e.g. `'5m'`, `'3h'`, `'1D'`) | | `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms | | `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels | | `height` | Required | `number` | none | Chart height in pixels | #### Basic usage ```tsx <BitdeerTankPressureCharts tag="container1" data={pressureData} timeline="24h" /> ``` #### Lines rendered - **Tank1 Pressure**: yellow, backend attribute `tank1_bar_group` - **Tank2 Pressure**: violet, backend attribute `tank2_bar_group` - Values are shown in `bar` with 1 decimal place ### `BitdeerTankTempCharts` <ComponentDescription name="BitdeerTankTempCharts" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `tag` | Required | `string` | none | Container tag used to scope chart data | | `tankNumber` | Optional | `number \| string` | `1` | Tank index used to build backend attributes | | `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot | | `timeline` | Optional | `string` | `'24h'` | Initial time range | | `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms | | `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels | | `height` | Required | `number` | none | Chart height in pixels | #### Basic usage ```tsx <BitdeerTankTempCharts tag="container1" tankNumber={1} data={tempData} timeline="24h" /> ``` #### Lines rendered - `Tank{n} Oil TempL`: yellow (4px), backend attribute `cold_temp_c_{n}_group` - `Tank{n} Oil TempH`: violet, `hot_temp_c_{n}_group` - `Tank{n} Water TempL`: blue, `cold_temp_c_w_{n}_group` - `Tank{n} Water TempH`: sky blue, `hot_temp_c_w_{n}_group` - Values are shown in `°C` # Bitmain container components (/reference/ui/react/foundation/operations/containers/bitmain) UI for Bitmain hydro containers. These components read from Bitmain-shaped device records and render cooling-system status, power and positioning, liquid-flow charts, and hydro settings. For primitives shared across all container vendors (`EnabledDisableToggle`, `DryCooler`, etc.), see the [Containers overview](/reference/ui/react/foundation/operations). The PDU socket tile has its own [Socket](/reference/ui/react/foundation/operations/containers/socket) page. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - A Bitmain container device record. Most components read from `container_specific_stats` and `container_specific_stats_group_aggr` on the device. ## Components <ComponentTable category="Containers" subcategory="Bitmain" pkg="foundation" /> ### `BitMainBasicSettings` <ComponentDescription name="BitMainBasicSettings" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | none | Bitmain container device record | #### Basic usage ```tsx <BitMainBasicSettings data={bitmainContainer} /> ``` #### Composition - Renders `BitMainCoolingSystem` with pump and fan indicators - Renders a `"Power & Positioning"` section containing `BitMainPowerAndPositioning` #### Styling - `.mdk-bitmain-basic-settings`: Root element - `.mdk-bitmain-basic-settings__section`: Section wrapper - `.mdk-bitmain-basic-settings__title`: Section heading ### `BitMainCoolingSystem` <ComponentDescription name="BitMainCoolingSystem" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `Device` | none | Bitmain container device record | #### Basic usage ```tsx <BitMainCoolingSystem data={bitmainContainer} /> ``` #### Indicators rendered - `Circulating pump`: `circulating_pump`, fault from `circulating_pump_fault` - `Fluid Infusion pump`: `fluid_infusion_pump`, fault from `fluid_infusion_pump_fault` - `Fan #1`, `Fan #2`: `fan1`, `fan2`, faults from `fan1_fault`, `fan2_fault` - `Cooling tower fan #1..#3`: `cooling_tower_fan1..3` with matching `_fault` attributes - Indicator color is red on fault, green when running, gray otherwise #### Styling - `.mdk-bitmain-cooling-system`: Root element - `.mdk-bitmain-cooling-system__wrapper`: Indicator grid wrapper - `.mdk-bitmain-cooling-system__row`: Row of indicators - `.mdk-bitmain-cooling-system__item`: Indicator cell - `.mdk-bitmain-cooling-system__label`: Label text ### `BitMainHydroLiquidTemperatureCharts` <ComponentDescription name="BitMainHydroLiquidTemperatureCharts" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `tag` | Required | `string` | none | Container tag used to scope chart data | | `chartTitle` | Optional | `string` | `'Hydro Liquid Temperature'` | Chart header title | | `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot | | `timeline` | Optional | `string` | `'24h'` | Initial time range (e.g. `'5m'`, `'3h'`, `'1D'`) | | `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms | | `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels | | `height` | Required | `number` | none | Chart height in pixels | | `showLegend` | Optional | `boolean` | `true` | Shows the series legend | | `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector | | `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart | #### Basic usage ```tsx <BitMainHydroLiquidTemperatureCharts tag="container1" data={tempData} timeline="24h" /> ``` #### Lines rendered - **Sec. Liquid supply Temp1**: sky blue, backend attribute `second_supply_temp1_group` - **Sec. Liquid supply Temp2**: violet, backend attribute `second_supply_temp2_group` - Values are shown in `°C` with 1 decimal place ### `BitMainHydroSettings` <ComponentDescription name="BitMainHydroSettings" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `Device` | none | Bitmain Hydro container device record | #### Basic usage ```tsx <BitMainHydroSettings data={bitmainContainer} /> ``` #### Composition - Renders `BitMainBasicSettings` for cooling, power, and positioning - Renders `HydroEditableThresholdForm` wired with Bitmain-specific color, flash, and superflash helpers for supply liquid temperature and pressure #### Styling - `.mdk-bitmain-hydro-settings`: Root element - `.mdk-bitmain-hydro-settings__params`: Basic settings section - `.mdk-bitmain-hydro-settings__thresholds`: Editable threshold section ### `BitMainLiquidPressureCharts` <ComponentDescription name="BitMainLiquidPressureCharts" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `tag` | Required | `string` | none | Container tag used to scope chart data | | `chartTitle` | Optional | `string` | `'Liquid Pressure'` | Chart header title | | `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot | | `timeline` | Optional | `string` | `'24h'` | Initial time range | | `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms | | `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels | | `height` | Required | `number` | none | Chart height in pixels | | `showLegend` | Optional | `boolean` | `true` | Shows the series legend | | `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector | | `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart | #### Basic usage ```tsx <BitMainLiquidPressureCharts tag="container1" data={pressureData} timeline="24h" /> ``` #### Lines rendered - **Supply Liquid Pressure**: sky blue, backend attribute `supply_liquid_pressure_group` - **Return Liquid Pressure**: violet, backend attribute `return_liquid_pressure_group` - Values are shown in `bar` with 3 decimal places; source MPa values are autoconverted with [`convertMpaToBar`](/reference/app-toolkit/ui-devkit/utilities#convertmpatobar). ### `BitMainLiquidTempCharts` <ComponentDescription name="BitMainLiquidTempCharts" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `tag` | Required | `string` | none | Container tag used to scope chart data | | `chartTitle` | Optional | `string` | `'Liquid Temperature'` | Chart header title | | `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot | | `timeline` | Optional | `string` | `'24h'` | Initial time range | | `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms | | `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels | | `height` | Required | `number` | none | Chart height in pixels | | `showLegend` | Optional | `boolean` | `true` | Shows the series legend | | `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector | | `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart | #### Basic usage ```tsx <BitMainLiquidTempCharts tag="container1" data={tempData} timeline="24h" /> ``` #### Lines rendered - **Supply Liquid Temp**: sky blue, backend attribute `supply_liquid_temp_group` - **Return Liquid Temp**: violet, backend attribute `return_liquid_temp_group` - Values are shown in `°C` with 1 decimal place ### `BitMainPowerAndPositioning` <ComponentDescription name="BitMainPowerAndPositioning" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `Device` | none | Bitmain container device record | #### Basic usage ```tsx <BitMainPowerAndPositioning data={bitmainContainer} /> ``` #### Composition - Renders a `Power` `ContentBox` with distribution box #1 and #2 kW values (read from `distribution_box1_power_w`, `distribution_box2_power_w`) - Renders a `Location` `ContentBox` with latitude, longitude, and their direction fields #### Styling - `.mdk-bitmain-power-positioning`: Root element - `.mdk-bitmain-power-positioning__panel`: Power or Location panel - `.mdk-bitmain-power-positioning__section`: Section body - `.mdk-bitmain-power-positioning__power-item`: Distribution box row - `.mdk-bitmain-power-positioning__location-grid`: Latitude and longitude grid - `.mdk-bitmain-power-positioning__location-item`: Coordinate cell - `.mdk-bitmain-power-positioning__location-details`: Coordinate details - `.mdk-bitmain-power-positioning__subtitle`: Panel subtitle - `.mdk-bitmain-power-positioning__value`: Power value text ### `BitMainPowerCharts` <ComponentDescription name="BitMainPowerCharts" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `tag` | Required | `string` | none | Container tag used to scope chart data | | `chartTitle` | Optional | `string` | `'Power Consumption'` | Chart header title | | `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot | | `timeline` | Optional | `string` | `'24h'` | Initial time range | | `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms | | `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels | | `height` | Required | `number` | none | Chart height in pixels | | `showLegend` | Optional | `boolean` | `true` | Shows the series legend | | `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector | | `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart | #### Basic usage ```tsx <BitMainPowerCharts tag="container1" data={powerData} timeline="24h" /> ``` #### Lines rendered - **Total Power**: sky blue (3px), computed attribute `total_power_computed` (sum of boxes) - **Dist. Box 1 Power**: violet, backend attribute `distribution_box1_power_group` - **Dist. Box 2 Power**: red, backend attribute `distribution_box2_power_group` - Values are shown in `W` (stored kW is converted with `convertKwToW`) with 2 decimal places ### `BitMainSupplyLiquidFlowCharts` <ComponentDescription name="BitMainSupplyLiquidFlowCharts" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `tag` | Required | `string` | none | Container tag used to scope chart data | | `chartTitle` | Optional | `string` | `'Supply Liquid Flow'` | Chart header title | | `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot | | `timeline` | Optional | `string` | `'24h'` | Initial time range | | `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms | | `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels | | `height` | Required | `number` | none | Chart height in pixels | | `showLegend` | Optional | `boolean` | `false` | Shows the series legend | | `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector | | `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart | #### Basic usage ```tsx <BitMainSupplyLiquidFlowCharts tag="container1" data={flowData} timeline="24h" /> ``` #### Lines rendered - **Supply Liquid Flow**: sky blue (2px), backend attribute `supply_liquid_flow_group` - Values are shown in `m³/h` with 2 decimal places ### `StatusItem` <ComponentDescription name="StatusItem" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Required | `string` | none | Label text shown next to the indicator | | `status` | Optional | `'normal' \| 'warning' \| 'fault' \| 'unavailable'` | `'unavailable'` | Status type; selects color and label | #### Status mapping - `normal`: green indicator, label `Normal` - `warning`: amber indicator, label `Warning` - `fault`: red indicator, label `Fault` - `unavailable`: gray indicator, label `Unavailable` #### Basic usage ```tsx <StatusItem label="Temperature" status="normal" /> <StatusItem label="Pressure" status="warning" /> <StatusItem label="Flow" status="fault" /> ``` #### Styling - `.mdk-status-item`: Root element - `.mdk-status-item__content`: Label and indicator row - `.mdk-status-item__label`: Label text # Bitmain Immersion container components (/reference/ui/react/foundation/operations/containers/bitmain-immersion) UI for Bitmain Immersion containers. These components render unit control boxes, pump-station status, immersion settings, and system-status views on top of Bitmain immersion-shaped device records. For primitives shared across all container vendors (`EnabledDisableToggle`, `DryCooler`, etc.), see the [Containers overview](/reference/ui/react/foundation/operations). The PDU socket tile has its own [Socket](/reference/ui/react/foundation/operations/containers/socket) page. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - A Bitmain Immersion container device record. Most components read pump and temperature fields from `container_specific_stats`. ## Components <ComponentTable category="Containers" subcategory="Bitmain Immersion" pkg="foundation" /> ### `BitMainControlsTab` <ComponentDescription name="BitMainControlsTab" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | none | Bitmain immersion container device record | #### Basic usage ```tsx <BitMainControlsTab data={immersionContainer} /> ``` #### Composition - Container fan indicator from `container_fan` and `fan_fault` (red on fault, green running, gray off) - Tank levels for Tank A to Tank D read from `tank_a_level` to `tank_d_level` in cm - GPS latitude and longitude with direction fields #### Styling - `.mdk-bitmain-controls-tab`: Root element - `.mdk-bitmain-controls-tab__section`: Section wrapper - `.mdk-bitmain-controls-tab__section-header`: Fan status row - `.mdk-bitmain-controls-tab__section-label`: Fan label text - `.mdk-bitmain-controls-tab__title`: Section heading - `.mdk-bitmain-controls-tab__grid`: Tank or GPS grid - `.mdk-bitmain-controls-tab__item`: Tank cell - `.mdk-bitmain-controls-tab__label`: Tank label - `.mdk-bitmain-controls-tab__value`: Tank value - `.mdk-bitmain-controls-tab__location`: GPS cell - `.mdk-bitmain-controls-tab__location-label`: GPS axis label - `.mdk-bitmain-controls-tab__location-value`: GPS coordinate value - `.mdk-bitmain-controls-tab__location-dir`: GPS direction text ### `BitMainImmersionControlBox` <ComponentDescription name="BitMainImmersionControlBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `title` | Required | `string` | none | Box title shown above the left column | | `leftContent` | Required | `ReactNode` | none | Content for the left column | | `rightContent` | Required | `ReactNode` | none | Content for the right column | | `bottomContent` | Optional | `ReactNode` | none | Optional content for the bottom row | | `secondary` | Optional | `boolean` | `false` | Borderless variant | | `className` | Optional | `string` | none | Additional class name on the root | #### Basic usage ```tsx <BitMainImmersionControlBox title="Power Status" leftContent={<div>Current: 35°C</div>} rightContent={<div>Target: 30°C</div>} bottomContent={<div>Additional info</div>} /> ``` #### Styling - `.mdk-bitmain-immersion-control-box`: Root element - `.mdk-bitmain-immersion-control-box--secondary`: Borderless variant modifier - `.mdk-bitmain-immersion-control-box__top`: Two-column wrapper - `.mdk-bitmain-immersion-control-box__left`: Left column - `.mdk-bitmain-immersion-control-box__right`: Right column - `.mdk-bitmain-immersion-control-box__title`: Title text - `.mdk-bitmain-immersion-control-box__bottom`: Bottom row ### `BitMainImmersionPumpStationControlBox` <ComponentDescription name="BitMainImmersionPumpStationControlBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `title` | Required | `string` | none | Box title | | `alarmStatus` | Optional | `boolean` | `false` | Shows `Fault` tag when true, `Normal` otherwise | | `ready` | Required | `boolean` | none | Ready state; row hidden when omitted | | `operation` | Required | `boolean` | none | Operating state; row hidden when omitted | | `start` | Required | `boolean` | none | Started state; row hidden when omitted | | `className` | Optional | `string` | none | Additional class name on the root | #### Basic usage ```tsx <BitMainImmersionPumpStationControlBox title="Pump Station #1" alarmStatus={false} ready={true} operation={true} start={true} /> ``` #### Styling - `.mdk-bitmain-immersion-pump-station-control-box`: Root element - `.mdk-bitmain-immersion-pump-station-control-box__title`: Title text - `.mdk-bitmain-immersion-pump-station-control-box__content`: Tag and states row - `.mdk-bitmain-immersion-pump-station-control-box__status`: Alarm tag wrapper - `.mdk-bitmain-immersion-pump-station-control-box__state`: State label - `.mdk-bitmain-immersion-pump-station-control-box__state--on`: Active state modifier - `.mdk-bitmain-immersion-pump-station-control-box__state--off`: Inactive state modifier ### `BitMainImmersionSettings` <ComponentDescription name="BitMainImmersionSettings" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `Device` | none | Bitmain immersion container device record | | `containerSettings` | Optional | `object \| null` | `null` | Optional custom oil temperature thresholds. Shape: `{ thresholds?: Record<string, unknown> }` | #### Basic usage ```tsx <BitMainImmersionSettings data={immersionContainer} /> ``` #### With custom thresholds ```tsx <BitMainImmersionSettings data={immersionContainer} containerSettings={{ thresholds: customThresholds }} /> ``` #### Composition - Renders `ImmersionEditableThresholdForm` wired with Bitmain immersion color, flash, and superflash helpers for oil temperature - When `status` is missing on `data`, it defaults to `'active'` ### `BitMainImmersionSystemStatus` <ComponentDescription name="BitMainImmersionSystemStatus" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `Device` | none | Bitmain immersion container device record | #### Basic usage ```tsx <BitMainImmersionSystemStatus data={immersionContainer} /> ``` #### Styling - `.mdk-bitmain-immersion-system-status`: Root element - `.mdk-bitmain-immersion-system-status__header`: Header row - `.mdk-bitmain-immersion-system-status__title`: Title text - `.mdk-bitmain-immersion-system-status__content`: Status rows wrapper - `.mdk-bitmain-immersion-system-status__item`: Single status row - `.mdk-bitmain-immersion-system-status__label`: Row label text ### `BitMainImmersionUnitControlBox` <ComponentDescription name="BitMainImmersionUnitControlBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `title` | Required | `string` | none | Box title shown above the left column | | `alarmStatus` | Optional | `boolean` | `false` | Shows `Fault` tag when true, `Normal` otherwise | | `frequency` | Required | `number` | none | Frequency value in Hz; row hidden when omitted | | `isDryCooler` | Optional | `boolean` | `false` | Forces status label to `"Dry Cooler"` | | `running` | Optional | `boolean` | `false` | Shows a running or off indicator | | `showFrequencyInLeftColumn` | Optional | `boolean` | `false` | Renders the frequency row in the left column instead of the right | | `secondary` | Optional | `boolean` | `false` | Borderless variant | | `className` | Optional | `string` | none | Additional class name on the root | #### Basic usage ```tsx <BitMainImmersionUnitControlBox title="Unit #1" alarmStatus={false} running={true} frequency={50} /> ``` #### Dry cooler variant ```tsx <BitMainImmersionUnitControlBox isDryCooler running frequency={45} showFrequencyInLeftColumn /> ``` #### Styling - `.mdk-bitmain-immersion-unit-control-box`: Root element - `.mdk-bitmain-immersion-unit-control-box__item`: Label and value row (status or frequency) - `.mdk-bitmain-immersion-unit-control-box__item-label`: Row label text - `.mdk-bitmain-immersion-unit-control-box__item-value`: Row value text # MicroBT container components (/reference/ui/react/foundation/operations/containers/microbt) UI for MicroBT containers. These components read from MicroBT-shaped device records and render cooling status, fire and water sensors, power meters, and a gauge chart used for temperature readouts. For primitives shared across all container vendors (`EnabledDisableToggle`, `DryCooler`, etc.), see the [Containers overview](/reference/ui/react/foundation/operations). The PDU socket tile has its own [Socket](/reference/ui/react/foundation/operations/containers/socket) page. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - A MicroBT container device record. Cooling components read from `container_specific_stats.cdu`; `PowerMeters` reads from `container_specific_stats.power_meters`. ## Components <ComponentTable category="Containers" subcategory="MicroBT" pkg="foundation" /> ### `GaugeChartComponent` <ComponentDescription name="GaugeChartComponent" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `max` | Required | `number` | none | Maximum value for the gauge | | `value` | Required | `number` | none | Current value | | `unit` | Required | `string` | none | Unit of measurement | | `label` | Optional | `string` | `''` | Title shown above the gauge | | `chartStyle` | Optional | `React.CSSProperties` | `{}` | Inline style on the chart wrapper | | `colors` | Optional | `string[]` | `[COLOR.EMERALD, COLOR.SOFT_TEAL]` | Arc colors in HEX | | `hideText` | Optional | `boolean` | `true` | Hides the built-in percentage text | | `height` | Optional | `number` | `200` | Chart height in pixels | | `className` | Optional | `string` | none | Additional class name on the root | #### Basic usage ```tsx <GaugeChartComponent max={100} value={75.5} label="Temperature" unit="°C" /> ``` #### Styling - `.mdk-gauge-chart-component`: Root element - `.mdk-gauge-chart-component__title`: Gauge title - `.mdk-gauge-chart-component__chart`: Chart wrapper - `.mdk-gauge-chart-component__value`: Value readout row - `.mdk-gauge-chart-component__value-number`: Numeric value text - `.mdk-gauge-chart-component__value-unit`: Unit text ### `MicroBTCooling` <ComponentDescription name="MicroBTCooling" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | none | MicroBT container device record | #### Basic usage ```tsx <MicroBTCooling data={microbtContainer} /> ``` #### Composition - `Cycle Pump` indicator from `cdu.cycle_pump_control` (green `Running`, gray `Off`) - `Main Circulation Pump` panel: status from `circulation_pump_running_status`, switch from `circulation_pump_switch`, speed from `circulation_pump_speed` in `%` or `Hz` - `Cooling Fan` panel: status from `cooling_fan_control`, Kehua-only speed from `cooling_system_status`, switch from `cooling_fan_switch` - `Make Up Pump` panel: status is red on `makeup_water_pump_fault`, green on `makeup_water_pump_control`, gray otherwise; switch from `makeup_water_pump_switch`. #### Styling - `.mdk-micro-bt-cooling`: Root element - `.mdk-micro-bt-cooling__section`: Section wrapper - `.mdk-micro-bt-cooling__section-title`: Section heading - `.mdk-micro-bt-cooling__divider`: Horizontal divider between sections - `.mdk-micro-bt-cooling__row`: Row of items inside a section - `.mdk-micro-bt-cooling__item-row`: Single-row layout (cycle pump) - `.mdk-micro-bt-cooling__item`: Item cell - `.mdk-micro-bt-cooling__label`: Item label text - `.mdk-micro-bt-cooling__value`: Item value text ### `MicroBTSettings` <ComponentDescription name="MicroBTSettings" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `Device` | none | MicroBT container device record | | `containerSettings` | Optional | `object \| null` | `null` | Optional custom inlet temperature thresholds. Shape: `{ thresholds?: Record<string, unknown> }` | #### Basic usage ```tsx <MicroBTSettings data={microbtContainer} /> ``` #### With custom thresholds ```tsx <MicroBTSettings data={microbtContainer} containerSettings={{ thresholds: customThresholds }} /> ``` #### Composition - Renders `ContainerParamsSettings` for the common container parameters block - Renders `MicroBTEditableThresholdForm` wired with MicroBT-specific color, flash, and superflash helpers (`getMicroBtInletTempColor`, `shouldMicroBtTemperatureFlash`, `shouldMicroBtTemperatureSuperflash`) for inlet water temperature #### Styling - `.mdk-micro-bt-settings`: Root element - `.mdk-micro-bt-settings__divider`: Spacer between the params and threshold sections ### `PowerMeters` <ComponentDescription name="PowerMeters" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `Device` | none | MicroBT container device record | #### Basic usage ```tsx <PowerMeters data={microbtContainer} /> ``` #### Rows rendered - `Communication Status`: green `Normal` when `status === 1`, red `Error` otherwise - `Voltage A-B`, `Voltage B-C`, `Voltage C-A`: `voltage_ab`, `voltage_bc`, `voltage_ca` in `V` - `Total Power Factor`: `total_power_factor`, unitless - `Frequency`: `freq` in `Hz` - `Total Active Power`: `total_active_power` in `kW` - `Total Apparent Power`: `total_apparent_power` in `kVA` - `Total Active Energy`: `total_active_energy` in `kWh` #### Styling - `.mdk-power-meters`: Root element - `.mdk-power-meters__panel`: Single power-meter panel wrapper # Socket (/reference/ui/react/foundation/operations/containers/socket) `Socket` renders a single PDU socket cell used inside container floor plans and detail views. It pairs socket identity with live power and current readouts, reflects miner mount state, and supports an add-miner flow in edit mode. For the container vendors that compose sockets into larger layouts, see the [Containers overview](/reference/ui/react/foundation/operations). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - A socket payload: index, enabled flag, optional `power_w` / `current_a`, - (Optional) a mounted [`Miner`](/reference/app-toolkit/ui-devkit/types#device) ### `Socket` <ComponentDescription name="Socket" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `socket` | Optional | `number \| null` | `null` | Socket index shown in the cell | | `enabled` | Optional | `boolean` | `false` | Whether the socket is powered | | `selected` | Optional | `boolean` | `false` | Applies selected visual state | | `current_a` | Optional | `number \| null` | `null` | Current draw in amperes | | `power_w` | Optional | `number \| null` | `null` | Power draw in watts | | `miner` | Optional | `Miner \| null` | `null` | Miner mounted in the socket | | `heatmap` | Optional | `Heatmap \| null` | `null` | Heatmap configuration; see type below | | `cooling` | Optional | `boolean \| undefined` | `undefined` | Shows cooling fan state when set | | `isEditFlow` | Optional | `boolean` | `false` | Renders the add-miner flow UI | | `clickDisabled` | Optional | `boolean` | `false` | Disables socket click interactions | | `isEmptyPowerDashed` | Optional | `boolean` | `false` | Shows zero power with dashed border | | `isContainerControlSupported` | Optional | `boolean` | `false` | Affects tooltip copy for controls | | `pdu` | Optional | `object` | none | PDU metadata used for `data-pdu-index`. Shape: `{ pdu?: string \| number }` | | `innerRef` | Optional | `ForwardedRef<HTMLDivElement>` | none | Forwarded ref to the root element | #### `Heatmap` type ```tsx type Heatmap = { isHeatmapMode?: boolean mode?: string // e.g. 'hashrate' or a temperature field ranges?: Record<string, { min?: number; max?: number }> } ``` #### Basic usage ```tsx <Socket socket={1} enabled power_w={3250} current_a={14.5} miner={minerData} /> ``` #### With heatmap ```tsx <Socket socket={1} enabled miner={minerData} heatmap={{ isHeatmapMode: true, mode: 'chip_avg', ranges: { chip_avg: { min: 40, max: 85 } }, }} /> ``` #### Styling - `.mdk-socket`: Root element - `.mdk-socket--has-cooling`: Cooling fan visible - `.mdk-socket--heatmap`: Heatmap mode active - `.mdk-socket--selected`: Selected state - `.mdk-socket--disabled`: Click disabled - `.mdk-socket__wrapper`: Content wrapper - `.mdk-socket__consumption-box`: Power and current readouts - `.mdk-socket__fan-icon` / `--on`: Cooling fan icon - `.mdk-socket__value`: Individual power or current cell - `.mdk-socket__index`: Socket number badge - `.mdk-socket__add-icon`: Add-miner icon shown in edit flow - `.mdk-socket__connection-icon`: Clock icon shown while connecting # Details view (/reference/ui/react/foundation/operations/details-view) UI for the details view opened from the [device explorer](/reference/ui/react/foundation/operations/device-explorer). These components render device identity, telemetry, hardware state, and operator controls for the currently selected miner, selection of miners, or container. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` wrapping your app tree <Accordions> <Accordion title="Adapter store hooks used across these components"> - Several components read the current selection through `useDevices()` (selected devices or containers) - They queue operator actions through `useActions()` for power mode, reboot, LED, frequency, and maintenance flows </Accordion> </Accordions> - A miner [`Device`](/reference/app-toolkit/ui-devkit/types#device) record (or array of records) shaped per `@tetherto/mdk-react-devkit/foundation`'s `Device` type <Accordions> <Accordion title="Device fields these components read"> - Identity and metadata fields on the `Device` itself - Live telemetry components additionally read `device.last.snap.stats` - Config-driven components additionally read `device.last.snap.config` </Accordion> </Accordions> ## Component groups The category is split into four subpages plus this index, which hosts the shared identity card: - [Charts](/reference/ui/react/foundation/operations/details-view/charts): fleet-level activity visualizations - [Chips](/reference/ui/react/foundation/operations/details-view/chips): per-hashboard ASIC chip telemetry - [Controls](/reference/ui/react/foundation/operations/details-view/controls): miner power mode, reboot, LEDs, frequency, maintenance flow, plus the batch and per-container controls cards - [Fleet management](/reference/ui/react/foundation/operations/details-view/fleet-management): dialogs for adding, replacing, moving, and removing miners across containers - [Stats](/reference/ui/react/foundation/operations/details-view/stats): single and secondary stat cards, aggregated stats, and the combined miner metric card ## All details view components <ComponentTable category="Details view" pkg="foundation" /> ## Shared identity card `MinerInfoCard` is the only component in this category without a subgroup. It anchors every details view as the identity header (model, serial, firmware, IP) and is reused in batch and single-selection layouts alike. ### `MinerInfoCard` <ComponentDescription name="MinerInfoCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `string` | `'Miner info'` | Card header label, rendered uppercase | | `data` | Required | `InfoItem[]` | none | Title and value rows to display | The `InfoItem` shape is re-exported from `@tetherto/mdk-react-devkit/foundation`: ```tsx type InfoItem = { title?: string value?: string | string[] | number } ``` When `value` is an array, each entry is rendered on its own line under the title. #### Basic usage ```tsx <MinerInfoCard label="Miner info" data={[ { title: 'Model', value: 'Antminer S19 Pro' }, { title: 'Serial', value: 'ANT-2024-00142' }, { title: 'Firmware', value: '2.1.3' }, { title: 'IP address', value: '192.168.1.42' }, ]} /> ``` #### Multi-line values Pass an array as `value` to stack rows under a single title (useful for pool URLs, worker names, hashboard ids): ```tsx <MinerInfoCard data={[ { title: 'Pools', value: ['stratum+tcp://pool1.example.com:3333', 'stratum+tcp://pool2.example.com:3333'], }, { title: 'Workers', value: ['worker-1', 'worker-2', 'worker-3'] }, ]} /> ``` #### Composition `MinerInfoCard` wraps [`DeviceInfo`](/reference/app-toolkit/ui-devkit/types#deviceinfo) (from `@tetherto/mdk-react-devkit/foundation`'s `info-container`) and adds the uppercase header label. If you need the bare row layout without the card chrome, use `DeviceInfo` directly. #### Styling - `.mdk-miner-info-card`: root element - `.mdk-miner-info-card__label`: uppercase header label - `.mdk-info-container`: nested per-row title and value wrapper - `.mdk-info-container__title`: row title - `.mdk-info-container__value`: row value (one inner `<div>` per array entry) # Charts (/reference/ui/react/foundation/operations/details-view/charts) Chart components that summarize fleet-wide miner state at a glance. For single-value and aggregated stat cards, see [Stats](/reference/ui/react/foundation/operations/details-view/stats). For miner identity (`MinerInfoCard`), see the [details view overview](/reference/ui/react/foundation/operations). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - A `MinersActivityData` record keyed by status name. Typically derived by grouping a [`Device`](/reference/app-toolkit/ui-devkit/types#device) list by status. ## Components <ComponentTable category="Details view" subcategory="Charts" pkg="foundation" /> ### `MinersActivityChart` <ComponentDescription name="MinersActivityChart" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `MinersActivityData` | `{}` | Counts keyed by status name | | `large` | Optional | `boolean` | `false` | Switch to large indicator and label sizing | | `isLoading` | Optional | `boolean` | `false` | Render a spinner instead of the chart | | `isError` | Optional | `boolean` | `false` | Render `CoreAlert` instead of the chart (unless `isDemoMode`) | | `error` | Optional | `object \| null` | `null` | Message surfaced inside the error alert. Shape: `{ data?: { message?: string } }` | | `showLabel` | Optional | `boolean` | `true` | Show the per-status text label under each indicator | | `isDemoMode` | Optional | `boolean` | `false` | Render zeros on error rather than the alert (for demos) | `MinersActivityData` is an open record. The component renders one indicator per status key it knows about; unknown keys are ignored. #### Statuses rendered The chart fixes the order and color of each indicator: - **Offline**: gray - **Error**: red, with a tooltip noting that minor errors not affecting hash rate are excluded - **Sleep**: power mode - **Low**: yellow, low power mode - **Normal**: green, normal power mode - **High**: purple, high power mode - **Empty**: socket with no miner connected (rendered as `empty` label) #### Basic usage ```tsx <MinersActivityChart data={{ total: 100, offline: 4, error: 1, low: 8, normal: 80, high: 7, }} /> ``` #### Loading and error states ```tsx <MinersActivityChart isLoading /> <MinersActivityChart isError error={{ data: { message: 'Failed to fetch activity data' } }} /> <MinersActivityChart isError isDemoMode /> ``` #### Styling - `.mdk-miners-activity-chart__root`: root flex row - `.mdk-miners-activity-chart__item`: per-status indicator wrapper - `.mdk-miners-activity-chart__item--large`: large variant - `.mdk-miners-activity-chart__label`: status label - `.mdk-miners-activity-chart__label--large`: large label - `.mdk-miners-activity-chart__spinner`: loading spinner - `.mdk-miners-activity-chart__spinner--large`: large spinner # Chips (/reference/ui/react/foundation/operations/details-view/chips) UI for the per-chip thermal and frequency telemetry that surfaces alongside the rest of the details view. `MinerChipsCard` renders a card with one `MinerChip` tile per ASIC; `MinerChip` is also exported on its own for callers that already have per-chip data and want to render their own grid. For miner identity, see the [details view overview](/reference/ui/react/foundation/operations). For aggregated stats, see [Stats](/reference/ui/react/foundation/operations/details-view/stats). For fleet activity, see [Charts](/reference/ui/react/foundation/operations/details-view/charts). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - A [`ContainerStats`](/reference/app-toolkit/ui-devkit/types#containerstats) payload with paired `frequency_mhz.chips` and `temperature_c.chips` arrays <Accordions> <Accordion title="How chip entries are matched and filtered"> - Chips are matched by `index` across the `frequency_mhz.chips` and `temperature_c.chips` arrays - Entries missing any of `min`, `max`, or `avg` temperature are skipped </Accordion> </Accordions> ## Components <ComponentTable category="Details view" subcategory="Chips" pkg="foundation" /> ### `MinerChipsCard` <ComponentDescription name="MinerChipsCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `ContainerStats` | none | Stats payload containing per-chip frequency and temperature arrays | The component reads `data.frequency_mhz.chips` and `data.temperature_c.chips`. Chips are joined by `index`. The card renders nothing when no chip pair is complete. #### Expected chip payload ```tsx type ContainerStats = { frequency_mhz?: { chips?: { index: number; current: number }[] } temperature_c?: { chips?: { index: number; max: number; min: number; avg: number }[] } } ``` #### Basic usage ```tsx <MinerChipsCard data={{ frequency_mhz: { chips: [ { index: 0, current: 500 }, { index: 1, current: 498 }, ], }, temperature_c: { chips: [ { index: 0, max: 72, min: 65, avg: 68 }, { index: 1, max: 70, min: 63, avg: 66 }, ], }, }} /> ``` #### Composition `MinerChipsCard` renders one `MinerChip` per joined entry inside a flex layout. Use `MinerChip` directly when you have already-joined per-chip data and want to skip the join step. #### Styling - `.mdk-miner-chips-card`: root element - `.mdk-miner-chips-card__label`: `Chips` header - `.mdk-miner-chips-card__chips`: flex container holding the chip tiles ### `MinerChip` <ComponentDescription name="MinerChip" /> `MinerChip` is the tile rendered inside `MinerChipsCard`. It is exported for callers that already have per-chip data and want to render their own grid (for example, custom layouts or test fixtures). #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `index` | Required | `number` | none | Chip index, displayed as the tile title (`Chip {index}`) | | `frequency` | Required | \{ current: number \} | none | Current frequency in MHz | | `temperature` | Required | \{ avg: number; min: number; max: number \} | none | Temperature readings in °C | #### Basic usage ```tsx <MinerChip index={0} frequency={{ current: 500 }} temperature={{ avg: 68, min: 65, max: 72 }} /> ``` #### Layout The tile shows, in order: - **Title**: `Chip {index}` - **Temperature**: average value with °C unit - **Min and max**: small paired values labelled `min (°C)` and `max (°C)` - **Frequency**: current value with MHz unit #### Styling - `.mdk-miner-chip`: root element - `.mdk-miner-chip__title`: `Chip {index}` header - `.mdk-miner-chip__property`: `Temperature` and `Frequency` row labels - `.mdk-miner-chip__value`: numeric value with unit - `.mdk-miner-chip__minmax`: min and max value row - `.mdk-miner-chip__value-type`: small label appended to min and max values # Controls (/reference/ui/react/foundation/operations/details-view/controls) Operator controls for the currently selected miner or container. These components queue actions through `useActions()` and surface confirmation through the standard notification hooks. For miner identity, see the [details view overview](/reference/ui/react/foundation/operations). For aggregated stats, see [Stats](/reference/ui/react/foundation/operations/details-view/stats). For fleet activity, see [Charts](/reference/ui/react/foundation/operations/details-view/charts). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` wrapping your app tree <Accordions> <Accordion title="Adapter store hooks required by these components"> - `MinerControlsCard` reads the current device selection from `useDevices()` and pending submissions from `useActions()`, then queues new submissions through `useActions()` - `BatchContainerControlsCard` reads the selected containers from `useDevices()` </Accordion> </Accordions> - The notification hook [`useNotification`](/reference/app-toolkit/hooks/components#usenotification) (from `@tetherto/mdk-react-devkit/foundation`) wired up; control actions notify on submit. ## Components <ComponentTable category="Details view" subcategory="Controls" pkg="foundation" /> ### `MinerControlsCard` <ComponentDescription name="MinerControlsCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `buttonsStates` | Optional | `Record<string, boolean \| undefined>` | none | Per-action disable flags. Currently consumed: `isSetUpFrequencyButtonDisabled` | | `isLoading` | Required | `boolean` | none | Renders the loading spinner and disables every action | | `showPowerModeSelector` | Optional | `boolean` | `true` | Show the embedded `MinerPowerModeSelectionButtons` row | #### Available controls The component renders a different control set depending on the selection and maintenance state: **Standard mode** (any non-maintenance selection): - **Power mode selector**: embedded `MinerPowerModeSelectionButtons` (toggle via `showPowerModeSelector`) - **Reboot**: dispatches `ACTION_TYPES.REBOOT` for every selected miner - **Setup Freq. Settings**: opens the frequency dropdown and dispatches `ACTION_TYPES.SETUP_FREQUENCY_SPEED` with the chosen value - **LEDs on / LEDs off**: dispatches `ACTION_TYPES.SET_LED` for miners whose LED is not already in the requested state - **Move to Maintenance**, **Change miner info**, **Change position**: single-device actions that open the matching dialog flow **Single-miner-in-maintenance mode**: - **Change Miner Info**: opens the change-info dialog - **Back from Maintenance**: opens the container-selection dialog (disabled until the device has a MAC address) - **Remove Miner**: opens the remove-miner dialog The card returns `null` when more than one miner is selected and every selected miner is already in maintenance. #### Basic usage ```tsx <MinerControlsCard buttonsStates={{ isSetUpFrequencyButtonDisabled: false }} isLoading={false} /> ``` #### Hide the power mode selector ```tsx <MinerControlsCard buttonsStates={buttonsStates} isLoading={isLoading} showPowerModeSelector={false} /> ``` #### Composition `MinerControlsCard` composes `MinerPowerModeSelectionButtons`, `MinerSetupFrequencyDropdown`, and four dialogs (`ContainerSelectionDialog`, `RemoveMinerDialog`, `AddReplaceMinerDialog`, `PositionChangeDialog`). The dialogs are mounted unconditionally and toggle visibility through internal state; no wiring required from the caller. #### Styling - `.mdk-miner-controls`: root element - `.mdk-miner-controls__label`: `Miner Controls` header - `.mdk-miner-controls__content`: controls container - `.mdk-miner-controls__loader`: loading spinner - `.mdk-miner-controls__grid`: standard mode button grid - `.mdk-miner-controls__full-width`: full-width button slot - `.mdk-miner-controls__maintenance-stack`: maintenance mode action stack - `.mdk-miner-controls__single-device-stack`: single-device action stack ### `MinerPowerModeSelectionButtons` <ComponentDescription name="MinerPowerModeSelectionButtons" /> `MinerPowerModeSelectionButtons` is rendered inside `MinerControlsCard` by default but is exported as a peer for layouts that want the power-mode dropdown without the rest of the control card (for example, an `Alarm` rail or a custom toolbar). #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `selectedDevices` | Optional | [`Device`](/reference/app-toolkit/ui-devkit/types#device)`[]` | `[]` | Miners targeted by the dropdown; used to derive the model groups | | `setPowerMode` | Required | `function` | none | Callback fired with the matching device subset when a mode is chosen | | `connectedMiners` | Required | `Device[]` | none | Used to compute the current power mode summary when `powerModesLog` is not provided | | `powerModesLog` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Pre-computed per-model current power modes (overrides the derived value) | | `disabled` | Optional | `boolean` | none | Disable every dropdown | | `hasMargin` | Optional | `boolean` | `false` | Add the `--with-margin` modifier on the root | The component groups `selectedDevices` by miner model (via `getDeviceModel`) and renders one dropdown per group. When the selection contains a single model, the button reads `Set Power Mode`; with multiple models, the model name is appended (`Set Power Mode (S19 Pro)`). #### Basic usage ```tsx <MinerPowerModeSelectionButtons selectedDevices={selectedMiners} setPowerMode={(devices, mode) => { console.log('Set power mode:', mode, 'for', devices.length, 'miners') }} /> ``` #### With pre-computed power modes ```tsx <MinerPowerModeSelectionButtons selectedDevices={selectedMiners} powerModesLog={powerModesByModel} setPowerMode={handlePowerModeChange} disabled={isLoading} /> ``` #### Styling - `.mdk-miner-power-mode-selection-buttons`: root element - `.mdk-miner-power-mode-selection-buttons--with-margin`: margin modifier ### `BatchContainerControlsCard` <ComponentDescription name="BatchContainerControlsCard" /> `BatchContainerControlsCard` is the container-level counterpart to `MinerControlsCard`. It renders inside the details view when one or more containers are selected and switches between batch and single-container layouts based on selection size. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `isBatch` | Optional | `boolean` | `true` | Toggle the title between `Batch Container Controls` and `Container Controls` | | `isCompact` | Optional | `boolean` | none | Forwarded to `ContainerControlsBox` for the compact layout | | `connectedMiners` | Optional | `unknown` | none | Forwarded to `ContainerControlsBox` when exactly one container is selected | | `alarmsDataItems` | Optional | `TimelineItemData[]` | none | Forwarded alarm timeline data | | `onNavigate` | Optional | `function` | no-op | Forwarded navigation handler | The card reads the selected containers from `useDevices()` and uses the selection to derive the device record passed into `ContainerControlsBox`. With a single container selected, the full record (plus `connectedMiners`) is forwarded; with multiple containers, only `type` is forwarded, and only when every selected container shares the same model (otherwise `type` is `undefined`, which forces the batch layout). #### Basic usage ```tsx <BatchContainerControlsCard alarmsDataItems={alarmTimelineItems} onNavigate={(path) => router.push(path)} /> ``` #### Single-container compact layout ```tsx <BatchContainerControlsCard isBatch={false} isCompact connectedMiners={connectedMinerCount} alarmsDataItems={alarmTimelineItems} onNavigate={(path) => router.push(path)} /> ``` #### Composition `BatchContainerControlsCard` is a thin shell that renders `ContentBox` (with the batch or single title) wrapping `ContainerControlsBox`. Use `ContainerControlsBox` directly if you need to drive the controls from props instead of the adapter store. #### Styling - `.mdk-batch-container-controls-card`: root element - `.mdk-batch-container-controls-card__controls`: controls wrapper inside the content box ### `ContainerControlsBox` <ComponentDescription name="ContainerControlsBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | none | Container device data | | `isBatch` | Optional | `boolean` | `false` | Enable batch operations mode | | `selectedDevices` | Optional | `Device[]` | `[]` | Selected devices for batch operations | | `pendingSubmissions` | Optional | `PendingSubmission[]` | `[]` | Pending action submissions | | `alarmsDataItems` | Optional | `TimelineItemData[]` | `[]` | Active alarms to display | | `tailLogData` | Optional | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord)`[]` | none | Tail log data for power modes | | `onNavigate` | Required | `function` | none | Navigation handler | #### Basic usage ```tsx <ContainerControlsBox data={container} onNavigate={(path) => router.push(path)} /> ``` #### Batch operations ```tsx <ContainerControlsBox isBatch selectedDevices={selectedContainers} pendingSubmissions={pending} alarmsDataItems={alarms} onNavigate={handleNavigate} /> ``` #### Container type features The component automatically adapts based on container type: - **Bitdeer**: Start/Stop, Reset Alarm, Tank 1/2 toggles, Air Exhaust toggle, Socket controls - **Bitmain Hydro**: Start/Stop Cooling, PID Mode display - **Bitmain Immersion**: Start/Stop Cooling, PID Mode, Running Mode, System Status - **MicroBT**: Start/Stop Cooling, Socket controls #### Styling - `.mdk-container-controls-box`: Root element - `.mdk-container-controls-box__buttons-row`: Action buttons row - `.mdk-container-controls-box__toggles-row`: Toggle switches row - `.mdk-container-controls-box__toggle`: Individual toggle container - `.mdk-container-controls-box__bulk-row`: Bulk action buttons row # Fleet management (/reference/ui/react/foundation/operations/details-view/fleet-management) Dialogs that orchestrate the miner lifecycle launched from the details view: registering a new miner in an empty socket, replacing an existing miner, moving a miner to or from maintenance, changing position between sockets, and permanently removing a miner. For miner identity, see the [details view overview](/reference/ui/react/foundation/operations). For the buttons that open most of these dialogs, see [Controls](/reference/ui/react/foundation/operations/details-view/controls). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` wrapping your app tree <Accordions> <Accordion title="Adapter store hooks required by these dialogs"> - All dialogs queue position, maintenance, and removal updates through `useActions()` - Submissions are validated against existing pending entries, so pending submissions from `useActions()` must be readable - The host application is responsible for draining the pending queue and submitting the action batch upstream </Accordion> </Accordions> - A miner [`Device`](/reference/app-toolkit/ui-devkit/types#device) record (or socket payload containing one) passed in via dialog props <Accordions> <Accordion title="Socket payload shape these dialogs read"> - `selectedEditSocket` and `selectedSocketToReplace` are socket payloads from the device explorer, each carrying a `miner` (`Device`), a `containerInfo` object holding `container`, plus `pos` and `socket` strings - The dialogs read `miner.code`, `miner.tags`, `miner.rack`, `miner.id`, and `miner.info` for short-codes, position text, and the dispatched payload </Accordion> </Accordions> - The notification helpers from `@tetherto/mdk-react-devkit/foundation` wired up; submit actions fire info or success notifications ## Components <ComponentTable category="Details view" subcategory="Fleet management" pkg="foundation" /> ### `PositionChangeDialog` <ComponentDescription name="PositionChangeDialog" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `open` | Required | `boolean` | none | Controls dialog visibility | | `onClose` | Required | `function` | none | Called when the dialog closes; receives the active flow key so callers can decide whether to reset selection state | | `selectedSocketToReplace` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Socket payload for the destination socket in a position-change or replace flow | | `selectedEditSocket` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Socket payload for the miner being edited, replaced, or moved | | `onChangePositionClicked` | Required | `function` | none | Fired when the user picks "Change position" in the default flow | | `onPositionChangedSuccess` | Required | `function` | none | Fired after a successful confirm-change-position submission | | `isContainerEmpty` | Optional | `boolean` | `false` | Hint for the container-selection step that the destination container has no occupied sockets | | `dialogFlow` | Optional | `string` | `''` | Initial flow key from [`POSITION_CHANGE_DIALOG_FLOWS`](/reference/app-toolkit/ui-devkit/constants#position_change_dialog_flows); when omitted the default chooser is shown | #### Internal flows The dialog routes between step-specific surfaces based on the active `dialogFlow` value: | Flow key | Surface rendered | |----------|------------------| | `confirmChange` | `ConfirmChangePositionDialogContent` | | `containerSelection` | `ContainerSelectionDialogContent` | | `replaceMiner`, `changeInfo` | `AddReplaceMinerDialogContent` | | `confirmRemove` | `RemoveMinerDialogContent` | | `maintenance` | `MaintenanceDialogContent` | | _none_ | `DefaultPositionChangeDialogContent` chooser | When both `selectedSocketToReplace` and `selectedEditSocket` are set, the dialog auto advances to the `confirmChange` flow. #### Basic usage ```tsx const [open, setOpen] = useState(false) <PositionChangeDialog open={open} onClose={() => setOpen(false)} selectedEditSocket={selectedEditSocket} dialogFlow={POSITION_CHANGE_DIALOG_FLOWS.CHANGE_INFO} onPositionChangedSuccess={() => refetchInventory()} /> ``` #### Move-to-maintenance flow ```tsx <PositionChangeDialog open={open} onClose={handleClose} selectedEditSocket={selectedEditSocket} dialogFlow={POSITION_CHANGE_DIALOG_FLOWS.MAINTENANCE} /> ``` #### Styling - `.mdk-position-change-dialog`: Root dialog element ### `AddReplaceMinerDialog` <ComponentDescription name="AddReplaceMinerDialog" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `open` | Required | `boolean` | none | Controls dialog visibility | | `onClose` | Required | `function` | none | Called when the dialog closes | | `selectedSocketToReplace` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Socket payload for the empty socket receiving a new miner | | `selectedEditSocket` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Socket payload for an existing miner when running the change-info flow | | `currentDialogFlow` | Required | `string` | none | Flow key from [`POSITION_CHANGE_DIALOG_FLOWS`](/reference/app-toolkit/ui-devkit/constants#position_change_dialog_flows); typically `replaceMiner` or `changeInfo` | | `isDirectToMaintenanceMode` | Optional | `boolean` | `false` | Register the new miner straight into the maintenance container instead of the selected socket | | `minersType` | Required | `string` | none | Restricts the form to a specific miner type (used to gate model-specific validation) | | `isContainerEmpty` | Optional | `boolean` | none | Forwarded to internal validation when registering into an empty container | #### Validation - MAC and serial are validated against pending submissions before dispatch - `isDirectToMaintenanceMode` skips the position picker and uses the maintenance container as the target #### Basic usage ```tsx <AddReplaceMinerDialog open={open} onClose={() => setOpen(false)} selectedSocketToReplace={emptySocket} currentDialogFlow={POSITION_CHANGE_DIALOG_FLOWS.REPLACE_MINER} /> ``` #### Direct-to-maintenance registration ```tsx <AddReplaceMinerDialog open={open} onClose={() => setOpen(false)} selectedSocketToReplace={emptySocket} isDirectToMaintenanceMode /> ``` ### `ContainerSelectionDialog` <ComponentDescription name="ContainerSelectionDialog" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `open` | Required | `boolean` | none | Controls dialog visibility | | `onClose` | Required | `function` | none | Called when the dialog closes | | `miner` | Required | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | none | The miner being moved out of maintenance | | `containers` | Optional | [`Device[]`](/reference/app-toolkit/ui-devkit/types#device) | `[]` | Candidate destination containers shown in the picker | | `isLoading` | Optional | `boolean` | none | Shows a loading state while `containers` is being fetched | #### Behavior - Presets the source as the maintenance container and lets the user pick a destination container and socket - Internally renders `ContainerSelectionDialogContent` with a synthesised `selectedSocketToReplace` of `{ miner, containerInfo: { container: 'maintenance' }, pos: '', socket: '' }` #### Basic usage ```tsx <ContainerSelectionDialog open={open} onClose={() => setOpen(false)} miner={minerUnderMaintenance} containers={availableContainers} isLoading={isContainersLoading} /> ``` ### `MaintenanceDialogContent` <ComponentDescription name="MaintenanceDialogContent" /> This is a content body intended to be rendered inside [`PositionChangeDialog`](#positionchangedialog) (or any host `Dialog`); it does not render its own dialog chrome. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `selectedEditSocket` | Optional | `object` | none | Socket payload for the miner being moved to maintenance. Shape: `Partial<{ miner: Device, containerInfo: { container?: string } }>` | | `onCancel` | Required | `function` | none | Called when the user cancels or after a successful submission | #### Behavior - Confirms the action with the miner short-code and its current container and position - On submit, queues an update action through `useActions()` with the maintenance container, an empty `pos`, and an empty `subnet`, preserving the prior position in `posHistory` - Fires an info notification ("Action added") and calls `onCancel` #### Basic usage ```tsx <MaintenanceDialogContent selectedEditSocket={selectedEditSocket} onCancel={() => setOpen(false)} /> ``` #### Styling - `.mdk-maintenance-confirm`: Root container - `.mdk-maintenance-confirm__warning`: Confirmation copy - `.mdk-maintenance-confirm__highlight`: Inline miner short-code - `.mdk-maintenance-confirm__footer`: Cancel and confirm action row ### `RemoveMinerDialog` <ComponentDescription name="RemoveMinerDialog" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `headDevice` | Optional | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | `{}` | The miner being removed; the dialog reads `info.pos` for the confirmation copy | | `isRemoveMinerFlow` | Required | `boolean` | none | Controls dialog visibility | | `onCancel` | Required | `function` | none | Called when the user cancels or after a successful submission | #### Behavior - Wraps `RemoveMinerDialogContent` inside a `Dialog` with the title "Are you sure to permanently remove miner?" - On confirm, queues the remove action through `useActions()` for the head device #### Basic usage ```tsx <RemoveMinerDialog headDevice={selectedMiner} isRemoveMinerFlow={isRemoveOpen} onCancel={() => setRemoveOpen(false)} /> ``` # Stats (/reference/ui/react/foundation/operations/details-view/stats) Single-value and grouped stat cards plus the combined miner metric layout used by the details view. For miner identity (`MinerInfoCard`), see the [details view overview](/reference/ui/react/foundation/operations). For fleet activity visualizations, see [Charts](/reference/ui/react/foundation/operations/details-view/charts). For per-chip thermal data, see [Chips](/reference/ui/react/foundation/operations/details-view/chips). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - Components on this page read live metrics from `device.last.snap.stats` on a [`Device`](/reference/app-toolkit/ui-devkit/types#device) <Accordions> <Accordion title="Metric fields and adapter store hooks"> - Hash rate in MH/s, temperature in °C, frequency in MHz, and power in W - `StatsGroupCard` additionally requires `useDevices()` so the current device selection is available </Accordion> </Accordions> ## Components <ComponentTable category="Details view" subcategory="Stats" pkg="foundation" /> ### `SingleStatCard` <ComponentDescription name="SingleStatCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `name` | Optional | `string` | none | Stat label | | `subtitle` | Optional | `string` | `''` | Secondary label rendered below the name | | `value` | Optional | `number \| string \| null` | `null` | Stat value; a tooltip is shown when `value` is set | | `unit` | Optional | `string` | `''` | Unit suffix; combined with `value` via [`formatValueUnit`](/reference/app-toolkit/ui-devkit/utilities#formatvalueunit) | | `color` | Optional | `string` | `'inherit'` | CSS color applied via the `--stat-color` custom property | | `flash` | Optional | `boolean` | `false` | Apply the standard flash animation | | `superflash` | Optional | `boolean` | `false` | Apply the faster flash animation | | `tooltipText` | Optional | `string` | `''` | Override for the tooltip label (defaults to `name`) | | `variant` | Optional | `'primary' \| 'secondary' \| 'tertiary' \| 'highlighted'` | `'primary'` | Layout variant | | `row` | Optional | `boolean` | `false` | Stack name and value horizontally | A tooltip is rendered automatically whenever `value` is set; pass `tooltipText` to override the label portion. Values longer than six characters get a `--long-value` modifier for narrower number formatting. Use `primary` through `tertiary` for explorer and device metrics. Use `highlighted` for financial or reporting summary metric strips (same presentation as OSS **MetricCard** `$isHighlighted`, for example EBITDA sell-scenario tiles: large emphasized value, subdued label). #### Basic usage ```tsx <SingleStatCard name="Temperature" value={42} unit="°C" /> <SingleStatCard name="Hash rate" value="95.5" unit="TH/s" /> <SingleStatCard name="Uptime" value="99.7" unit="%" /> ``` #### Variants ```tsx <SingleStatCard name="Temperature" value={42} unit="°C" variant="primary" /> <SingleStatCard name="Fan speed" value={4200} unit="RPM" variant="secondary" /> <SingleStatCard name="Power" value={3250} unit="W" variant="tertiary" /> ``` #### Highlighted (reporting metrics) ```tsx <SingleStatCard name="Revenue" value={4.2} unit="M$" variant="highlighted" /> <SingleStatCard name="OpEx" value={1.8} unit="M$" variant="highlighted" /> <SingleStatCard name="(Sell scenario - all BTC sold)" value={-123.123} unit="$" variant="highlighted" color="#FF8C42" /> <SingleStatCard name="Margin" value={57} unit="%" variant="highlighted" /> ``` #### Alerts with flash ```tsx <SingleStatCard name="Temperature" value={92} unit="°C" color="red" flash /> <SingleStatCard name="Status" value="Overheat" color="#ff0000" superflash /> ``` #### Row layout ```tsx <SingleStatCard name="Efficiency" value="32.5" unit="J/TH" row /> ``` #### Styling - `.mdk-single-stat-card`: root element - `.mdk-single-stat-card--primary`, `--secondary`, `--tertiary`, `--highlighted`: layout variants (`--highlighted` uses a large bold value via `--stat-color`, muted name and subtitle) - `.mdk-single-stat-card--flash`, `--superflash`: animation modifiers - `.mdk-single-stat-card--row`: row layout - `.mdk-single-stat-card--long-value`: applied automatically when value exceeds 6 characters - `.mdk-single-stat-card__name`, `__subtitle`, `__value`, `__text`: inner elements ### `SecondaryStatCard` <ComponentDescription name="SecondaryStatCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `name` | Optional | `string` | `''` | Stat label | | `value` | Optional | `string \| number` | `''` | Stat value | | `className` | Optional | `string` | none | Additional class merged onto the root | #### Basic usage ```tsx <SecondaryStatCard name="Hash rate" value="95.5 TH/s" /> <SecondaryStatCard name="Uptime" value={99.8} /> <SecondaryStatCard name="Efficiency" value="92%" /> ``` #### Styling - `.mdk-secondary-stat-card`: root element - `.mdk-secondary-stat-card__name`: stat label - `.mdk-secondary-stat-card__value`: stat value ### `StatsGroupCard` <ComponentDescription name="StatsGroupCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `miners` | Optional | `Device[] \| DeviceData[]` | none | Devices to aggregate for stat values; falls back to the adapter store selection from `useDevices()` when omitted | | `isMinerMetrics` | Optional | `boolean` | `false` | When `true`, renders `MinerMetricCard` instead of the default `SingleStatCard` grid | #### Aggregated stats Primary stats (always rendered): - **Hash rate**: sum of `snap.stats.hashrate_mhs.t_5m` across the selection, formatted via `getHashrateUnit` - **Temperature**: max of `snap.stats.temperature_c.max`, in °C - **Frequency**: average of `snap.stats.frequency_mhz.avg`, in MHz - **Consumption**: sum of `snap.stats.power_w` (suppressed for miner types where power is not reported) - **Efficiency**: derived `consumption / hash rate` in J/TH, only when both are present Secondary stats depend on layout mode: - **Default grid layout** (`isMinerMetrics={false}`): a second row of `SecondaryStatCard`s when the effective selection (`miners` or the `useDevices()` fallback) has **length 1** (any device type). Values come from the first entry in that set. - **Miner-metrics layout** (`isMinerMetrics={true}`): secondary stats inside `MinerMetricCard` only when the adapter store selection from `useDevices()` contains **exactly one** device whose `type` satisfies `isMiner` (prefix `miner-`). Passing `miners={…}` alone does not enable the secondary strip. Vendor types such as `antminer-s19` are not counted unless `type` uses the `miner-` prefix. #### Basic usage ```tsx <StatsGroupCard miners={selectedMiners} /> ``` #### Render with the miner metric layout ```tsx <StatsGroupCard isMinerMetrics /> ``` When `isMinerMetrics` is true, wire device selection through `useDevices()` and use `miner-*` device types if you need the secondary strip; see **Aggregated stats** above. #### Styling - `.mdk-stats-group-card`: root element - `.mdk-stats-group-card__row`: stat row container ### `MinerMetricCard` <ComponentDescription name="MinerMetricCard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `primaryStats` | Optional | `StatItem[]` | none | Primary metrics keyed by fixed labels (see below) | | `secondaryStats` | Optional | `StatItem[]` | none | Free-form stats rendered in the optional secondary grid | | `showSecondaryStats` | Optional | `boolean` | `true` | When `false`, hides the secondary stats grid | The `StatItem` type is exported from the same module: ```tsx type StatItem = { name?: string value?: number | string unit?: string tooltipText?: string } ``` #### Recognised primary stat names `primaryStats` is read by name. Unknown entries are ignored; only these labels render: - `Efficiency`: rendered top-right. Hidden if value is undefined or non-numeric. - `Hash rate`: top-left primary box - `Temperature`: top-right primary box. Also drives the displayed Frequency value (the source rounds and formats the temperature value as a Frequency stand-in; pass both stats explicitly to keep them aligned). - `Frequency`: bottom-left primary box (uses the formatted `Temperature` numeric for backwards-compat with upstream callers) - `Consumption`: bottom-right primary box. Formatted with three decimals; falls back to `kWh` unit when value is `0`. #### Basic usage ```tsx <MinerMetricCard primaryStats={[ { name: 'Efficiency', value: 32.5, unit: 'J/TH' }, { name: 'Hash rate', value: 95.5, unit: 'TH/s' }, { name: 'Temperature', value: 65, unit: '°C' }, { name: 'Frequency', value: 500, unit: 'MHz' }, { name: 'Consumption', value: 3.25, unit: 'kW' }, ]} secondaryStats={[ { name: 'Fan speed', value: '6000 RPM' }, { name: 'Uptime', value: '3 days' }, ]} /> ``` #### Hide the secondary grid ```tsx <MinerMetricCard primaryStats={primaryStats} secondaryStats={[]} showSecondaryStats={false} /> ``` #### Styling - `.mdk-miner-metric-card`: root element - `.mdk-miner-metric-card__title`: card title (`Miner Metrics`) - `.mdk-miner-metric-card__body`: layout wrapper - `.mdk-miner-metric-card__efficiency`: top-right efficiency block - `.mdk-miner-metric-card__content`: primary and secondary stat grid - `.mdk-miner-metric-card__box`: pair of primary stat items - `.mdk-miner-metric-card__item`: single label/value cell - `.mdk-miner-metric-card__label`: stat label - `.mdk-miner-metric-card__value`: stat value - `.mdk-miner-metric-card__grid-box`: secondary stats grid # Device explorer (/reference/ui/react/foundation/operations/device-explorer) The device explorer is the primary navigation surface for browsing containers, racks, and miners. It combines a filter `Cascader`, a tag-based search, device-type tabs, and a selectable data table so operators can drill into fleet inventory. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ### `DeviceExplorer` <ComponentDescription name="DeviceExplorer" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `deviceType` | Required | `'container' \| 'miner' \| 'cabinet'` | required | Current view type | | `data` | Required | `Device[]` | none | Array of devices to display | | `filterOptions` | Required | `DeviceExplorerFilterOption[]` | none | `Cascader` filter options | | `searchOptions` | Required | `DeviceExplorerSearchOption[]` | none | Search autocomplete options | | `searchTags` | Required | `string[]` | none | Current search tags | | `onSearchTagsChange` | Required | `function` | none | Search tags change handler | | `onDeviceTypeChange` | Required | `function` | none | Device type tab change handler | | `onFiltersChange` | Required | `function` | none | Filter change handler | | `selectedDevices` | Optional | `DataTableRowSelectionState` | `{}` | Selected row state | | `onSelectedDevicesChange` | Optional | `function` | none | Selection change handler | | `renderAction` | Optional | `function` | none | Custom action column renderer | | `getFormattedDate` | Required | `function` | none | Date formatter function | | `className` | Optional | `string` | none | Additional CSS class | #### Basic usage ```tsx <DeviceExplorer deviceType="container" data={containers} filterOptions={[ { value: 'site-a', label: 'Site A' }, { value: 'site-b', label: 'Site B' }, ]} searchOptions={[ { value: 'container-001', label: 'Container 001' }, ]} searchTags={searchTags} onSearchTagsChange={setSearchTags} onDeviceTypeChange={setDeviceType} onFiltersChange={handleFilters} getFormattedDate={(date) => date.toLocaleDateString()} /> ``` #### With selection ```tsx <DeviceExplorer deviceType="miner" data={miners} filterOptions={filterOptions} searchOptions={searchOptions} searchTags={[]} onSearchTagsChange={setSearchTags} onDeviceTypeChange={setDeviceType} onFiltersChange={handleFilters} selectedDevices={selected} onSelectedDevicesChange={setSelected} getFormattedDate={formatDate} renderAction={(device) => ( <Button size="sm" onClick={() => viewDetails(device.id)}> View </Button> )} /> ``` #### Styling - `.mdk-device-explorer`: Root element - `.mdk-device-explorer__toolbar`: Toolbar container - `.mdk-device-explorer__toolbar__filter`: Filter `Cascader` - `.mdk-device-explorer__toolbar__search`: Search input - `.mdk-device-explorer__toolbar__tabs`: Device type tabs - `.mdk-device-explorer__toolbar__tabs-list`: Tabs list container - `.mdk-device-explorer__toolbar__tab-trigger`: Individual tab trigger ## Related hooks | Hook | Supplies | |------|---------| | [`useGetAvailableDevices`](/reference/app-toolkit/hooks/components#usegetavailabledevices) | Transforms the device list into available container and miner type sets consumed by `<DeviceExplorer />` | ## Next steps - For selecting and acting on an individual device, see the [details view](/reference/ui/react/foundation/operations/details-view) pages. - For container-level controls alongside the explorer, see [`ContainerControlsBox`(../details-view/controls#containercontrolsbox) on the Controls page. # Pool Manager (/reference/ui/react/foundation/pool-manager) The Pool Manager section provides UI for landing, exploring miners, and managing pool configurations. It is rendered as a top-level product area with three sibling workflows. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` wrapping your app tree <Accordions> <Accordion title="Adapter store hooks used across these components"> - `PoolManagerMinerExplorer` reads pool configs through `usePoolConfigs` and queues miner-action events through `useActions()` - `PoolManagerPools` reads and mutates pool configuration state through `useActions()`; formatting relies on `useTimezone()` for display-local timestamps - The standalone dashboard has no adapter store dependencies </Accordion> </Accordions> ## Component groups The section is split into five subpages plus this index: - [Dashboard](/reference/ui/react/foundation/pool-manager/dashboard): landing page composing stats, navigation blocks, and a recent alerts feed - [Miner explorer](/reference/ui/react/foundation/pool-manager/miner-explorer): cross-pool miner browser with filter, search, and selection; used to assign miners to pool configurations - [Pools](/reference/ui/react/foundation/pool-manager/pools): pools page with the collapsible pool list and the **Add Pool** dialog for authoring new pool configurations - [Sites overview](/reference/ui/react/foundation/pool-manager/sites-overview): multi-site landing screen showing every site as a status card with pool assignment, miner counts, and hashrate - [Site overview details](/reference/ui/react/foundation/pool-manager/site-overview-details): rack-level miner grid detail view for a single site with drag-to-select and pool assignment ## All pool manager components <ComponentTable category="Pool Manager" pkg="foundation" /> # Assign pool (/reference/ui/react/foundation/pool-manager/assign-pool) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> `AssignPoolModal` opens from the miner explorer to let operators assign a configured pool to one or more selected miners. It shows the selected miner list, a pool selector with live metadata, an endpoints preview, and an optional credential template preview. Submission is async; the modal stays open with a loading state until the parent resolves. For the miner selection surface see [Miner explorer](/reference/ui/react/foundation/pool-manager/miner-explorer). For pool authoring see [Pools](/reference/ui/react/foundation/pool-manager/pools). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` with `useActions()` wired up - Pool configuration data (`PoolConfigData[]`) sourced from your API layer ## Components <ComponentTable category="Pool Manager" subcategory="Assign pool" pkg="foundation" /> ### `AssignPoolModal` <ComponentDescription name="AssignPoolModal" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `isOpen` | Required | `boolean` | none | Controls dialog visibility | | `onClose` | Required | `function` | none | Called when the user cancels or closes the dialog | | `onSubmit` | Required | `function` | none | Async handler called on form submission; modal stays open with a loading state until the promise resolves | | `miners` | Required | `Device[]` | none | Selected miners to assign; displayed in the miner summary table | | `poolConfig` | Required | `PoolConfigData[]` | none | Pool configuration data from your API layer | #### `PoolConfigData` type The input shape passed to `poolConfig`. Each entry maps to one option in the pool selector. ```tsx type PoolConfigData = { id: string poolConfigName: string description: string poolUrls: Array<{ url: string pool: string workerName?: string workerPassword?: string }> miners: number containers: number updatedAt: string | number // Unix timestamp (ms) or ISO string } ``` #### `PoolSummary` type The resolved pool object passed back through `onSubmit`. ```tsx type PoolSummary = { id: string name: string description: string units: number miners: number workerName: string | undefined workerPassword: string | undefined endpoints: PoolEndpoint[] validation?: { status: string } updatedAt: Date } type PoolEndpoint = { role?: string // Primary, Failover, etc. host: string port: string pool: string url?: string } ``` #### Basic usage ```tsx const poolConfig: PoolConfigData[] = [ { id: 'pool-1', poolConfigName: 'Alpha Pool', description: 'Primary pool with failover', poolUrls: [ { url: 'stratum+tcp://pool-primary.example.com:3333', pool: 'pool1', workerName: 'wn-1', workerPassword: 'x' }, { url: 'stratum+tcp://pool-failover.example.com:3333', pool: 'pool1', workerName: 'wn-1', workerPassword: 'x' }, ], miners: 120, containers: 4, updatedAt: Date.now(), }, ] const [isOpen, setIsOpen] = useState(false) const [selectedMiners, setSelectedMiners] = useState<Device[]>([]) const handleSubmit = async ({ pool }: { pool: PoolSummary }) => { await yourApi.assignMinersToPool(selectedMiners.map(m => m.id), pool.id) setIsOpen(false) } return ( <> <button onClick={() => setIsOpen(true)}>Assign Pool</button> <AssignPoolModal isOpen={isOpen} onClose={() => setIsOpen(false)} onSubmit={handleSubmit} miners={selectedMiners} poolConfig={poolConfig} /> </> ) } ``` #### Behaviour The modal renders three sections: 1. **Selected miners** — a `DataTable` showing each miner's short code, unit, current pool assignment, and status. Row count is shown in the section header. 2. **Choose pool** — a `FormSelect` dropdown built from `poolConfig`. On selection, a metadata row appears showing unit count, miner count, and last-updated time (displayed as a relative string via `intlFormatDistance`). Below the metadata, an **Endpoints Preview** lists each endpoint with its role label (Primary, Failover), host, and port. 3. **Credential template preview** (optional) — shown only when the `SHOW_CREDENTIAL_TEMPLATE` feature flag is enabled. The **Assign** button is disabled during submission and shows "Assigning…" while the `onSubmit` promise is pending. The form resets automatically after a successful submission. A `Loader` replaces the form body while pool configs are loading; a `CoreAlert` error is shown if pool config loading fails. #### Styling - `.mdk-pm-assign-pool-modal`: Root dialog element - `.mdk-pm-assign-pool-modal__body`: Form body container - `.mdk-pm-assign-pool-modal__section`: Each labelled content section - `.mdk-pm-assign-pool-modal__section-header`: Section header row (title + optional value) - `.mdk-pm-assign-pool-modal__section-title`: Section label text - `.mdk-pm-assign-pool-modal__section-value`: Section summary value (e.g. "3 miners selected") - `.mdk-pm-assign-pool-modal__pool-meta`: Metadata row shown after a pool is selected - `.mdk-pm-assign-pool-modal__endpoints-list`: Endpoints preview list container - `.mdk-pm-assign-pool-modal__endpoint`: Single endpoint row - `.mdk-pm-assign-pool-modal__endpoint-role`: Endpoint role label wrapper - `.mdk-pm-assign-pool-modal__endpoint-role-name`: Role label text - `.mdk-pm-assign-pool-modal__endpoint-fields`: Host and port fields wrapper - `.mdk-pm-assign-pool-modal__endpoint-host`: Endpoint hostname - `.mdk-pm-assign-pool-modal__endpoint-port`: Endpoint port - `.mdk-pm-assign-pool-modal__credential-template`: Credential template preview section - `.mdk-pm-assign-pool-modal__footer`: Dialog footer containing Cancel and Assign buttons # Dashboard (/reference/ui/react/foundation/pool-manager/dashboard) The Pool Manager dashboard aggregates pool health stats, quick-navigation blocks into the miner explorer and pools workflows, and a feed of recent alerts. It is the entry point rendered when operators land on the Pool Manager area. For miner-to-pool assignment, see [Miner explorer](/reference/ui/react/foundation/pool-manager/miner-explorer). For pool and endpoint management, see [Pools](/reference/ui/react/foundation/pool-manager/pools). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Components <ComponentTable category="Pool Manager" subcategory="Dashboard" pkg="foundation" /> ### `PoolManagerDashboard` <ComponentDescription name="PoolManagerDashboard" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `stats` | Optional | `DashboardStats` | none | Dashboard statistics | | `isStatsLoading` | Optional | `boolean` | `false` | Stats loading state | | `alerts` | Optional | `Alert[]` | `[]` | Recent alerts list | | `onNavigationClick` | Required | `function` | none | Navigation handler | | `onViewAllAlerts` | Required | `function` | none | View all alerts handler | #### `DashboardStats` type ```tsx type StatItem = { label: string value: number type?: 'ERROR' | 'SUCCESS' secondaryValue?: string } type DashboardStats = { items: StatItem[] } ``` #### Basic usage ```tsx <PoolManagerDashboard stats={{ items: [ { label: 'Active Pools', value: 3, type: 'SUCCESS' }, { label: 'Total Miners', value: 150 }, { label: 'Offline', value: 2, type: 'ERROR' }, ], }} alerts={recentAlerts} onNavigationClick={(url) => router.push(url)} onViewAllAlerts={() => router.push('/alerts')} /> ``` #### Loading state ```tsx <PoolManagerDashboard isStatsLoading alerts={[]} onNavigationClick={handleNav} onViewAllAlerts={handleViewAlerts} /> ``` #### Dashboard sections The component displays: 1. **Stats blocks**: Key metrics with optional success/error indicators 2. **Navigation blocks**: Quick links to pool management features 3. **Recent alerts**: Latest alerts with severity indicators #### Styling - `.mdk-pm-dashboard`: Root element - `.mdk-pm-dashboard__stat-blocks`: Stats container - `.mdk-pm-dashboard__stat-block`: Individual stat block - `.mdk-pm-dashboard__stat-header`: Stat header with label and status - `.mdk-pm-dashboard__stat-label`: Stat label text - `.mdk-pm-dashboard__stat-status`: Status indicator - `.mdk-pm-dashboard__stat-value-row`: Value container - `.mdk-pm-dashboard__stat-value`: Primary value - `.mdk-pm-dashboard__stat-secondary`: Secondary value - `.mdk-pm-dashboard__nav-blocks`: Navigation blocks container - `.mdk-pm-dashboard__nav-block`: Individual navigation block - `.mdk-pm-dashboard__nav-header`: Block header with icon - `.mdk-pm-dashboard__nav-icon`: Block icon - `.mdk-pm-dashboard__nav-title`: Block title - `.mdk-pm-dashboard__nav-description`: Block description - `.mdk-pm-dashboard__nav-action`: Action button - `.mdk-pm-dashboard__alerts-wrapper`: Alerts section container - `.mdk-pm-dashboard__alerts-title`: Alerts heading - `.mdk-pm-dashboard__alerts`: Alerts list - `.mdk-pm-dashboard__alert-row`: Individual alert row - `.mdk-pm-dashboard__alert-text`: Alert text content - `.mdk-pm-dashboard__alert-status`: Alert severity indicator - `.mdk-pm-dashboard__alerts-empty`: Empty alerts message ## Related hooks | Hook | Purpose | |------|---------| | [`usePoolStats`](/reference/app-toolkit/hooks/data#usepoolstats) | Aggregate per-pool stats into site-level totals surfaced by the stats strip | | [`useActiveIncidents`](/reference/app-toolkit/hooks/data#useactiveincidents) | Fetch the live list of currently-firing alerts for the alerts panel | | [`useSitesOverviewData`](/reference/app-toolkit/hooks/data#usesitesoverviewdata) | Project container rows and pool stats into the sites overview view-model | ## Next steps - For pool summary widgets that surface on the top-level operations dashboard, see [`PoolDetailsCard`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#pooldetailscard) and [`PoolDetailsPopover`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#pooldetailspopover). # Miner explorer (/reference/ui/react/foundation/pool-manager/miner-explorer) Surface for browsing miners across the fleet and assigning them to pool configurations. `PoolManagerMinerExplorer` is the plug-and-play feature composite that the demo ships with. For pool configuration authoring, see [Pools](/reference/ui/react/foundation/pool-manager/pools). For the Pool Manager landing surface, see [Dashboard](/reference/ui/react/foundation/pool-manager/dashboard). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` with `useActions()` wired up (used by `PoolManagerMinerExplorer` to queue `SETUP_POOLS` actions) - Pool configuration data (`PoolConfigData[]`) and miner `Device[]` arrays. The `Device` shape is documented in [reference types](/reference/app-toolkit/ui-devkit/types) ## Components <ComponentTable category="Pool Manager" subcategory="Miner explorer" pkg="foundation" /> ### `PoolManagerMinerExplorer` <ComponentDescription name="PoolManagerMinerExplorer" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `miners` | Required | `Device[]` | none | Fleet miners to browse | | `poolConfig` | Required | `PoolConfigData[]` | none | Pool configurations used for the pool filter and assign flow | | `backButtonClick` | Required | `function` | none | Fires when the operator clicks the "Pool Manager" back link | #### Behaviour - Renders a page header with title, a back link, and an **Assign Pool** button gated by the `ACTION_TYPES.SETUP_POOLS` permission - Lists miners across the fleet with filter, search, and multi-select - On submit, queues a submission through `useActions()` with the selected miners and the chosen pool, then resets the selection - The Assign Pool button is hidden when the `ASSIGN_POOL_POPUP_ENABLED` feature flag is off #### Basic usage ```tsx <PoolManagerMinerExplorer miners={fleetMiners} poolConfig={poolConfigs} backButtonClick={() => router.push('/pool-manager')} /> ``` #### Styling - `.mdk-pm-miner-explorer-page`: Root element - `.mdk-pm-miner-explorer-page__header`: Title and action row - `.mdk-pm-miner-explorer-page__title`: Page title - `.mdk-pm-miner-explorer-page__subtitle`: Back-link wrapper - `.mdk-pm-miner-explorer-page__back-link`: Back link button # Pools (/reference/ui/react/foundation/pool-manager/pools) Authoring UI for mining pools. `PoolManagerPools` is the plug-and-play feature composite used by the demo; it opens an internal pool-authoring dialog on demand when the **Add Pool** button is clicked. For miner-to-pool assignment via the explorer, see [Miner explorer](/reference/ui/react/foundation/pool-manager/miner-explorer). For the landing surface, see [Dashboard](/reference/ui/react/foundation/pool-manager/dashboard). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` with `useActions()` wired up. `PoolManagerPools` queues pool-config actions through the adapter store - Pool configuration data (`PoolConfigData[]`) sourced from your API layer - Feature flags that gate optional controls: `ADD_POOL_ENABLED`, `SHOW_CREDENTIAL_TEMPLATE`, `SHOW_POOL_VALIDATION` (re-exported from `@tetherto/mdk-react-devkit/foundation`) ## Components <ComponentTable category="Pool Manager" subcategory="Pools" pkg="foundation" /> ### `PoolManagerPools` <ComponentDescription name="PoolManagerPools" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `poolConfig` | Required | `PoolConfigData[]` | none | Pool configuration source; hydrated by `usePoolConfigs` | | `backButtonClick` | Required | `function` | none | Fires when the operator clicks the "Pool Manager" back link | #### Behaviour - Renders a page header (title + back link) with an **Add Pool** button gated by the `ADD_POOL_ENABLED` flag - Shows a loader while `usePoolConfigs` is loading, or a `CoreAlert` on error - Lists every pool in a collapsible accordion: each row shows the pool name, description, unit/miner counts, and a validation badge; expanding a row reveals the endpoints list, credentials template, and a Test Configuration action - Opens an internal pool-authoring dialog when the **Add Pool** button is clicked #### Basic usage ```tsx <PoolManagerPools poolConfig={poolConfigs} backButtonClick={() => router.push('/pool-manager')} /> ``` #### Styling - `.mdk-pm-pools`: Root element - `.mdk-pm-pools__header`: Title and action row - `.mdk-pm-pools__header-title`: Page title - `.mdk-pm-pools__back-link`: Back link button - `.mdk-pm-pools__accordion`: Accordion root - `.mdk-pm-pools__accordion-item`, `.mdk-pm-pools__accordion-trigger`, `.mdk-pm-pools__accordion-content`: Accordion parts ## Related hooks | Hook | Purpose | |------|---------| | [`usePoolRows`](/reference/app-toolkit/hooks/data#usepoolrows) | Fetch per-pool stats and transform them into `PoolRow[]` objects for the pool manager table | | [`usePoolStats`](/reference/app-toolkit/hooks/data#usepoolstats) | Aggregate per-pool stats into site-level totals (workers, mismatch count, hashrate) | | [`usePoolConfigs`](/reference/app-toolkit/hooks/components#usepoolconfigs) | Map caller-provided query data into `PoolSummary[]` for pool summary display | # Site overview details (/reference/ui/react/foundation/pool-manager/site-overview-details) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> `PoolManagerSiteOverviewDetails` is the detail view for a single container site in the Pool Manager. It renders a rack/PDU miner grid, a status legend, and a pool-assignment panel. Operators can multi-select miners by dragging a rectangle over socket cells, then assign pool configurations from the sidebar or modal. For the site card grid that navigates here see [Sites overview](/reference/ui/react/foundation/pool-manager/sites-overview). For the miner-level assign dialog see [Assign pool](/reference/ui/react/foundation/pool-manager/assign-pool). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` with `useActions()` wired up - Site data as a `Device` row from your API layer - Pool configuration data (`PoolConfigData[]`) from your API layer - Optionally, `useSiteOverviewDetailsData` from `@tetherto/mdk-react-adapter` to supply `dataOptions` ## Components <ComponentTable category="Pool Manager" subcategory="Site overview details" pkg="foundation" /> ### `PoolManagerSiteOverviewDetails` <ComponentDescription name="PoolManagerSiteOverviewDetails" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `unit` | Required | `Device` | none | The site (container unit) to render details for | | `unitName` | Required | `string` | none | Display name shown in the breadcrumb (`Site Overview / <unitName>`) | | `poolConfig` | Required | `PoolConfigData[]` | none | Pool configurations powering the per-pool detail rows | | `dataOptions` | Optional | `SiteOverviewDetailsDataOptions` | none | Data-fetch knobs forwarded to `useSiteOverviewDetailsData` | | `isLoading` | Optional | `boolean` | `false` | Show a centered loader instead of the detail container | | `backButtonClick` | Required | `VoidFunction` | none | Called when the operator clicks the "Site Overview" back link | #### Basic usage ```tsx <PoolManagerSiteOverviewDetails unit={site} unitName={site.name} poolConfig={poolConfig} isLoading={isLoading} backButtonClick={() => router.push('/pool-manager/sites')} /> ) ``` #### More examples <Accordions> <Accordion title="Loading state"> ```tsx <PoolManagerSiteOverviewDetails unit={site} unitName={site.name} poolConfig={[]} isLoading={true} backButtonClick={handleBack} /> ``` </Accordion> <Accordion title="With data options"> ```tsx const { dataOptions } = useSiteOverviewDetailsData({ unit: site }) <PoolManagerSiteOverviewDetails unit={site} unitName={site.name} poolConfig={poolConfig} dataOptions={dataOptions} backButtonClick={handleBack} /> ``` </Accordion> </Accordions> #### Behaviour The component renders a breadcrumb header (`Site Overview / <unitName>`) with a back link, then delegates the body to the internal `SiteOverviewDetailsContainer`. The container renders: - A rack/PDU miner grid (`GridUnit`) with each socket showing hashrate, status color, and socket ID - A status legend - A pool-assignment panel when miners are selected: - **Desktop**: sticky sidebar column with `SetPoolConfiguration` - **Tablet**: a fixed FAB button that opens `SetPoolConfigurationModal` On submission the selected miners are queued as a `SETUP_POOLS` action through `useActions().setAddPendingSubmissionAction`, and the selection is cleared. Only miners in `mining` or `not_mining` status are eligible for pool assignment. A `Loader` is shown while `isLoading` is true. ## Miner selection Miners are selected using [`react-selecto`](https://github.com/daybrush/selecto). Selection is always available once the grid has loaded — no prop is required to enable it. ### Interaction reference | Interaction | Result | |-------------|--------| | Drag a rectangle | Selects all miner socket cells intersected by the rectangle | | Click a socket | Selects that single miner | | Shift + click or drag | Adds to the current selection | | Click a rack bar | Selects all miners in that rack | | Control / Command + click a rack bar | Deselects all miners in that rack | | **Select All** (header button) | Selects every miner in the grid | | **Deselect All** (header button) | Clears the selection | Empty sockets (no connected miner) are not selectable. ## Styling ### `PoolManagerSiteOverviewDetails` (feature wrapper) - `.mdk-pm-sod`: Root element - `.mdk-pm-sod__header`: Breadcrumb header row - `.mdk-pm-sod__title`: "Site Overview" label - `.mdk-pm-sod__subtitle`: Back-link wrapper - `.mdk-pm-sod__back-link`: "Site Overview" back button ### `SiteOverviewDetailsContainer` (inner container) - `.mdk-sodc`: Flex row wrapping rack column and sticky column - `.mdk-sodc__racks-col`: Rack grid column; narrows when a sticky sidebar is visible - `.mdk-sodc__racks-col--narrow`: Applied when miners are selected and the sidebar is shown (desktop) - `.mdk-sodc__sticky-col`: Sticky pool-assignment sidebar column (desktop) - `.mdk-sodc__tablet-btn`: Fixed FAB button (tablet, when miners are selected) ### `GridUnit` (rack grid) - `.mdk-grid-unit`: Root of each rack/PDU grid section - `.mdk-grid-unit__row-label`: Rack row label (`Rack {pdu}`) - `.mdk-grid-unit__socket-container`: Selectable miner socket cell (drag-select target) - `.mdk-grid-unit__socket-container--disabled`: Socket cell not eligible for pool assignment - `.mdk-grid-unit__miner-box--selected`: Applied to a miner cell when selected ## Related hooks | Hook | Supplies | |------|---------| | [`useSiteOverviewDetailsData`](/reference/app-toolkit/hooks/components#usesiteoverviewdetailsdata) | Data options forwarded to the container via `dataOptions` prop | # Sites overview (/reference/ui/react/foundation/pool-manager/sites-overview) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> `PoolManagerSitesOverview` is the multi-site landing screen for pool management. It renders every site as a status card showing pool assignment, online miner count, hashrate, and active incidents. Selecting one or more cards exposes a pool-assignment panel (sidebar on desktop, modal on tablet) backed by `useActions()`. For the rack-level miner grid shown after selecting a site card see [Site overview details](/reference/ui/react/foundation/pool-manager/site-overview-details). For the miner-level pool assignment dialog see [Assign pool](/reference/ui/react/foundation/pool-manager/assign-pool). For the pool manager landing page see [Pool Manager overview](/reference/ui/react/foundation/pool-manager). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` with `useActions()` and `useDeviceResolution()` wired up - Site data normalised through `useSitesOverviewData` from `@tetherto/mdk-react-adapter` - Pool configuration data (`PoolConfigData[]`) from your API layer ## Components <ComponentTable category="Pool Manager" subcategory="Sites overview" pkg="foundation" /> ### `PoolManagerSitesOverview` <ComponentDescription name="PoolManagerSitesOverview" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `units` | Required | `ProcessedContainerUnit[]` | none | Sites to render, normalised through `useSitesOverviewData` | | `poolConfig` | Required | `PoolConfigData[]` | none | Pool configurations used to resolve pool names on each card | | `isLoading` | Optional | `boolean` | none | Show a skeleton loader while site data is fetching | | `error` | Optional | `unknown` | none | Surface a "Failed to load data" error alert when defined | | `backButtonClick` | Required | `function` | none | Called when the operator clicks the "Pool Manager" back link | | `onCardClick` | Required | `function` | none | Called with the clicked unit id — typically navigates to `/sites/:id` | #### `ProcessedContainerUnit` type Produced by `useSitesOverviewData` from `@tetherto/mdk-react-adapter`. Pass the result directly to `units`. ```tsx type ContainerUnit = { id?: string type?: string info?: { container?: string nominalMinerCapacity?: string poolConfig?: string // pool config id currently assigned } miners?: { total: number disconnected: number actualMiners: number } last?: { snap?: { stats?: { status?: string; [key: string]: unknown } } } } type ProcessedContainerUnit = ContainerUnit & { hashrateMhs: number // per-container hashrate in MH/s status: 'mining' | 'offline' poolStats?: ContainerPoolStat } ``` #### Basic usage ```tsx rawUnits, poolStats, tailLog, poolConfig, }: { rawUnits: ContainerUnit[] poolStats: ContainerPoolStat[] tailLog: SitesOverviewTailLogItem poolConfig: PoolConfigData[] }) => { const { units } = useSitesOverviewData({ units: rawUnits, poolStats, tailLog }) return ( <PoolManagerSitesOverview units={units} poolConfig={poolConfig} backButtonClick={() => router.push('/pool-manager')} onCardClick={(id) => router.push(`/pool-manager/sites/${id}`)} /> ) } ``` #### More examples <Accordions> <Accordion title="Loading state"> ```tsx <PoolManagerSitesOverview units={[]} poolConfig={[]} isLoading={true} backButtonClick={handleBack} onCardClick={handleCardClick} /> ``` </Accordion> <Accordion title="Error state"> ```tsx <PoolManagerSitesOverview units={[]} poolConfig={poolConfig} error={new Error('Failed to fetch sites')} backButtonClick={handleBack} onCardClick={handleCardClick} /> ``` </Accordion> </Accordions> #### Behaviour The component renders a page header ("Site Overview" title + "Pool Manager" back link) and delegates the card grid to the internal `SitesOverviewStatusCardList`. Each site card shows: - Container / unit name - Assigned pool name (resolved from `poolConfig` via `usePoolConfigs`) - Formatted hashrate - Online miner count - Pool override count - Status indicator (`mining` / `offline`) Selecting one or more cards activates a pool-assignment panel: - **Desktop**: a sticky sidebar column with `SetPoolConfiguration` - **Tablet**: a FAB button that opens `SetPoolConfigurationModal` On submission the selected units are queued as a `SETUP_POOLS` action through `useActions().setAddPendingSubmissionAction`, and the selection is cleared. A `Loader` is shown while `units` or pool configs are loading; a `CoreAlert` error is shown if either fails. #### Styling - `.mdk-pm-sites-overview`: Root element - `.mdk-pm-sites-overview__header`: Title and back-link row - `.mdk-pm-sites-overview__title`: "Site Overview" heading text - `.mdk-pm-sites-overview__subtitle`: Back-link wrapper - `.mdk-pm-sites-overview__back-link`: "Pool Manager" back button - `.mdk-pm-sites-list`: Card grid container (rendered by internal list component) - `.mdk-pm-sites-list__row`: Flex row containing card grid and optional sticky sidebar - `.mdk-pm-sites-list__unit-col`: Card grid column - `.mdk-pm-sites-list__unit-grid`: CSS grid of status cards - `.mdk-pm-sites-list__sticky-col`: Sticky sidebar column (desktop, when units are selected) - `.mdk-pm-sites-list__fab`: Floating action button (tablet, when units are selected) ## Related hooks The following hooks supply live data to `<PoolManagerSitesOverview />`. | Hook | Supplies | |------|---------| | [`useSitesOverviewData`](/reference/app-toolkit/hooks/data#usesitesoverviewdata) | Projects raw container rows and pool stats into the shape accepted by `units` and `isLoading` props | | [`usePoolStats`](/reference/app-toolkit/hooks/data#usepoolstats) | Aggregate pool worker counts and hashrate passed as the `poolStats` option to `useSitesOverviewData` | # Repairs (/reference/ui/react/foundation/repairs) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> Repairs components display spare-part changes recorded in device repair batch actions. Pair with the [Operations centre](/reference/ui/react/foundation/operations) for full device-management context. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Components <ComponentTable category="Repairs" pkg="foundation" /> ### `RepairLogChangesSubRow` <ComponentDescription name="RepairLogChangesSubRow" /> Expandable sub-row that lists the spare-part changes recorded in a repair batch action. Each non-miner repair action is resolved against its device to show the part type, serial number, MAC address, and whether the part was added or removed. Renders as a `DataTable`; shows a `Spinner` when `isLoading` is `true`. The component does no data fetching — the parent fetches the batch action and its associated devices (for example via the things API) and passes them as props. #### Import ```tsx RepairLogChangesSubRowProps, RepairBatchAction, RepairDevice, } from '@tetherto/mdk-react-devkit/foundation' ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `batchAction` | Required | `RepairBatchAction` | none | The repair batch action whose part changes are displayed | | `devices` | Required | `RepairDevice[]` | none | Devices referenced by the batch action, pre-fetched by the parent | | `isLoading` | Optional | `boolean` | `false` | When `true`, renders a spinner instead of the table | #### Supporting types ```tsx type RepairBatchAction = Partial<{ params: RepairAction[] }> type RepairAction = Partial<{ params: RepairActionParam[] }> type RepairActionParam = Partial<{ comment: string id: string rackId: string info: { parentDeviceId: string | null } }> type RepairDevice = Partial<{ id: string rack: string info: Partial<{ serialNum: string macAddress: string }> }> ``` #### Basic usage ```tsx const batchAction: RepairBatchAction = { params: [ { params: [ { id: 'inventory-miner_part-hashboard-001', rackId: 'inventory-miner_part-hashboard', info: { parentDeviceId: null }, }, ], }, ], } const devices: RepairDevice[] = [ { id: 'inventory-miner_part-hashboard-001', rack: 'inventory-miner_part-hashboard', info: { serialNum: 'HB-SN-0001', macAddress: 'AA:BB:CC:00:00:01' }, }, ] <RepairLogChangesSubRow batchAction={batchAction} devices={devices} /> ``` #### Loading state ```tsx <RepairLogChangesSubRow batchAction={batchAction} devices={[]} isLoading /> ``` #### Behavior notes - Miner rack actions and actions with a `comment` field are filtered out — only spare-part changes appear in the table - A part is marked **Removed** when `parentDeviceId` is `null`; **Added** when `parentDeviceId` references a parent device - Part type labels come from `MINER_TYPE_NAME_MAP` and `SparePartNames`; unrecognised rack IDs display as `Unknown` - Pagination is disabled by default ## Next steps - For device-level details, see the [Operations centre](/reference/ui/react/foundation/operations) pages # Reporting tool (/reference/ui/react/foundation/reporting) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> Reporting-tool components cover financial and operational analytics. Host apps supply API or tail-log data; components handle layout, charts, and tab navigation. Every report shares one date-range model through `TimeframeControls`, `ReportTimeFrameSelector`, and `useFinancialDateRange`. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Component groups - [Financial reporting](./financial): revenue, cost, EBITDA, energy balance, hash balance, and subsidy fee reports - [Operational reporting](./operational): operational dashboard, energy consumption, and hashrate reports - [Operational efficiency](./operations-efficiency): three-tab efficiency dashboard (`OperationsEfficiency`) - [Multi-site reporting](./multi-site): portfolio-level `SiteReports` composite ## Reporting components <FoundationComponentTablesByCategory categories={["Reporting tool"]} /> ### `TimeframeControls` <ComponentDescription name="TimeframeControls" /> Date-range picker for financial reporting pages. Supports year, month, and optional week granularity via connected selects. Drives the date range for the cost, EBITDA, energy balance, and other financial reports. #### Import ```tsx ``` #### Props All props are optional. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `dateRange` | Optional | `{ start, end }` | none | Controlled date range in ms epoch; when omitted the control manages its own state | | `onRangeChange` | Optional | `function` | none | Called with `([start, end], { year, month, period })` when the user changes the selection | | `isMonthSelectVisible` | Optional | `boolean` | `true` | Show or hide the month select | | `isWeekSelectVisible` | Optional | `boolean` | `true` | Show or hide the week select | | `showResetButton` | Optional | `boolean` | `false` | Show a Reset button at the end of the toolbar | | `onReset` | Optional | `function` | none | Called when the user clicks Reset | | `layout` | Optional | `'horizontal' \| 'stacked'` | `'horizontal'` | Selects row layout | | `hint` | Optional | `string` | none | Hint text shown above the toolbar in a banded strip | | `timeframeType` | Optional | `TimeframeTypeValue \| null` | none | Controlled timeframe type (year / month / week) | | `onTimeframeTypeChange` | Optional | `function` | none | Called when the resolved timeframe type changes | #### Basic usage ```tsx function ReportPage() { const [dateRange, setDateRange] = useState<FinancialDateRange>() return ( <TimeframeControls isMonthSelectVisible isWeekSelectVisible={false} showResetButton dateRange={dateRange} onRangeChange={(range, opts) => setDateRange({ start: range[0].getTime(), end: range[1].getTime(), period: opts.period }) } onReset={() => setDateRange(undefined)} /> ) } ``` For the backing state machine see [`useTimeframeControls`](/reference/app-toolkit/hooks/components#usetimeframecontrols). ### `ReportTimeFrameSelector` <ComponentDescription name="ReportTimeFrameSelector" /> Compact preset-window picker (1D / 7D / 30D / custom range) used inside the Miner Type and Mining Unit bar views of the operational efficiency and hashrate reports. Pair it with [`useReportTimeFrameSelectorState`](/reference/app-toolkit/hooks/components#usereporttimeframeselectorstate) for the full controlled state. #### Import ```tsx ``` #### Props Props come directly from the `useReportTimeFrameSelectorState` return value; spread them onto the component: | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `presetTimeFrame` | Required | `number \| null` | none | **Required.** Active preset window in days (`1`, `7`, `30`) or `null` when the custom range is active | | `dateRange` | Required | `{ start, end } \| null` | none | **Required.** Controlled date range; `null` while a preset is active | | `setPresetTimeFrame` | Required | `function` | none | **Required.** Setter called when the user selects a preset | | `setDateRange` | Required | `function` | none | **Required.** Setter called when the user picks a custom date range | #### Basic usage ```tsx ReportTimeFrameSelector, useReportTimeFrameSelectorState, } from '@tetherto/mdk-react-devkit/foundation' function EfficiencyBarPanel() { const { presetTimeFrame, dateRange, setPresetTimeFrame, setDateRange } = useReportTimeFrameSelectorState() return ( <ReportTimeFrameSelector presetTimeFrame={presetTimeFrame} dateRange={dateRange} setPresetTimeFrame={setPresetTimeFrame} setDateRange={setDateRange} /> ) } ``` #### Styling - `.mdk-report-time-frame-selector`: Root element ### `MetricCard` <ComponentDescription name="MetricCard" /> Compact card displaying a labelled metric value with an optional unit, highlight state, and transparency. Used across financial and operational reporting composites for cost, EBITDA, hash, and energy metric tiles. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Required | `string` | none | **Required.** Metric label text | | `value` | Required | `number \| string \| null` | none | **Required.** Metric value; `null` renders a fallback dash | | `unit` | Required | `string` | none | **Required.** Unit suffix appended after the value when value is not `null` | | `bgColor` | Optional | `string` | `rgba(0,0,0,0.05)` | Background color CSS value | | `isHighlighted` | Optional | `boolean` | `false` | Apply highlight text color to the value | | `isTransparentColor` | Optional | `boolean` | `false` | Render the value text in a muted / transparent color | | `isValueMedium` | Optional | `boolean` | `false` | Render the value at medium font weight | | `showDashForZero` | Optional | `boolean` | `false` | When `true`, render a dash instead of `0` | | `noMinWidth` | Optional | `boolean` | `false` | Remove the default minimum card width | | `className` | Optional | `string` | none | Root class name from the host app | #### Basic usage ```tsx <MetricCard label="Total Cost" value={42500} unit="USD" /> ``` #### Styling - `.mdk-metric-card`: Root element - `.mdk-metric-card--no-min-width`: Modifier removing the min-width constraint - `.mdk-metric-card__label`: Label text - `.mdk-metric-card__value`: Value text - `.mdk-metric-card__value--medium`: Medium-weight value modifier # Financial reporting (/reference/ui/react/foundation/reporting/financial) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> Financial reporting components cover cost summary, EBITDA, energy balance, hash balance, subsidy fee, and revenue views. Most are self-contained reporting page composites — supply your API data and a `<TimeframeControls>` period selector; the component handles layout, charts, and metric tiles. `RevenueChart` is a standalone stacked-bar chart you can drop into a multi-site financial view. For operational reporting see [Operational](/reference/ui/react/foundation/reporting/operational). For shared controls see the [Reporting tool overview](/reference/ui/react/foundation/reporting). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` ## Components <ComponentTable category="Reporting tool" subcategory="Financial" pkg="foundation" /> ### `TimeframeControls` <ComponentDescription name="TimeframeControls" /> The shared period selector for the reporting composites on this page — pass it into each composite's controls slot (`controls`, `datePicker`, or `timeframeControls` depending on the component). It drives year, month, and week granularity and is also used by the operational surfaces. #### Import ```tsx ``` #### Props All props are optional. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `dateRange` | Optional | `TimeframeControlsDateRange` | — | Currently selected date range driving the connected selects | | `timeframeType` | Optional | `TimeframeTypeValue \| null` | `null` | Active granularity (year / month / week) | | `onRangeChange` | Optional | `TimeframeControlsOnRangeChange` | — | Fires when the selected date range changes | | `onTimeframeTypeChange` | Optional | `(type: TimeframeTypeValue) => void` | — | Fires when the granularity changes | | `isMonthSelectVisible` | Optional | `boolean` | — | Toggles visibility of the month select | | `isWeekSelectVisible` | Optional | `boolean` | — | Toggles visibility of the week select | | `layout` | Optional | `'horizontal' \| 'stacked'` | — | Arrangement of the connected selects | | `showResetButton` | Optional | `boolean` | — | Renders a reset button | | `onReset` | Optional | `VoidFunction` | — | Fires when the reset button is clicked | | `hint` | Optional | `string` | — | Helper text shown alongside the selector | #### Basic usage Pair it with the [`useTimeframeControls`](/reference/app-toolkit/hooks/components#usetimeframecontrols) state machine, then pass it into a composite's controls slot: ```tsx const { dateRange, timeframeType, onRangeChange, onTimeframeTypeChange } = useTimeframeControls({ /* … */ }) <Cost controls={ <TimeframeControls dateRange={dateRange} timeframeType={timeframeType} onRangeChange={onRangeChange} onTimeframeTypeChange={onTimeframeTypeChange} /> } /> ``` #### Behavior Renders connected year / month / week selects. Hide the month or week select via `isMonthSelectVisible` / `isWeekSelectVisible`, switch between inline and stacked arrangement with `layout`, and optionally surface a reset button (`showResetButton` + `onReset`). The selection state itself is owned by [`useTimeframeControls`](/reference/app-toolkit/hooks/components#usetimeframecontrols). ### `Cost` <ComponentDescription name="Cost" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `metrics` | Required | `CostSummaryDisplayMetrics \| null` | none | Derived metric tiles from `buildCostSummaryViewModel` | | `costLog` | Required | `ReadonlyArray<CostTimeSeriesEntry>` | none | Monthly cost time-series for the bar charts | | `btcPriceLog` | Required | `ReadonlyArray<BtcPriceTimeSeriesEntry>` | none | BTC price overlay series | | `totals` | Required | `CostSummaryMonetaryTotals \| null` | none | Aggregate totals for the summary tile | | `dateRange` | Required | `FinancialDateRange \| null` | none | Active period — drives chart x-axis | | `avgAllInCostData` | Optional | `ReadonlyArray<AvgAllInCostDataPoint>` | none | Revenue vs cost series for the Avg All-in Cost panel | | `controls` | Required | `ReactElement` | none | Period selector slot — pass `<TimeframeControls>` | | `setCostAction` | Optional | `ReactElement` | none | Optional header action slot (e.g. a "Set Monthly Cost" link) | | `isLoading` | Optional | `boolean` | `false` | Show a loading state | | `error` | Optional | `unknown` | none | Show an error state when defined | #### Data preparation Use `buildCostSummaryViewModel` to transform a raw API response into the props the component expects: ```tsx const viewModel = buildCostSummaryViewModel({ data: apiResponse }) // → { metrics, costLog, btcPriceLog, totals } ``` #### `FinancialDateRange` type ```tsx type FinancialDateRange = { start: number // epoch ms end: number // epoch ms period?: 'daily' | 'weekly' | 'monthly' | 'yearly' } ``` #### Basic usage ```tsx Cost, buildCostSummaryViewModel, TimeframeControls, PERIOD, } from '@tetherto/mdk-react-devkit/foundation' const [dateRange, setDateRange] = useState<FinancialDateRange>({ start: startOfMonth(new Date()).getTime(), end: endOfMonth(new Date()).getTime(), period: PERIOD.MONTHLY, }) const viewModel = useMemo( () => buildCostSummaryViewModel({ data: apiResponse }), [apiResponse], ) return ( <Cost {...viewModel} dateRange={dateRange} controls={ <TimeframeControls isMonthSelectVisible isWeekSelectVisible={false} dateRange={{ start: dateRange.start, end: dateRange.end }} onRangeChange={(range, opts) => setDateRange({ start: range[0].getTime(), end: range[1].getTime(), period: opts.period }) } /> } /> ) } ``` #### Behavior Renders a "Cost Summary" page header, the `controls` slot (period selector), and the `CostContent` 2×2 grid of charts and metric tiles (production cost chart, operations energy chart, avg all-in cost chart, and cost metric cards). #### Styling - `.mdk-cost`: Root element - `.mdk-cost__header`: Title and optional action row - `.mdk-cost__page-title`: "Cost Summary" heading - `.mdk-cost__controls`: Controls slot wrapper ### `Ebitda` <ComponentDescription name="Ebitda" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `metrics` | Required | `CostSummaryDisplayMetrics \| null` | none | Derived metric tiles from `buildCostSummaryViewModel` | | `ebitdaChartInput` | Required | `ToBarChartDataInput \| null` | none | EBITDA bar chart series | | `btcProducedChartInput` | Required | `ToBarChartDataInput \| null` | none | BTC produced bar chart series | | `hasBtcProducedAllZeros` | Required | `boolean` | none | Hides the BTC produced series when all values are zero | | `showEbitdaBarChart` | Required | `boolean` | none | Toggle the EBITDA bar chart panel | | `currentBTCPrice` | Required | `number` | none | Live BTC price used in metric calculations | | `datePicker` | Required | `ReactElement` | none | Period selector slot | | `hasDateSelection` | Required | `boolean` | none | When `false` shows a "select a period" hint instead of empty data | | `isLoading` | Optional | `boolean` | `false` | Show a loading state | | `errors` | Optional | `string[]` | `[]` | Error messages displayed as an alert | | `setCostHref` | Optional | `string` | none | When provided, shows a "Set Monthly Cost" gear link in the header | #### Basic usage ```tsx <Ebitda metrics={ebitdaMetrics} ebitdaChartInput={ebitdaChartData} btcProducedChartInput={btcProducedData} hasBtcProducedAllZeros={false} showEbitdaBarChart={true} currentBTCPrice={65000} datePicker={<TimeframeControls {...timeframeProps} />} hasDateSelection={true} /> ``` #### Behavior Renders an "EBITDA" page header, period selector slot, and (when `hasDateSelection` is true and data is available) the `EbitdaMetrics` card grid and `EbitdaCharts` panels. Shows a "please select a period" hint when `hasDateSelection` is false. A full-page spinner appears while `isLoading` is true. #### Styling - `.mdk-ebitda`: Root element - `.mdk-ebitda__header`: Title and optional action row - `.mdk-ebitda__page-title`: "EBITDA" heading - `.mdk-ebitda__header-actions`: "Set Monthly Cost" link wrapper - `.mdk-ebitda__controls`: Date picker slot - `.mdk-ebitda__loading`: Spinner overlay - `.mdk-ebitda__error`: Error / empty state container ### `EnergyBalance` <ComponentDescription name="EnergyBalance" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `viewModel` | Required | `EnergyBalanceViewModel` | none | Full view-model from `useEnergyBalance` hook | | `onTabChange` | Required | `function` | none | Called when the Revenue/Cost tab changes | | `onRevenueDisplayModeChange` | Required | `function` | none | Called when the revenue chart display mode toggles | | `onCostDisplayModeChange` | Required | `function` | none | Called when the cost chart display mode toggles | | `timeframeControls` | Optional | `ReactNode` | none | Period selector slot rendered above the tabs | | `setCostHref` | Optional | `string` | none | When provided, shows a "Set Monthly Cost" gear link in the header | | `isDemoMode` | Optional | `boolean` | `false` | Suppresses error alerts (for demo/storybook use) | #### `EnergyBalanceTab` type ```tsx type EnergyBalanceTab = 'revenue' | 'cost' ``` #### Basic usage ```tsx const viewModel = useEnergyBalance({ data: apiData, dateRange }) return ( <EnergyBalance viewModel={viewModel} onTabChange={(tab) => setActiveTab(tab)} onRevenueDisplayModeChange={(mode) => setRevenueMode(mode)} onCostDisplayModeChange={(mode) => setCostMode(mode)} timeframeControls={<TimeframeControls {...timeframeProps} />} /> ) } ``` #### Behavior Renders an "Energy Balance" page header, optional timeframe controls, and a two-tab layout: - **Energy Revenue** — revenue metrics cards, revenue bar chart, [`AverageDowntimeChart`](/reference/ui/react/core/components/charts#averagedowntimechart) (curtailment vs operational issues), power chart - **Energy Cost** — cost metrics cards, cost bar chart, power chart Empty and no-selection states are handled internally. A loading spinner overlays the view while data fetches. #### Styling - `.mdk-energy-balance`: Root element - `.mdk-energy-balance__header`: Title and optional action row - `.mdk-energy-balance__controls`: Timeframe controls slot - `.mdk-energy-balance__tabs`: Tab container - `.mdk-energy-balance__tabs-list`: Tab switcher row - `.mdk-energy-balance__tabs-trigger`: Individual tab button - `.mdk-energy-balance__tabs-content`: Tab panel content area - `.mdk-energy-balance__loading`: Spinner overlay - `.mdk-energy-balance__error`: Error / empty state ### `HashBalance` <ComponentDescription name="HashBalance" /> #### Import ```tsx ``` #### Props All props are optional (the component renders an empty/loading state when omitted). | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `HashRevenueResponse \| null` | — | Hash revenue API response | | `isLoading` | Optional | `boolean` | `false` | Show a loading state | | `isError` | Optional | `boolean` | `false` | Show an error alert | | `errorMessage` | Optional | `string` | `'Error loading hash balance data…'` | Override error message text | | `initialDateRange` | Optional | `FinancialDateRange` | current month | Starting period for the integrated timeframe controls | | `onDateRangeChange` | Optional | `function` | — | Fires when the user changes the period | | `className` | Optional | `string` | — | Root class override | | `tabsClassName` | Optional | `string` | — | Class on the tab container | | `tabsListClassName` | Optional | `string` | — | Class on the tab list | #### Basic usage ```tsx <HashBalance data={hashRevenueData} isLoading={isLoading} onDateRangeChange={(range, query) => fetchHashBalance(query)} /> ``` #### Behavior Renders integrated `TimeframeControls` (year/month/week) with a reset button, and a two-tab layout: - **Hash Revenue** — site hash revenue, network hashrate, and network hashprice charts with metric cards; includes a currency toggle (USD / BTC) - **Hash Cost** — hash cost vs revenue comparison charts Date range is managed internally unless `initialDateRange` is supplied; `onDateRangeChange` fires on every period change. #### Styling - `.mdk-hash-balance`: Root element - `.mdk-hash-balance__loading`: Spinner overlay - `.mdk-hash-balance__error`: Error alert - `.mdk-hash-balance__tabs`: Tab container - `.mdk-hash-balance__tabs-list`: Tab row - `.mdk-hash-balance__tabs-trigger`: Individual tab button - `.mdk-hash-balance__tabs-content`: Tab panel ### `SubsidyFee` <ComponentDescription name="SubsidyFee" /> #### Import ```tsx ``` #### Props All props are optional. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `HashRevenueResponse \| null` | — | Hash revenue API response | | `log` | Optional | `SubsidyFeesLogEntry[]` | — | Per-block log entries (alternative to `data`) | | `isLoading` | Optional | `boolean` | `false` | Show a loading state | | `isError` | Optional | `boolean` | `false` | Show an error alert | | `errorMessage` | Optional | `string` | `'Error loading hash balance data…'` | Override error message text | | `showSummaryCards` | Optional | `boolean` | `false` | Show Total Subsidy, Total Fees, and Average Fees stat cards above the charts | | `onDateRangeChange` | Optional | `function` | — | Fires when the user changes the period | #### Basic usage ```tsx <SubsidyFee data={subsidyFeesData} isLoading={isLoading} showSummaryCards={true} onDateRangeChange={(range, query) => fetchSubsidyFees(query)} /> ``` #### Behavior Renders integrated `TimeframeControls` (year/month/week) and two chart panels side by side: - **Subsidy/Fees** — stacked bar chart of mining reward breakdown (subsidy vs transaction fees) with a % fee ratio overlay on the right y-axis - **Average Fees** — average fees in sats/vbyte bar chart When `showSummaryCards` is true, three `SingleStatCard` tiles (Total Subsidy, Total Fees, Average Fees) appear above the charts. #### Styling - `.mdk-subsidy-fee__panel`: Each chart panel wrapper - `.mdk-subsidy-fee__panel--primary`: Primary variant ### `RevenueChart` <ComponentDescription name="RevenueChart" /> Stacked bar chart showing monthly Bitcoin revenue across multiple mining sites. Values display in BTC when the per-label average exceeds 1 BTC, otherwise they are converted to Sats. #### Import ```tsx ``` #### Props All props are optional (the component renders an empty/loading state when omitted). | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `RevenueDataItem[]` | `[]` | Pre-fetched revenue records — each entry is one time period with a `timeKey`, `period`, `timestamp`, and one numeric value per site ID | | `isLoading` | Optional | `boolean` | `false` | Shows a loading spinner while data is being fetched | | `siteList` | Optional | `(string \| SiteItem)[]` | `[]` | Resolves `data` site IDs to display names in the legend; pass `string[]` of IDs or `{ id, name? }[]` objects | | `legendPosition` | Optional | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Chart legend position | | `legendAlign` | Optional | `'start' \| 'center' \| 'end'` | `'start'` | Chart legend alignment | #### Data shape Each array element is one time bucket; site IDs are dynamic keys holding that site's revenue in BTC: ```ts { timeKey: 'Jan 2024', // X-axis label period: 'monthly', timestamp: 1704067200000, 'site-a': 0.0042, // Revenue in BTC for site-a 'site-b': 0.0031, // Revenue in BTC for site-b } ``` #### Basic usage ```tsx const siteList = [ { id: 'site-a', name: 'Paraguay' }, { id: 'site-b', name: 'Uruguay' }, ] <RevenueChart data={revenueData} siteList={siteList} isLoading={isLoadingRevenue} /> ``` #### Behavior Renders a stacked column chart with one series per site inside a `ChartContainer`. Currency is auto-detected: if any per-label daily average is greater than 1 BTC the chart displays BTC (₿); otherwise values are multiplied by 1,000,000 and shown in Sats. While `isLoading` is true a spinner replaces the chart. No internal data fetching — pass data from your query layer. #### Styling - `.mdk-revenue-chart`: Root element - `.mdk-revenue-chart__header`: Title and currency-unit row - `.mdk-revenue-chart__title`: "Revenue" heading - `.mdk-revenue-chart__unit`: Currency unit label ## Related hooks | Hook | Supplies | |------|---------| | [`useFinancialDateRange`](/reference/app-toolkit/hooks/components#usefinancialdaterange) | Resolves the active financial date range consumed by reporting-section queries | | [`useEbitda`](/reference/app-toolkit/hooks/components#useebitda) | Transforms raw EBITDA API response into the view-model shape for `<Ebitda />` | | [`useEnergyBalanceViewModel`](/reference/app-toolkit/hooks/components#useenergybalanceviewmodel) | Computes the full energy-balance view model (tab and display-mode state) for `<EnergyBalance />` | | [`useHashBalance`](/reference/app-toolkit/hooks/utilities#usehashbalance) | Derives the hash-balance view model for `<HashBalance />` | | [`useSubsidyFees`](/reference/app-toolkit/hooks/utilities#usesubsidyfees) | Derives subsidy-fee series for `<SubsidyFee />` | # Multi-site reporting (/reference/ui/react/foundation/reporting/multi-site) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> `SiteReports` is the multi-site report index — a duration toggle (weekly / monthly / yearly) and a sortable table of published report windows. Each row has a "View Report" action that the caller handles, so the component stays routing-agnostic. For single-site financial reporting see [Financial](/reference/ui/react/foundation/reporting/financial). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Components <ComponentTable category="Reporting tool" subcategory="Multi-site" pkg="foundation" /> ### `SiteReports` <ComponentDescription name="SiteReports" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `pageTitle` | Optional | `string` | `'Reports'` | Heading displayed above the toolbar | | `siteName` | Optional | `string` | — | Optional site label shown below the heading | | `duration` | Optional | `ReportDuration` | — | Controlled duration (`'weekly'`, `'monthly'`, `'yearly'`) | | `defaultDuration` | Optional | `ReportDuration` | `'weekly'` | Initial duration when uncontrolled | | `onDurationChange` | Optional | `function` | — | Fires when the user switches duration | | `reports` | Optional | `SiteReportRecord[]` | auto-generated | Explicit report windows — when omitted, windows are auto-generated from the current date | | `referenceDate` | Optional | `Date` | `new Date()` | Reference point for auto-generating report windows | | `onViewReport` | Optional | `function` | — | Called when the user clicks "View Report" on a row; button is disabled when omitted | | `className` | Optional | `string` | — | Optional root class override | #### `SiteReportRecord` type ```tsx type SiteReportRecord = { from: Date // report window start to: Date // report window end publishedAt: Date // when this report was published } ``` #### `ReportDuration` type ```tsx type ReportDuration = 'weekly' | 'monthly' | 'yearly' ``` #### `SiteReportViewContext` type Passed as the second argument to `onViewReport`: ```tsx type SiteReportViewContext = { duration: ReportDuration siteName?: string } ``` #### Basic usage ```tsx <SiteReports pageTitle="Reports" siteName="EU Site 01" onViewReport={(record, context) => router.push(`/reports/${context.duration}/${record.from.toISOString()}`) } /> ``` #### More examples <Accordions> <Accordion title="Controlled duration"> ```tsx const [duration, setDuration] = useState<ReportDuration>('monthly') <SiteReports pageTitle="Reports" duration={duration} onDurationChange={setDuration} onViewReport={handleViewReport} /> ``` </Accordion> <Accordion title="Providing explicit report windows"> When your API returns pre-computed report records, pass them directly to bypass auto-generation: ```tsx <SiteReports pageTitle="Reports" reports={[ { from: new Date('2026-01-01'), to: new Date('2026-01-07'), publishedAt: new Date('2026-01-08'), }, { from: new Date('2026-01-08'), to: new Date('2026-01-14'), publishedAt: new Date('2026-01-15'), }, ]} onViewReport={handleViewReport} /> ``` </Accordion> </Accordions> #### Behaviour Renders a two-part surface: 1. **Toolbar** — page heading, optional site name, and a segmented duration toggle (Weekly / Monthly / Yearly) implemented as side-variant `Tabs`. 2. **Table** — `DataTable` with three columns: Date (the formatted report window), Date of Publish (formatted `publishedAt`), and Actions (a "View Report" button). Both date columns are sortable. The "View Report" button is disabled when `onViewReport` is not provided. When `reports` is omitted, the component auto-generates windows backwards from `referenceDate` based on the active duration. Duration is uncontrolled by default; pass `duration` + `onDurationChange` to make it controlled. #### Styling - `.mdk-site-reports`: Root element - `.mdk-site-reports__toolbar`: Heading + duration toggle row - `.mdk-site-reports__heading`: Page title text - `.mdk-site-reports__site-name`: Site name label - `.mdk-site-reports__duration`: Duration tab container - `.mdk-site-reports__table`: Data table wrapper - `.mdk-site-reports__view-button`: "View Report" action button ## Related hooks | Hook | Supplies | |------|---------| | [`useHashrate`](/reference/app-toolkit/hooks/components#usehashrate) | Normalises grouped-hashrate query results into the shape consumed by `<SiteReports />` | | [`useEnergyReportSite`](/reference/app-toolkit/hooks/components#useenergyreportsite) | Per-site energy data for the multi-site energy tab | # Operational reporting (/reference/ui/react/foundation/reporting/operational) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> Operational reporting components cover a consolidated operations dashboard (`OperationalDashboard`), energy consumption (`EnergyReport`), and hashrate (`Hashrate`) views. `EnergyReport` and `Hashrate` are multi-tab reporting surfaces with site, miner-type, and mining-unit breakdown charts; `OperationalDashboard` is a 2×2 grid composite of the four core site-operations charts. Each is self-contained — supply your API data and the component handles layout, charts, and tab navigation. For financial reporting see [Financial](/reference/ui/react/foundation/reporting/financial). For operational efficiency see [Operational efficiency](/reference/ui/react/foundation/reporting/operations-efficiency). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - `<MdkProvider>` from `@tetherto/mdk-react-adapter` ## Components <ComponentTable category="Reporting tool" subcategory="Operational" pkg="foundation" /> ### `OperationalDashboard` <ComponentDescription name="OperationalDashboard" /> #### Import ```tsx ``` #### Props All props are optional. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `hashrate` | Optional | `{ data, isLoading }` | none | Pre-shaped hashrate trend data from `useOperationsDashboard` | | `consumption` | Optional | `{ data, isLoading }` | none | Pre-shaped power-consumption trend data | | `efficiency` | Optional | `{ data, isLoading }` | none | Pre-shaped site-efficiency trend data | | `miners` | Optional | `{ data, isLoading }` | none | Pre-shaped miners-status stacked-bar data | | `controls` | Optional | `ReactElement` | none | Optional slot rendered above the grid (for example a date-range picker) | #### Basic usage ```tsx function OperationsDashboardPage({ hashrateLog, consumptionLog, efficiencyLog, minersLog }) { const vm = useOperationsDashboard({ hashrate: { log: hashrateLog, isLoading }, consumption: { log: consumptionLog, isLoading }, efficiency: { log: efficiencyLog, isLoading }, miners: { log: minersLog, isLoading }, }) return ( <OperationalDashboard hashrate={vm.hashrate} consumption={vm.consumption} efficiency={vm.efficiency} miners={vm.miners} /> ) } ``` #### Behavior Renders a 2×2 grid of four `LineChartCard`-based chart cards: hashrate trend, power consumption trend, site efficiency trend, and miners status (stacked bar). Each card has an expand toggle that widens it to full grid width; expand state persists across remounts. Assumes a single `OperationalDashboard` instance is mounted at a time. #### Styling - `.mdk-operational-dashboard`: Root element - `.mdk-operational-dashboard__controls`: Controls slot wrapper (only rendered when `controls` is supplied) - `.mdk-operational-dashboard__grid`: 2×2 chart grid - `.mdk-operational-dashboard__cell`: Individual chart cell - `.mdk-operational-dashboard__cell--expanded`: Modifier applied when a card is expanded to full width ### `EnergyReport` <ComponentDescription name="EnergyReport" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `defaultTab` | Optional | `EnergyReportTabValue` | `'site-view'` | Tab shown on first render — defaults to `'site-view'` | | `siteView` | Optional | `HashrateSiteViewProps` | none | Props for the Site View tab | | `minerTypeView` | Optional | `HashrateMinerTypeViewProps` | none | Props for the Miner Type View tab | | `minerUnitView` | Optional | `EnergyReportMinerUnitViewProps` | none | Props for the Mining Unit View tab | | `className` | Optional | `string` | none | Optional root class override | #### `EnergyReportTabValue` type ```tsx type EnergyReportTabValue = 'site-view' | 'miner-type-view' | 'miner-unit-view' ``` #### `EnergyReportSiteViewProps` key fields ```tsx type EnergyReportSiteViewProps = { consumptionLog?: MetricsConsumptionLogEntry[] // power/consumption time-series nominalPowerAvailabilityMw?: number | null // site nominal capacity containers?: EnergyReportContainer[] // container inventory tailLog?: EnergyReportTailLogItem[][] // snapshot tail-log for power-mode table dateRange?: EnergyReportDateRange // controlled date range onDateRangeChange?: (range: EnergyReportDateRange) => void } ``` #### Basic usage ```tsx <EnergyReport siteView={{ consumptionLog: consumptionData, nominalPowerAvailabilityMw: 500, containers, tailLog, }} minerTypeView={{ groupedConsumption, containers }} minerUnitView={{ groupedConsumption: unitGroupedData, containers }} /> ) ``` #### More examples <Accordions> <Accordion title="Minimal — site view only"> ```tsx <EnergyReport siteView={{ consumptionLog: [ { ts: Date.now() - 86_400_000, powerW: 180_000_000, consumptionMWh: 4.3 }, { ts: Date.now(), powerW: 220_000_000, consumptionMWh: 5.1 }, ], nominalPowerAvailabilityMw: 500, }} /> ``` </Accordion> <Accordion title="Starting on a specific tab"> ```tsx <EnergyReport defaultTab="miner-type-view" minerTypeView={{ groupedConsumption, containers }} /> ``` </Accordion> </Accordions> #### Behavior Renders a three-tab layout: - **Site View** — power consumption trend chart against nominal capacity, power-mode breakdown table per container. A `DateRangePicker` and Reset button appear above this tab only. Date range is managed internally unless `siteView.dateRange` is provided. - **Miner Type View** — consumption grouped by miner type as a bar chart with per-miner-type breakdown. - **Mining Unit View** — consumption grouped by mining unit as a bar chart. Each tab fetches independently via its own prop bag. #### Styling - `.mdk-energy-report`: Root element - `.mdk-energy-report__date-controls`: Date picker + Reset row (site view only) ### `Hashrate` <ComponentDescription name="Hashrate" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `defaultTab` | Optional | `HashrateTabValue` | `'site-view'` | Tab shown on first render | | `siteView` | Optional | `HashrateSiteViewProps` | none | Props for the Site View tab | | `minerTypeView` | Optional | `HashrateMinerTypeViewProps` | none | Props for the Miner Type View tab | | `miningUnitView` | Optional | `HashrateMiningUnitViewProps` | none | Props for the Mining Unit View tab | #### `HashrateTabValue` type ```tsx type HashrateTabValue = 'site-view' | 'miner-type-view' | 'mining-unit-view' ``` #### Site view tab props `HashrateSiteView` renders an aggregate hashrate trend line across the whole site, with an optional miner-type filter that scopes the sum to a subset. A date-range picker and optional reset button appear in the control row. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `log` | Optional | `HashrateGroupedLog` | `[]` | Hashrate log grouped by miner type | | `isLoading` | Optional | `boolean` | `false` | Show a loading state on the chart | | `dateRange` | Optional | `HashrateDateRange` | none | Controlled date range `{ start, end }` in ms epoch; drives the upstream query | | `onDateRangeChange` | Optional | `function` | none | Fires when the user selects a new range from the date picker | | `onReset` | Optional | `function` | none | When provided, renders a Reset button next to the date picker | #### Miner type and mining unit tab props Both `minerTypeView` and `miningUnitView` render bar charts. Charts share axis scaling when both tabs are visible so relative comparisons remain accurate. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `chartInput` | Optional | `ToBarChartDataInput` | none | Declarative bar data (`{ labels, series }`) | | `isEmpty` | Optional | `boolean` | `false` | When `true`, shows the chart empty state | | `isLoading` | Optional | `boolean` | `false` | Show a loading state on the bar chart | #### Basic usage ```tsx <Hashrate siteView={{ log: groupedHashrateLog, isLoading, dateRange, onDateRangeChange: setDateRange, }} minerTypeView={{ chartInput: minerTypeInput, isLoading }} miningUnitView={{ chartInput: miningUnitInput, isLoading }} /> ``` #### More examples <Accordions> <Accordion title="Empty / no-data state"> The component renders an empty shell when no props are supplied — safe to render while data is loading. ```tsx <Hashrate /> ``` </Accordion> <Accordion title="Starting on miner type view"> ```tsx <Hashrate defaultTab="miner-type-view" minerTypeView={{ chartInput: minerTypeInput }} /> ``` </Accordion> </Accordions> #### Behavior Renders a three-tab layout using a shared `Tabs` shell. Each tab fetches independently via its own prop bag: - **Site View** — aggregate hashrate trend line for the whole site with optional miner-type filter; date-range picker and Reset button in the control row - **Miner Type View** — hashrate broken down by miner model/type as a bar chart with a toggle legend - **Mining Unit View** — hashrate broken down per mining unit (container) as a bar chart with a toggle legend Miner type and mining unit bar charts share Y-axis scaling so relative comparisons across tabs remain accurate. Active tab is managed internally. #### Styling - `.mdk-hashrate`: Root element ### `OperationalDashboard` <ComponentDescription name="OperationalDashboard" /> A 2×2 grid of the four site-operations charts — **Hashrate**, **Power Consumption**, **Site Efficiency** (line trends with an optional nominal reference line), and **Miners Status** (stacked daily breakdown). Each card can expand to full width, and the expand state persists across remounts. The composite is pure glue: it renders pre-shaped data. Use the `useOperationsDashboard` hook to turn raw metric logs into the chart-ready payloads, then spread them in — the hook never fetches, so wire your own data layer. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `hashrate` | Optional | `{ data?, isLoading? }` | none | Shaped hashrate trend (`LineChartCardData`) | | `consumption` | Optional | `{ data?, isLoading? }` | none | Shaped power-consumption trend | | `efficiency` | Optional | `{ data?, isLoading? }` | none | Shaped site-efficiency trend | | `miners` | Optional | `{ data?, isLoading? }` | none | Shaped stacked miners-status data | | `controls` | Optional | `ReactElement` | none | Controls slot (e.g. a date-range picker) rendered above the grid | #### `useOperationsDashboard(input)` `input` accepts one entry per chart. Trend inputs take `{ log, nominalValue?, isLoading?, error? }` where `log` is `{ ts, value }[]` in base units (hashrate MH/s, power W, efficiency W/TH/s). The miners input takes per-day `{ ts, online, error, offline, sleep, maintenance }` counts. #### Basic usage ```tsx const Dashboard = ({ queries }) => { const viewModel = useOperationsDashboard({ hashrate: { log: queries.hashrate.log, nominalValue: queries.nominalHashrateMhs }, consumption: { log: queries.consumption.log, nominalValue: queries.nominalPowerW }, efficiency: { log: queries.efficiency.log, nominalValue: queries.nominalEfficiency }, miners: { log: queries.miners.log }, }) return <OperationalDashboard {...viewModel} controls={<DateRangePicker />} /> } ``` #### Behavior Renders the four charts in a 2×2 grid; any card expands to full width and the expand state persists across remounts. Hashrate is displayed in TH/s, power in MW, and efficiency in W/TH/s. A `nominalValue` renders a flat reference line. The individual chart components (`OperationalHashrateChart`, …) and `ChartExpandAction` are exported as `advanced` building blocks for custom layouts. ## Related hooks | Hook | Supplies | |------|---------| | [`useOperationsDashboard`](/reference/app-toolkit/hooks/components#useoperationsdashboard) | Shapes raw operational metric logs into chart-ready payloads for the four `OperationalDashboard` cards | | [`useHashrate`](/reference/app-toolkit/hooks/components#usehashrate) | Normalises a grouped-hashrate query result into the shape consumed by `<Hashrate />` | | [`useEnergyReportSite`](/reference/app-toolkit/hooks/components#useenergyreportsite) | Merges consumption metrics with tail-log and container data for `<EnergyReport />` | | [`useReportTimeFrameSelectorState`](/reference/app-toolkit/hooks/components#usereporttimeframeselectorstate) | Active time-frame window and setters for the time-frame selector | | [`useTimeframeControls`](/reference/app-toolkit/hooks/components#usetimeframecontrols) | Year/month/week state machine for `TimeframeControls` | # Operational efficiency (/reference/ui/react/foundation/reporting/operations-efficiency) <PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge> `OperationsEfficiency` is a three-tab reporting surface: - Site View - Miner Type View - Mining Unit View Your app loads metrics or tail-log data, passes it through the `siteView`, `minerTypeView`, and `minerUnitView` prop bags, and the shell renders charts and time-frame controls. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - [`@tetherto/mdk-react-devkit/core`](/reference/ui/react/core) (tabs and charts are composed from core primitives) ### Import ```tsx OperationsEfficiency, toOperationsEfficiencyMinerType, toOperationsEfficiencyMinerUnit, TAIL_LOG_MINER_TYPE_KEY, TAIL_LOG_CONTAINER_KEY, } from '@tetherto/mdk-react-devkit/foundation' EfficiencyDateRange, MetricsEfficiencyLogEntry, } from '@tetherto/mdk-react-devkit/foundation' ``` ## `OperationsEfficiency` Tab shell built on [`Tabs`](/reference/ui/react/core/components/navigation#tabs) from `@tetherto/mdk-react-devkit/core`. Each tab receives an optional props object; omit a tab’s props to render it with empty defaults. ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `defaultTab` | Optional | `'site-view' \| 'miner-type-view' \| 'mining-unit-view'` | `'site-view'` | Initial active tab key | | `siteView` | Optional | `EfficiencySiteViewProps` | none | Data and callbacks for the Site View line chart | | `minerTypeView` | Optional | `EfficiencyMinerTypeViewProps` | none | Bar chart input for [Miner Type View](#miner-type-and-mining-unit-tabs) | | `minerUnitView` | Optional | `EfficiencyMinerUnitViewProps` | none | Bar chart input for Mining Unit View (same shape as miner type) | ### Site view tab Wire the Site View to **`/auth/metrics/efficiency`** (v2). Map the response log array to [`MetricsEfficiencyLogEntry`](/reference/app-toolkit/ui-devkit/types#metricsefficiencylogentry) and pass it on `siteView.log`. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `log` | Optional | `MetricsEfficiencyLogEntry[]` | `[]` | Time series for the line chart (`ts`, `efficiencyWThs`) | | `avgEfficiency` | Optional | `number \| null` | `null` | Average efficiency for the selected range; shown in the chart header | | `nominalValue` | Optional | `number \| null` | `null` | Nominal efficiency target; when set, adds a nominal series to the chart | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows loading state on the chart container | | `dateRange` | Optional | `EfficiencyDateRange` | none | `{ start, end }` millisecond range for the date picker | | `onDateRangeChange` | Optional | `function` | none | Called when the user selects a new range from the chart brush or date picker | | `onReset` | Optional | `function` | none | Called when the user activates **Reset** on the site chart header | ### Miner type and mining unit tabs Miner Type View and Mining Unit View use bar charts fed by **`ToBarChartDataInput`** (`{ labels, series }`). Until the metrics API supports `groupBy=miner`, build that input from **tail-log** (`stat-5m` / `t-miner`) using the pure helpers below. A backend follow-up will allow swapping the data source in foundation without changing this props contract. | Helper | Input | Output | |--------|--------|--------| | `toOperationsEfficiencyMinerType` | `{ tailLog }` | `{ chartInput, isEmpty }` — reads `TAIL_LOG_MINER_TYPE_KEY` from tail-log | | `toOperationsEfficiencyMinerUnit` | `{ tailLog, containers? }` | `{ chartInput, isEmpty }` — reads `TAIL_LOG_CONTAINER_KEY`; optional `containers` for labels | Pass the result on `minerTypeView` / `minerUnitView`: | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `chartInput` | Optional | `ToBarChartDataInput` | none | Declarative bar data; convert with [`buildBarChartData`](/reference/ui/react/core/components/charts/composition#chart-utilities) if you need Chart.js `data` elsewhere | | `isEmpty` | Optional | `boolean` | `false` | When `true`, shows the chart empty state | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows loading on the bar chart container | | `onTimeFrameChange` | Optional | `function` | none | Called with `(start: Date, end: Date)` when the preset or custom range changes | Each bar view mounts a single-series toggle legend via `ChartContainer`'s `legendData` and `onToggleDataset` props. Clicking the legend item hides or shows the bar series. MDK tooltips on the bars format values with the efficiency unit (`W/TH/s`), consistent with the rest of the reporting surface. ### Example ```tsx OperationsEfficiency, toOperationsEfficiencyMinerType, toOperationsEfficiencyMinerUnit, } from '@tetherto/mdk-react-devkit/foundation' function OperationalEfficiencyPanel({ efficiencyLog, minerTypeTailLog, containerTailLog, }: { efficiencyLog: MetricsEfficiencyLogEntry[] minerTypeTailLog: Record<string, unknown> containerTailLog: Record<string, unknown> }) { const [dateRange, setDateRange] = useState<EfficiencyDateRange | undefined>() const minerType = useMemo( () => toOperationsEfficiencyMinerType({ tailLog: minerTypeTailLog }), [minerTypeTailLog], ) const minerUnit = useMemo( () => toOperationsEfficiencyMinerUnit({ tailLog: containerTailLog }), [containerTailLog], ) return ( <OperationsEfficiency siteView={{ log: efficiencyLog, dateRange, onDateRangeChange: setDateRange, }} minerTypeView={{ chartInput: minerType.chartInput, isEmpty: minerType.isEmpty, }} minerUnitView={{ chartInput: minerUnit.chartInput, isEmpty: minerUnit.isEmpty, }} /> ) } ``` ## Next steps Consider related reference materials: - [Metrics efficiency types](/reference/app-toolkit/ui-devkit/types#metrics-efficiency-types): `MetricsEfficiencyLogEntry` and response wrapper for the site tab - [Chart composition](/reference/ui/react/core/components/charts/composition): `buildBarChartData` for bar chart `data` shapes # Settings components (/reference/ui/react/foundation/settings) The [`@tetherto/mdk-react-devkit/foundation`](/reference/ui/react/foundation) package provides pre-built settings UI for common administrative tasks. Either use: 1. **All-in-one dashboard** ([`SettingsDashboard`](#settings-dashboard)): renders all settings sections in collapsible accordions. 2. **Individual components**: use [`FeatureFlagsSettings`](/reference/ui/react/foundation/settings/feature-flags), [`HeaderControlsSettings`](/reference/ui/react/foundation/settings/header-controls), etc. directly for custom layouts. ## Settings dashboard <ComponentDescription name="SettingsDashboard" /> Each section renders if you provide its props, giving you control over the sections you need. ```tsx ``` ## Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `showFeatureFlags` | Optional | `boolean` | `false` | Show the feature flags section (requires `featureFlagsProps`) | | `headerControlsProps` | Optional | [`HeaderControlsSettingsProps`](/reference/ui/react/foundation/settings/header-controls) | none | Props for header controls section | | `rbacControlProps` | Optional | [`RBACControlSettingsProps`](/reference/ui/react/foundation/settings/access-control) | none | Props for RBAC/user management section | | `importExportProps` | Optional | [`ImportExportSettingsProps`](/reference/ui/react/foundation/settings/import-export) | none | Props for import/export section | | `featureFlagsProps` | Optional | [`FeatureFlagsSettingsProps`](/reference/ui/react/foundation/settings/feature-flags) | none | Props for feature flags section | | `dangerActions` | Optional | `ActionButtonProps[]` | none | Entries forwarded to [`ActionButton`](/reference/ui/react/core/components/forms#actionbutton) (`@tetherto/mdk-react-devkit/core`). See [advanced usage for danger actions with confirmation](#advanced-usage-for-danger-actions-with-confirmation). | | `className` | Optional | `string` | none | Additional CSS class | ## Basic usage ```tsx function SettingsPage() { return ( <SettingsDashboard headerControlsProps={{ preferences: headerPrefs, onToggle: handleToggle, onReset: handleReset, }} rbacControlProps={{ users, roles, rolePermissions, permissionLabels, canWrite: true, onCreateUser, onUpdateUser, onDeleteUser, }} importExportProps={{ onExport: handleExport, onImport: handleImport, onParseFile: parseSettingsFile, }} dangerActions={[ { label: 'Reboot system', variant: 'danger', confirmation: { title: 'Reboot system', description: 'This restarts device Workers. Ensure no pending actions remain.', onConfirm: handleReboot, }, }, ]} /> ) } ``` ## Advanced usage for danger actions with confirmation Use **`dangerActions`** when you need high-impact controls below the **Settings** heading and above the accordion sections. Each item follows **[`ActionButton`](/reference/ui/react/core/components/forms#actionbutton)** props: at minimum `label`, `variant`, and a **`confirmation`** object. Set **`mode: 'dialog'`** for modal confirmations (for example two side-by-side danger actions). ```tsx <SettingsDashboard headerControlsProps= rbacControlProps= importExportProps= dangerActions={[ { label: 'Restart orchestration', variant: 'danger', mode: 'dialog', confirmation: { title: 'Restart orchestration', description: ( <p> Restarts orchestration Workers. Ensure maintenance windows are respected. </p> ), onConfirm: () => { void restartOrchestration() }, }, }, { label: 'Disable automation policy', variant: 'danger', mode: 'dialog', confirmation: { title: 'Disable automation policy', description: 'Automated mitigations will stop until you re-enable the policy.', onConfirm: () => { void disableAutomationPolicy() }, }, }, ]} /> ``` Full **`ActionButton`** semantics (**`confirmation`** fields, **`mode`**, **`loading`**, etc.) live under **[Form components: ActionButton](/reference/ui/react/core/components/forms#actionbutton)**. ## Accordion sections The dashboard renders each settings section inside an [`Accordion`](/reference/ui/react/core/components/data-display#accordion) component from [`@tetherto/mdk-react-devkit/core`](/reference/ui/react/core): - **[Header Controls](/reference/ui/react/foundation/settings/header-controls)**: toggle visibility of header metrics - **[Access control](/reference/ui/react/foundation/settings/access-control)**: manage users and role-based permissions - **[Import / Export](/reference/ui/react/foundation/settings/import-export)**: backup and restore configuration - **[Feature Flags](/reference/ui/react/foundation/settings/feature-flags)**: toggle feature flags (requires `showFeatureFlags={true}`) ## Styling The component uses the `.mdk-settings-dashboard` CSS class. Key selectors: - `.mdk-settings-dashboard__title`: main heading - `.mdk-settings-dashboard__danger-actions`: container for danger action buttons - `.mdk-settings-dashboard__accordions`: container for accordion sections ## Individual components Use these components directly when you need a custom layout or only one settings section: <ComponentTable category="Settings" pkg="foundation" /> # Access control settings (/reference/ui/react/foundation/settings/access-control) <ComponentDescription name="RBACControlSettings" /> It manages: 1. **Access control** (`canWrite`): if `false`, hides edit/delete actions. 2. **User data** (`users`): array of users to display. 3. **Role configuration** (`roles`, `rolePermissions`, `permissionLabels`): define available roles and permissions. 4. **Callbacks** (`onCreateUser`, `onUpdateUser`, `onDeleteUser`): handle CRUD operations. 5. **State** (`isLoading`): loading indicator. 6. **Styling** (`className`): optional CSS class. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Import ```tsx ``` ## Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `canWrite` | Required | `boolean` | none | If `false`, hides edit/delete actions | | `users` | Required | `SettingsUser[]` | none | Array of users to display | | `roles` | Required | `RoleOption[]` | none | Available roles for assignment | | `rolePermissions` | Required | `Record<string, Record<string, PermLevel>>` | none | Permissions matrix by role | | `permissionLabels` | Required | `Record<string, string>` | none | Human-readable permission names | | `onCreateUser` | Required | `function` | none | Create user callback | | `onUpdateUser` | Required | `function` | none | Update user callback | | `onDeleteUser` | Required | `function` | none | Delete user callback | | `isLoading` | Optional | `boolean` | `false` | Loading state | | `className` | Optional | `string` | none | Additional CSS class | ## Data structure ```tsx SettingsUser, RoleOption, PermLevel, } from '@tetherto/mdk-react-devkit/foundation' type SettingsUser = { id: string name?: string email: string role: string lastActive?: string last_login?: string } type RoleOption = { value: string label: string } type PermLevel = 'r' | 'rw' | false // read, read-write, none type CreateUserData = { name: string email: string role: string } type UpdateUserData = CreateUserData & { id: string } ``` ## Callbacks ### `onCreateUser` Called when end user submits the add user form. Receives `CreateUserData`: ```tsx const handleCreateUser = async (data: CreateUserData) => { const newUser = await api.createUser(data) setUsers(prev => [...prev, newUser]) } ``` ### `onUpdateUser` Called when end user saves changes in the manage modal. Receives `UpdateUserData`: ```tsx const handleUpdateUser = async (data: UpdateUserData) => { await api.updateUser(data) setUsers(prev => prev.map(u => u.id === data.id ? { ...u, ...data } : u)) } ``` ### `onDeleteUser` Called after end user confirms deletion. Receives the user ID: ```tsx const handleDeleteUser = async (userId: string) => { await api.deleteUser(userId) setUsers(prev => prev.filter(u => u.id !== userId)) } ``` ## Basic usage ```tsx function UserManagementSection() { const [users, setUsers] = useState<SettingsUser[]>([]) const [isLoading, setIsLoading] = useState(true) useEffect(() => { api.getUsers().then(data => { setUsers(data) setIsLoading(false) }) }, []) const handleCreateUser = async (data) => { const newUser = await api.createUser(data) setUsers(prev => [...prev, newUser]) } const handleUpdateUser = async (data) => { await api.updateUser(data) setUsers(prev => prev.map(u => u.id === data.id ? { ...u, ...data } : u) ) } const handleDeleteUser = async (userId) => { await api.deleteUser(userId) setUsers(prev => prev.filter(u => u.id !== userId)) } return ( <RBACControlSettings canWrite={true} users={users} roles={[ { value: 'admin', label: 'Admin' }, { value: 'operator', label: 'Operator' }, { value: 'viewer', label: 'Viewer' }, ]} rolePermissions={{ admin: { miners: 'rw', settings: 'rw', users: 'rw' }, operator: { miners: 'rw', settings: 'r', users: false }, viewer: { miners: 'r', settings: 'r', users: false }, }} permissionLabels={{ miners: 'Miner Management', settings: 'Settings', users: 'User Management', }} isLoading={isLoading} onCreateUser={handleCreateUser} onUpdateUser={handleUpdateUser} onDeleteUser={handleDeleteUser} /> ) } ``` ## Features ### User table Displays users in a table with columns: - **User**: name with tooltip - **Email**: email address with tooltip - **Assigned Roles**: role badge with color coding - **Last Active**: formatted timestamp - **Manage**: opens edit modal - **Delete**: deletes with confirmation ### Search Filter users by name, email, or role using the search input. ### Role badges Roles are displayed as colored badges. Colors are determined by [`getRoleBadgeColors()`](/reference/app-toolkit/ui-devkit/constants#getrolebadgecolors) from the foundation constants. ### Integrated modals The component includes three modal dialogs: - `AddUserModal`: create new users - `ManageUserModal`: edit user details and view permissions - `ChangeConfirmationModal`: confirm destructive actions ## Permission check When `canWrite` is `false`: - **Add User** button is hidden - **Manage** and **Delete** buttons are hidden - User list is read-only ```tsx <RBACControlSettings canWrite={false} // Read-only mode // ...other props /> ``` ## Styling The component uses the `.mdk-settings-rbac` CSS class. Key selectors: - `.mdk-settings-rbac__description`: header text - `.mdk-settings-rbac__actions-row`: search and add button row - `.mdk-settings-rbac__table`: user table container - `.mdk-settings-rbac__role-badge`: role badge styling - `.mdk-settings-rbac__manage-btn`: manage button - `.mdk-settings-rbac__delete-btn`: delete button # Feature flags settings (/reference/ui/react/foundation/settings/feature-flags) <ComponentDescription name="FeatureFlagsSettings" /> It manages: 1. **User access control** (`isEditingEnabled`): if `false`, shows empty state and user is not provided with toggles. 2. **What data?** (`featureFlags`): the flags to display as toggles. 3. **What happens on save?** (`onSave`): callback receiving updated flags. 4. **State indicators** (`isLoading`, `isSaving`): optional user feedback on loading/saving states. 5. **Styling** (`className`): optional CSS class. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Import ```tsx ``` ## Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `isEditingEnabled` | Required | `boolean` | none | If `false`, shows empty state and other props have no effect | | `featureFlags` | Required | `Record<string, boolean>` | none | Object mapping flag names to enabled/disabled state | | `onSave` | Required | `function` | none | Callback when save is clicked | | `isLoading` | Optional | `boolean` | `false` | Loading state | | `isSaving` | Optional | `boolean` | `false` | Saving state | | `className` | Optional | `string` | none | Additional CSS class | ## Data structure The `featureFlags` prop accepts an object where: - **Keys** are flag names (arbitrary strings defined by your application) - **Values** are booleans (`true` = enabled, `false` = disabled) ```tsx { darkMode: true, betaFeatures: false, advancedMetrics: true, } ``` This component renders toggles for whatever flags you pass in. Your application or backend determines the available flags. ## Basic usage Changes are held locally until the user clicks Save. The `onSave` callback receives the updated flags object: ```tsx const handleSave = async (updatedFlags: Record<string, boolean>) => { await api.saveFeatureFlags(updatedFlags) // persist to backend setFlags(updatedFlags) // update local state } ``` <Callout type="warning"> The component does not persist data, you must implement the save logic. </Callout> ### Example ```tsx function FeatureFlagsPage() { // Flags reflecting your API or app config const [flags, setFlags] = useState<Record<string, boolean>>({ darkMode: true, betaFeatures: false, advancedMetrics: true, }) const [isSaving, setIsSaving] = useState(false) const handleSave = async (updatedFlags: Record<string, boolean>) => { setIsSaving(true) await api.saveFeatureFlags(updatedFlags) setFlags(updatedFlags) setIsSaving(false) } return ( <FeatureFlagsSettings featureFlags={flags} isEditingEnabled={true} isSaving={isSaving} onSave={handleSave} /> ) } ``` ## Features ### Add flags Developers add new feature flags through the UI by entering comma-separated names. Flag names are arbitrary strings; the component does not validate against a predefined list. ### Toggle flags Each flag displays a toggle switch to enable/disable it. Changes are held locally until the end user clicks **Save**. ### Delete flags End user can click the trash icon next to any flag to remove it from the list. ## Permission check When `isEditingEnabled` is `false`, the component renders an empty state: ```tsx <FeatureFlagsSettings featureFlags={flags} isEditingEnabled={false} // Shows "Update feature flags not enabled" onSave={handleSave} /> ``` ## Integration Feature flags are typically fetched from your backend API. This component provides the UI for viewing and editing them, it does not manage persistence. Use the `onSave` callback to sync changes back to your server. ## Styling The component uses the `.mdk-settings-feature-flags` CSS class. Key selectors: - `.mdk-settings-feature-flags__add-row`: Input and add button container - `.mdk-settings-feature-flags__toggles`: Grid of flag toggles - `.mdk-settings-feature-flags__flag-item`: Individual flag row - `.mdk-settings-feature-flags__save`: Save button container ## Related hooks | Hook | Supplies | |------|---------| | [`useIsFeatureEditingEnabled`](/reference/app-toolkit/hooks/utilities#useisfeatureeditingenabled) | Permission guard that returns `true` when the current user can toggle feature flags | # Header controls settings (/reference/ui/react/foundation/settings/header-controls) <ComponentDescription name="HeaderControlsSettings" /> It provides: 1. **Data** (`preferences`): current visibility state for header items. 2. **Callbacks** (`onToggle`, `onReset`): handle changes and reset to defaults. 3. **State** (`isLoading`): optional loading feedback. 4. **Styling** (`className`): optional CSS class. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Import ```tsx ``` ## Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `preferences` | Required | [`HeaderPreferences`](/reference/app-toolkit/ui-devkit/constants#headerpreferences-type) | none | Current header visibility preferences | | `onToggle` | Required | `function` | none | Callback when a toggle changes | | `onReset` | Required | `function` | none | Callback to reset to defaults | | `isLoading` | Optional | `boolean` | `false` | Loading state | | `className` | Optional | `string` | none | Additional CSS class | ## Data structure The `HeaderPreferences` type maps header item keys to visibility booleans. See [constants](/reference/app-toolkit/ui-devkit/constants#header-controls) for the full list. ```tsx type HeaderPreferences = { poolMiners: boolean miners: boolean poolHashrate: boolean hashrate: boolean consumption: boolean efficiency: boolean } ``` ## Basic usage Changes apply instantly via `onToggle`. The callback receives the preference key and new value: ```tsx const handleToggle = (key: keyof HeaderPreferences, value: boolean) => { setPreferences(prev => ({ ...prev, [key]: value })) api.updateHeaderPreference(key, value) // persist immediately } ``` <Callout type="info"> There is no **Save** button, each toggle immediately persists via your callback. </Callout> ### Example ```tsx function HeaderSettingsSection() { const [preferences, setPreferences] = useState<HeaderPreferences>({ poolMiners: true, miners: true, poolHashrate: true, hashrate: false, consumption: true, efficiency: true, }) const handleToggle = (key: keyof HeaderPreferences, value: boolean) => { setPreferences(prev => ({ ...prev, [key]: value })) api.updateHeaderPreference(key, value) } const handleReset = () => { setPreferences(DEFAULT_HEADER_PREFERENCES) api.resetHeaderPreferences() } return ( <HeaderControlsSettings preferences={preferences} onToggle={handleToggle} onReset={handleReset} /> ) } ``` ## Features ### Table layout The component renders a table with: - **Header Item** column: label for the metric - **Visibility Toggle** column: switch to show/hide Items are defined by [`HEADER_ITEMS`](/reference/app-toolkit/ui-devkit/constants#header_items). Labels for the in-app rows (`miners`, `hashrate`) are composed from [`WEBAPP_SHORT_NAME`](/reference/app-toolkit/ui-devkit/constants#webapp_short_name), so they reflect the brand string the foundation kit ships with. ### Reset to default The **Reset to Default** button calls your `onReset` callback. You define what "default" means: ```tsx const handleReset = () => { setPreferences(DEFAULT_HEADER_PREFERENCES) api.resetHeaderPreferences() } ``` ## Loading state When `isLoading` is `true` and no preferences are available, a spinner is shown: ```tsx <HeaderControlsSettings preferences={null} isLoading={true} onToggle={handleToggle} onReset={handleReset} /> ``` ## Styling The component uses the `.mdk-settings-header-controls` CSS class. Key selectors: - `.mdk-settings-header-controls__description`: Explanatory text - `.mdk-settings-header-controls__table`: Table container - `.mdk-settings-header-controls__table-header`: Header row - `.mdk-settings-header-controls__table-row`: Data rows - `.mdk-settings-header-controls__actions`: Reset button container ## Related hooks | Hook | Supplies | |------|---------| | [`useHeaderControls`](/reference/app-toolkit/hooks/components#useheadercontrols) | Read/write access to the global header-controls store — toggle visibility, set sticky state, and read current values | # Header items (/reference/ui/react/foundation/settings/header-controls/header-items) The header bar components that render live stats and controls in the persistent app header. Visibility for each item is governed by [`HeaderControlsSettings`](/reference/ui/react/foundation/settings/header-controls) and the `HeaderPreferences` object. For vendor-agnostic dashboard body cards see [Dashboard › Stats › Generic widgets](/reference/ui/react/foundation/dashboard/stats/generic-widgets). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Components <ComponentTable category="Settings" subcategory="Header controls" pkg="foundation" /> --- ### `HeaderStatsBar` <ComponentDescription name="HeaderStatsBar" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `children` | Required | `ReactNode` | none | Stat box components to render left-to-right | | `className` | Optional | `string` | none | Optional root class override | #### Basic usage `HeaderStatsBar` is a slot-based container. Pass the stat boxes you want to show as children — the bar inserts an angled chevron divider between each pair automatically. ```tsx HeaderStatsBar, HeaderMinersBox, HeaderHashrateBox, HeaderConsumptionBox, HeaderEfficiencyBox, } from '@tetherto/mdk-react-devkit/foundation' <HeaderStatsBar> <HeaderMinersBox total={2188} online={158} error={1} offline={57} mosTotal={216} poolTotal={205} poolOnline={201} poolMismatch={4} /> <HeaderHashrateBox mosPhs={63.262} poolPhs={52.687} /> <HeaderConsumptionBox valueMw={1.663} /> <HeaderEfficiencyBox valueWthS={26.29} /> </HeaderStatsBar> ``` #### Styling - `.mdk-header-stats-bar`: Root flex strip - `.mdk-header-stats-bar__divider`: Angled chevron icon between children --- ### `HeaderMinersBox` <ComponentDescription name="HeaderMinersBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `total` | Optional | `number` | none | Total miners on site (denominator) | | `online` | Optional | `number` | none | Online miner count (green, also the numerator in the ratio) | | `error` | Optional | `number` | none | Miners in warning state (amber) | | `offline` | Optional | `number` | none | Offline miners (red) | | `mosTotal` | Optional | `number` | none | Total miners reporting to MOS | | `poolTotal` | Optional | `number` | none | Total miners as reported by upstream pools | | `poolOnline` | Optional | `number` | none | Pool-side online count (green) | | `poolMismatch` | Optional | `number` | none | Pool-side mismatch count (red) | | `icon` | Optional | `ReactNode` | none | Override the default miner icon | | `className` | Optional | `string` | none | Optional root class override | All numeric values fall back to `—` when undefined. #### Basic usage ```tsx <HeaderMinersBox total={2188} online={158} error={1} offline={57} mosTotal={216} poolTotal={205} poolOnline={201} poolMismatch={4} /> ``` #### Styling - `.mdk-header-stat-box`: Shared stat cell root - `.mdk-header-stat-box__icon`: Icon slot - `.mdk-header-stat-box__body`: Text content area - `.mdk-header-stat-box__row`: Each label/value row - `.mdk-header-stat-box__success`: Green value (online) - `.mdk-header-stat-box__warning`: Amber value (error) - `.mdk-header-stat-box__danger`: Red value (offline / mismatch) - `.mdk-header-stat-box__accent`: Highlighted online ratio - `.mdk-header-stat-box__muted`: Subdued label text --- ### `HeaderHashrateBox` <ComponentDescription name="HeaderHashrateBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `mosPhs` | Optional | `number` | none | MOS-side aggregate hashrate in PH/s | | `poolPhs` | Optional | `number` | none | Pool-side aggregate hashrate in PH/s | | `unit` | Optional | `string` | varies | Unit label — see individual component for default | | `icon` | Optional | `ReactNode` | none | Override the default miner icon | | `className` | Optional | `string` | none | Optional root class override | #### Basic usage ```tsx <HeaderHashrateBox mosPhs={63.262} poolPhs={52.687} /> ``` --- ### `HeaderConsumptionBox` <ComponentDescription name="HeaderConsumptionBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `valueMw` | Optional | `number` | none | Current site-level power consumption in megawatts | | `unit` | Optional | `string` | varies | Unit label — see individual component for default | | `icon` | Optional | `ReactNode` | none | Override the default miner icon | | `className` | Optional | `string` | none | Optional root class override | The value is formatted to 3 decimal places and rendered in the accent (orange) colour token. #### Basic usage ```tsx <HeaderConsumptionBox valueMw={1.663} /> ``` --- ### `HeaderEfficiencyBox` <ComponentDescription name="HeaderEfficiencyBox" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `valueWthS` | Optional | `number` | none | Efficiency in W/TH/s (`power_w / hashrate_th`) | | `unit` | Optional | `string` | varies | Unit label — see individual component for default | | `icon` | Optional | `ReactNode` | none | Override the default miner icon | | `className` | Optional | `string` | none | Optional root class override | The value is formatted to 2 decimal places. #### Basic usage ```tsx <HeaderEfficiencyBox valueWthS={26.29} /> ``` --- ### `DashboardDateRangePicker` <ComponentDescription name="DashboardDateRangePicker" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `value` | Required | `DashboardDateRange` | none | Current range as `{ start, end }` epoch-millisecond timestamps | | `onChange` | Required | `function` | none | Fires with the next `{ start, end }` window when the user applies a range | | `dateFormat` | Optional | `string` | `'dd/MM/yyyy'` | Display format — defaults to `dd/MM/yyyy` | | `disabled` | Optional | `boolean` | `false` | Disable the trigger | | `className` | Optional | `string` | none | Optional root class override | #### `DashboardDateRange` type ```tsx type DashboardDateRange = { start: number // epoch ms end: number // epoch ms } ``` #### Basic usage Designed to slot directly into `useDashboardDateRange` from `@tetherto/mdk-react-adapter`: ```tsx const { start, end, setRange } = useDashboardDateRange() return ( <DashboardDateRangePicker value={{ start, end }} onChange={({ start, end }) => setRange(start, end)} /> ) } ``` #### Styling - `.mdk-dashboard-date-range-picker__trigger`: Trigger button - `.mdk-dashboard-date-range-picker__modal`: Calendar modal --- ### `ExportButton` <ComponentDescription name="ExportButton" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `onExport` | Required | `function` | none | Fires with `'csv'` or `'json'` when the user picks a format | | `formats` | Optional | `readonly ExportFormat[]` | `['csv', 'json']` | Formats to offer in the dropdown — defaults to `['csv', 'json']` | | `label` | Optional | `string` | `'Profile menu'` | Accessible label for the trigger button — defaults to `'Profile menu'` | | `disabled` | Optional | `boolean` | `false` | Disable the trigger | | `className` | Optional | `string` | none | Optional root class override | #### `ExportFormat` type ```tsx type ExportFormat = 'csv' | 'json' ``` #### Basic usage ```tsx <ExportButton onExport={(format) => { if (format === 'csv') downloadCsv(data) else downloadJson(data) }} /> ``` #### Styling - `.mdk-export-button`: Trigger button wrapper - `.mdk-export-button__label`: Label text span - `.mdk-export-button__chevron`: Dropdown chevron icon - `.mdk-export-button__menu`: Dropdown menu container --- ### `ProfileMenu` <ComponentDescription name="ProfileMenu" /> #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `items` | Required | `ProfileMenuItem[]` | none | Items rendered in the dropdown, top-to-bottom. Defaults to a single "Sign out" item. | | `user` | Optional | `ReactNode` | none | Optional user label rendered at the top of the dropdown (e.g. an email) | | `icon` | Optional | `ReactNode` | none | Override the default miner icon | | `label` | Optional | `string` | `'Profile menu'` | Accessible label for the trigger button — defaults to `'Profile menu'` | | `className` | Optional | `string` | none | Optional root class override | #### `ProfileMenuItem` type ```tsx type ProfileMenuItem = { label: string onSelect: () => void danger?: boolean // render as a destructive action (red) icon?: ReactNode // optional leading icon description?: ReactNode // optional secondary line (e.g. "Current: Europe/Podgorica") disabled?: boolean } ``` #### Basic usage ```tsx <ProfileMenu user="admin@example.com" items={[ { label: 'Timezone', description: 'Current: Europe/Podgorica', onSelect: () => openTimezoneDialog(), }, { label: 'Sign out', danger: true, onSelect: () => auth.signOut(), }, ]} /> ``` #### Styling - `.mdk-profile-menu__trigger`: Trigger button - `.mdk-profile-menu__user`: User label at top of dropdown - `.mdk-profile-menu__item`: Menu item row - `.mdk-profile-menu__item--two-line`: Modifier when `description` is present - `.mdk-profile-menu__item--danger`: Modifier for destructive items - `.mdk-profile-menu__item-icon`: Leading icon slot - `.mdk-profile-menu__item-body`: Label + description wrapper - `.mdk-profile-menu__item-label`: Primary label text - `.mdk-profile-menu__item-description`: Secondary description text # Import/export settings (/reference/ui/react/foundation/settings/import-export) <ComponentDescription name="ImportExportSettings" /> It manages: 1. **Export** (`onExport`): callback to generate and download settings JSON. 2. **Import** (`onImport`): callback when end user confirms import. 3. **File parsing** (`onParseFile`): validate and parse uploaded files. 4. **State indicators** (`isExporting`, `isImporting`): show loading feedback. 5. **Styling** (`className`): optional CSS class. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Import ```tsx ``` ## Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `onExport` | Required | `function` | none | Callback to trigger settings export | | `onImport` | Required | `function` | none | Callback when import is confirmed | | `onParseFile` | Optional | `function` | none | Parse and validate uploaded file | | `isExporting` | Optional | `boolean` | `false` | Export in progress | | `isImporting` | Optional | `boolean` | `false` | Import in progress | | `className` | Optional | `string` | none | Additional CSS class | ## Data structure The [`SettingsExportData`](/reference/app-toolkit/ui-devkit/types#settingsexportdata) type defines the structure for exported settings: ```tsx type SettingsExportData = { headerControls?: HeaderPreferences featureFlags?: Record<string, boolean> timestamp?: string } ``` ## Callbacks ### `onExport` Called when end user clicks **Export JSON**. Generate settings and trigger download: ```tsx const handleExport = async () => { const data = await api.getSettingsExport() downloadJson(data, 'settings-backup.json') } ``` ### `onImport` Called after end user confirms import. Receives parsed `SettingsExportData`: ```tsx const handleImport = async (data: SettingsExportData) => { await api.importSettings(data) } ``` ### `onParseFile` Validates and parses the uploaded file. Must return a `Promise<SettingsExportData>`: ```tsx const parseFile = async (file: File): Promise<SettingsExportData> => { const text = await file.text() return JSON.parse(text) } ``` ## Basic usage ```tsx function ImportExportSection() { const [isExporting, setIsExporting] = useState(false) const [isImporting, setIsImporting] = useState(false) const handleExport = async () => { setIsExporting(true) const data = await api.getSettingsExport() downloadJson(data, 'settings-backup.json') setIsExporting(false) } const handleImport = async (data: SettingsExportData) => { setIsImporting(true) await api.importSettings(data) setIsImporting(false) } const parseFile = async (file: File): Promise<SettingsExportData> => { const text = await file.text() return JSON.parse(text) } return ( <ImportExportSettings onExport={handleExport} onImport={handleImport} onParseFile={parseFile} isExporting={isExporting} isImporting={isImporting} /> ) } ``` ## Features ### Export Clicking **Export JSON** triggers the `onExport` callback. The developer is responsible for: - Fetching current settings - Converting to JSON - Triggering file download ### Import flow 1. End user clicks **Import JSON**. 2. Modal opens with file upload area. 3. End user selects a `.json` or `.csv` file. 4. `onParseFile` validates and parses the file. 5. Confirmation modal shows what will be imported. 6. End user confirms and `onImport` is called with parsed data. ### Confirmation modal Before importing, end users see a confirmation dialog listing: - Header Controls (if present) - Feature Flags (if present) - Export timestamp (if available) ## Accepted file formats The file input accepts: - `.json`: JSON format - `.csv`: CSV format (requires custom `onParseFile` handling) ## Warning message The component displays a warning: <Callout type="warning"> Importing settings will overwrite your current configuration. Make sure to export your current settings before importing. </Callout> ## Styling The component uses the `.mdk-settings-import-export` CSS class. Key selectors: - `.mdk-settings-import-export__description`: explanatory text - `.mdk-settings-import-export__actions`: button container - `.mdk-settings-import-export__warning`: warning message - `.mdk-settings-import-export__upload-area`: file drop zone in modal # User management modals (/reference/ui/react/foundation/settings/user-management) These modal components handle user creation, editing, and confirmation dialogs. While they are designed to be used within [`RBACControlSettings`](/reference/ui/react/foundation/settings/access-control) the three modal components can stand alone: 1. **[`AddUserModal`](#addusermodal)**: create new users with form validation. 2. **[`ManageUserModal`](#manageusermodal)**: edit users and view effective permissions. 3. **[`ChangeConfirmationModal`](#changeconfirmationmodal)**: confirm destructive or important actions. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## `AddUserModal` <ComponentDescription name="AddUserModal" /> ## Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `open` | Required | `boolean` | none | Whether the modal is visible | | `roles` | Required | `array` | none | Available roles for selection | | `onSubmit` | Required | `function` | none | Called with form data on submit | | `onClose` | Required | `function` | none | Called when modal should close | | `isSubmitting` | Optional | `boolean` | `false` | Shows loading state on submit button | ### `RoleOption` structure Full type: [`RoleOption` in Types reference](/reference/app-toolkit/ui-devkit/types#roleoption). | Property | Type | Description | |----------|------|-------------| | `value` | `string` | Role identifier | | `label` | `string` | Display name | ### Callbacks The `onSubmit` callback receives the validated form data: ```tsx const handleSubmit = async (data) => { // data: { name: string, email: string, role: string } await api.createUser(data) // persist to backend refetchUsers() // refresh list } ``` The modal resets its form after successful submission. #### Example ```tsx function UserActions() { const [isOpen, setIsOpen] = useState(false) const handleSubmit = async (data) => { await api.createUser(data) setIsOpen(false) } return ( <> <Button onClick={() => setIsOpen(true)}>Add User</Button> <AddUserModal open={isOpen} onClose={() => setIsOpen(false)} roles={[ { value: 'admin', label: 'Admin' }, { value: 'operator', label: 'Operator' }, ]} onSubmit={handleSubmit} /> </> ) } ``` ### Form fields - **Name**: required, trimmed - **Email**: required, must be valid email - **Role**: required, select from available roles Validation uses Zod schema with `react-hook-form`. The modal displays **Add User** and **Cancel** buttons. ## `ManageUserModal` <ComponentDescription name="ManageUserModal" /> ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `open` | Required | `boolean` | none | Whether the modal is visible | | `user` | Required | [`SettingsUser`](/reference/app-toolkit/ui-devkit/types#settingsuser) | none | User being edited | | `roles` | Required | `array` | none | Available roles | | `rolePermissions` | Required | `object` | none | Permissions by role | | `permissionLabels` | Required | `object` | none | Permission display names | | `onSubmit` | Required | `function` | none | Called with updated data on submit | | `onClose` | Required | `function` | none | Called when modal should close | | `isSubmitting` | Optional | `boolean` | `false` | Shows loading state on submit button | ### Data structures The `rolePermissions` object maps role IDs to their permissions: ```tsx const rolePermissions = { admin: { users: 'rw', settings: 'rw', reports: 'r' }, operator: { users: 'r', settings: 'none', reports: 'r' } } ``` The `permissionLabels` object provides display names: ```tsx const permissionLabels = { users: 'User Management', settings: 'System Settings', reports: 'Reports' } ``` ### Callbacks The `onSubmit` callback receives the updated user data: ```tsx const handleSubmit = async (data) => { // data: { id: string, name: string, email: string, role: string } await api.updateUser(data) // persist to backend refetchUsers() // refresh list } ``` ### Example ```tsx function UserRow({ user }) { const [isEditing, setIsEditing] = useState(false) const handleSubmit = async (data) => { await api.updateUser(data) setIsEditing(false) } return ( <> <Button onClick={() => setIsEditing(true)}>Manage</Button> <ManageUserModal open={isEditing} onClose={() => setIsEditing(false)} user={user} roles={roles} rolePermissions={rolePermissions} permissionLabels={permissionLabels} onSubmit={handleSubmit} /> </> ) } ``` ### Sections The modal is divided into three sections: 1. **User Information**: edit name and email. 2. **Assigned Role**: select role from dropdown. 3. **Effective Permissions**: read-only table showing what the selected role can do. ### Permission icons Permissions display icons based on level: - `rw`: Read/Write (full access) - `r`: Read (view only) - `none`: No access The modal displays **Save Changes** and **Cancel** buttons. ## `ChangeConfirmationModal` <ComponentDescription name="ChangeConfirmationModal" /> ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `open` | Required | `boolean` | none | Whether the modal is visible | | `title` | Required | `string` | none | Modal title | | `children` | Required | `ReactNode` | none | Modal body content | | `onConfirm` | Required | `function` | none | Called when end user confirms | | `onClose` | Required | `function` | none | Called when end user cancels or closes | | `confirmText` | Optional | `string` | `'Confirm'` | Text for confirm button | | `destructive` | Optional | `boolean` | `false` | Use danger styling (red button) | ### Example ```tsx function DeleteButton({ user }) { const [showConfirm, setShowConfirm] = useState(false) const handleDelete = async () => { await api.deleteUser(user.id) setShowConfirm(false) } return ( <> <Button onClick={() => setShowConfirm(true)}>Delete</Button> <ChangeConfirmationModal open={showConfirm} title={`Delete ${user.email}?`} onClose={() => setShowConfirm(false)} onConfirm={handleDelete} confirmText="Delete" destructive > Are you sure you want to delete this user? This action is permanent and cannot be undone. </ChangeConfirmationModal> </> ) } ``` ### Variants #### Standard confirmation ```tsx <ChangeConfirmationModal title="Save Changes?" confirmText="Save" destructive={false} > Your changes will be applied immediately. </ChangeConfirmationModal> ``` #### Destructive confirmation ```tsx <ChangeConfirmationModal title="Delete Item?" confirmText="Delete" destructive > This action cannot be undone. </ChangeConfirmationModal> ``` The modal displays a **Cancel** button alongside the configurable confirm button. ## Dependencies All user management modals depend on `@tetherto/mdk-react-devkit/core` components: - `Dialog`, `DialogContent`, `DialogFooter` - `Button` - `Form`, `FormInput`, `FormSelect` They also use: - `react-hook-form` for form state - `zod` for validation - `@hookform/resolvers` for Zod integration # 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 | |----------|-------------| | [Cards](/reference/ui/types/cards) | Card component type definitions | | [General](/reference/ui/types/devkit-general) | General component and hook 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 Types (/reference/ui/types/api) Type definitions for API requests and responses. ## Package `@tetherto/mdk-ui-foundation` ## Types ### `ActionsParams` Free-form query parameters for `GET /auth/actions`. Array values are serialized comma-separated (e.g. `?status=VOTING,APPROVED`). ```typescript type ActionsParams = Record<string, unknown> ``` ### `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<string | number> } ``` ### `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<string, unknown> thresholds?: Record<string, ContainerThresholdLevels> } ``` ### `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<string, string> status_group_aggr?: Record<string, string> } ``` ### `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 `miningos-gateway`. {todo: update miningos-gateway} ```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 `miningos-gateway`. `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<string, unknown> [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<string, unknown> action?: string params?: VotingActionPara… ``` # Card Types (/reference/ui/types/cards) Type definitions for card components. ## Package `@tetherto/mdk-react-devkit` ## Types ### `MiningPoolRow` Display contract for one row of the `<MiningPoolsPanel />` table. Adapter hooks (e.g. `usePoolRows`) shape their output to fit this type; consumers can also build rows by hand for fixtures or demos. ```typescript type MiningPoolRow = { /** Stable React key. */ id: string /** Display name (e.g. `minerpool-f2pool-shelf-0`). */ name: string /** 24h revenue in BTC; rendered as `0.00 BTC` when undefined. */ revenue24hBtc?: number /** Hashrate in PH/s — used for display (TH/… ``` # Devkit General Types (/reference/ui/types/devkit-general) General type definitions from the react-devkit package. ## Package `@tetherto/mdk-react-devkit` ## Types ### `ActionButtonConfirmation` ```typescript type ActionButtonConfirmation = { title: string cancelLabel?: string confirmLabel?: string icon?: React.ReactNode onCancel?: VoidFunction onConfirm?: VoidFunction description?: React.ReactNode } ``` ### `ActionButtonProps` ```typescript type ActionButtonProps = { label?: string loading?: boolean disabled?: boolean className?: string variant?: TActionButtonVariant confirmation: ActionButtonConfirmation /** Confirmation mode: popover (inline) or dialog (modal). Default: popover */ mode?: 'popover'… ``` ### `ActionNameKey` ```typescript type ActionNameKey = keyof typeof ACTION_NAMES_MAP ``` ### `ActionNameValue` ```typescript type ActionNameValue = (typeof ACTION_NAMES_MAP)[ActionNameKey] ``` ### `ActionStatusTypeKey` ```typescript type ActionStatusTypeKey = keyof typeof ACTION_STATUS_TYPES ``` ### `ActionStatusTypeValue` ```typescript type ActionStatusTypeValue = (typeof ACTION_STATUS_TYPES)[ActionStatusTypeKey] ``` ### `ActionTypeKey` ```typescript type ActionTypeKey = keyof typeof ACTION_TYPES ``` ### `ActionTypeValue` ```typescript type ActionTypeValue = (typeof ACTION_TYPES)[ActionTypeKey] ``` ### `ActiveIncidentsCardPartialProps` ```typescript type ActiveIncidentsCardPartialProps = Partial<{ label: string isLoading: boolean className: string skeletonRows: number emptyMessage: string items: TIncidentRowProps[] onItemClick: (id: string) => void }> ``` ### `ActiveTimeframe` Which single control “owns” the range: others show placeholders (mutually exclusive UI). ```typescript type ActiveTimeframe = 'year' | 'month' | 'week' ``` ### `ActualEbitdaCardProps` ```typescript type ActualEbitdaCardProps = { value: number } ``` ### `AddSparePartFormValues` Values collected by the register-part form. Select fields are nullable until chosen. ```typescript type AddSparePartFormValues = { partTypeId: string; model: string | null; parentDeviceModel: string | null; serialNum: string; macAddress: string; status: string | null; location: string | null; comment: string; tags: string[]; } ``` ### `AddSparePartModalProps` Props for `AddSparePartModal`; option lists and handlers are supplied by the caller. ```typescript type AddSparePartModalProps = { isOpen: boolean; onClose: VoidFunction; partTypes: SparePartSubTypesModalPartType[]; defaultPartTypeId?: string; modelOptions: FormSelectOption[]; isModelOptionsLoading?: boolean; minerModelOptions: FormSelectOption[]; statusOptions: For… ``` ### `AddUserModalProps` ```typescript type AddUserModalProps = { open: boolean onClose: VoidFunction roles: RoleOption[] onSubmit: (data: { name: string; email: string; role: string }) => Promise<void> isSubmitting?: boolean } ``` ### `AlarmItemData` ```typescript type AlarmItemData = { title: string subtitle: string body: string uuid?: string status: string [key: string]: unknown } ``` ### `AlarmsBellButtonCounts` ```typescript type AlarmsBellButtonCounts = { critical?: number high?: number medium?: number } ``` ### `AlarmsBellButtonProps` ```typescript type AlarmsBellButtonProps = { /** Severity-bucketed alarm counts rendered in the stacked badge. */ counts?: AlarmsBellButtonCounts /** Click handler — typically opens an alerts panel or routes to /alerts. */ onClick?: (event: MouseEvent<HTMLButtonElement>) => void /*… ``` ### `Alert` ```typescript type Alert = { id?: string severity: string createdAt: number | string name: string description: string message?: string uuid?: string code?: string | number [key: string]: unknown } ``` ### `AlertActions` ```typescript type AlertActions = { onAlertClick?: (id: string, uuid: string) => void id?: string uuid: string } ``` ### `AlertConfirmationModalProps` ```typescript type AlertConfirmationModalProps = { isOpen: boolean onOk: VoidFunction } ``` ### `AlertLocalFilters` ```typescript type AlertLocalFilters = { severity?: string[] | string status?: string[] type?: string[] id?: string[] thing?: { id?: string } [key: string]: unknown } ``` ### `AlertSeverity` ```typescript type AlertSeverity = (typeof ALERT_SEVERITY_TYPES)[keyof typeof ALERT_SEVERITY_TYPES] ``` ### `AlertsProps` ```typescript type AlertsProps = { /** * Devices payload powering the "Current Alerts" table. * Mirrors the API response shape of `useGetListThingsQuery({ ... alerts query })`. */ devices?: Device[][] /** * Loading flag for the "Current Alerts" table. */ isCurrentAlertsLo… ``` ### `AlertsTableTitleProps` ```typescript type AlertsTableTitleProps = { title: ReactNode subtitle?: ReactNode className?: string } ``` ### `AlertTableRecord` ```typescript type AlertTableRecord = { shortCode: string device: string alertName: string description?: string message?: string severity: string createdAt: number | string id?: string uuid: string actions?: AlertActions /** * Hidden tokens (uuid, ip-/mac-/sn-/firmware- tags,… ``` ### `ApiErrorKey` ```typescript type ApiErrorKey = keyof typeof API_ERRORS ``` ### `ApiErrorValue` ```typescript type ApiErrorValue = (typeof API_ERRORS)[ApiErrorKey] ``` ### `ApiResponse` ```typescript type ApiResponse = { data: T message?: string status: number } ``` ### `AppHeaderProps` ```typescript type AppHeaderProps = { /** Left-most slot — typically the app's brand lockup / logo. */ logo?: ReactNode /** Left-edge content — e.g. a sidebar collapse toggle button. */ start?: ReactNode /** Middle slot — typically the dashboard's stats strip. */ children?:… ``` ### `AreaChartProps` ```typescript type AreaChartProps = { /** Chart data - required, provided by parent */ data: ChartJS<'line'>['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 = { isOpen: boolean onClose: () => void onSubmit: (values: { pool: PoolSummary }) => Promise<void> miners: Device[] poolConfig: PoolConfigData[] } ``` ### `AttentionLevelColorKey` ```typescript type AttentionLevelColorKey = keyof typeof ATTENTION_LEVEL_COLORS ``` ### `AuthCapKey` ```typescript type AuthCapKey = keyof typeof AUTH_CAPS ``` ### `AuthCapValue` ```typescript type AuthCapValue = (typeof AUTH_CAPS)[AuthCapKey] ``` ### `AverageDowntimeChartData` ```typescript type AverageDowntimeChartData = { labels: string[] curtailment?: number[] operationalIssues?: number[] } ``` ### `AverageDowntimeChartProps` ```typescript type AverageDowntimeChartProps = Partial<{ title: string unit: string height: number barWidth: number className: string isLoading: boolean emptyMessage: string data: AverageDowntimeChartData /** Formats Y-axis ticks, tooltips, and bar data labels (values are 0–1 rates). *… ``` ### `AvgAllInCostChartProps` ```typescript type AvgAllInCostChartProps = { data?: ReadonlyArray<AvgAllInCostDataPoint> dateRange: FinancialDateRange | null isLoading?: boolean } ``` ### `AvgAllInCostDataPoint` ```typescript type AvgAllInCostDataPoint = { ts: number revenueUSDPerMWh: number costUSDPerMWh: number } ``` ### `AvgHistoryRangeKey` ```typescript type AvgHistoryRangeKey = keyof typeof AVG_HISTORY_RANGES ``` ### `AvgHistoryRangeValue` ```typescript type AvgHistoryRangeValue = (typeof AVG_HISTORY_RANGES)[AvgHistoryRangeKey] ``` ### `AxisTitleText` ```typescript type AxisTitleText = { x: string y: string } ``` ### `BadgeColors` Display colors for a status/location badge. ```typescript type BadgeColors = { backgroundColor: string borderColor: string } ``` ### `BadgeProps` ```typescript type BadgeProps = { /** * Badge content (wraps children with badge) */ children?: ReactNode /** * Number to display in badge * If > overflowCount, will show "overflowCount+" */ count?: number /** * Maximum count to display * @default 99 */ overflowCount?: n… ``` ### `BadgeStatus` Badge status options ```typescript type BadgeStatus = 'success' | 'processing' | 'error' | 'warning' | 'default' ``` ### `BarChartConstant` ```typescript type BarChartConstant = { label: string value: number color?: string borderDash?: number[] yAxisID?: string } ``` ### `BarChartInput` ```typescript type BarChartInput = { labels?: string[] series: BarChartSeries[] lines?: BarChartLine[] constants?: BarChartConstant[] } ``` ### `BarChartItemBorderColorKey` ```typescript type BarChartItemBorderColorKey = keyof typeof BAR_CHART_ITEM_BORDER_COLORS ``` ### `BarChartLine` ```typescript type BarChartLine = { label: string values: number[] | Record<string, number> color?: string yAxisID?: string tension?: number pointRadius?: number pointHoverRadius?: number } ``` ### `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 */ isStacked?: b… ``` ### `BarChartSeries` ```typescript type BarChartSeries = { label: string values: number[] | Record<string, number> color?: string /** Assign a stack group id to stack multiple series together */ stack?: string /** Gradient opacity stops (default { top: 0.3, bottom: 0.1 }) */ gradient?: { top: nu… ``` ### `BatchActionTypeKey` ```typescript type BatchActionTypeKey = keyof typeof BATCH_ACTION_TYPES ``` ### `BatchActionTypeValue` ```typescript type BatchActionTypeValue = (typeof BATCH_ACTION_TYPES)[BatchActionTypeKey] ``` ### `BatchMoveSparePart` A spare part shown in the batch-move table. ```typescript type BatchMoveSparePart = { id: string; code: string; location: string; status: string; } ``` ### `BatchMoveSparePartsModalProps` Props for `BatchMoveSparePartsModal`; unselected location/status arrive as `null` on submit. ```typescript type BatchMoveSparePartsModalProps = { isOpen: boolean; onClose: VoidFunction; spareParts: BatchMoveSparePart[]; locationOptions: FormSelectOption[]; statusOptions: FormSelectOption[]; onSubmit: (values: { location: string | null; status: string | null; observation: string |… ``` ### `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 } ``` ### `BitMainImmersionSummaryBoxContainerSettings` ```typescript type BitMainImmersionSummaryBoxContainerSettings = { thresholds?: Record<string, unknown> } ``` ### `BitMainImmersionSummaryBoxProps` ```typescript type BitMainImmersionSummaryBoxProps = { data?: Device containerSettings?: BitMainImmersionSummaryBoxContainerSettings | null } ``` ### `BorderRadius` Border radius variants Used by Checkbox, Switch, Radio ```typescript type BorderRadius = 'none' | 'small' | 'medium' | 'large' | 'full' ``` ### `BreadcrumbItem` ```typescript type BreadcrumbItem = { label: string href?: string onClick?: VoidFunction } ``` ### `BreadcrumbsProps` ```typescript type BreadcrumbsProps = { items: BreadcrumbItem[] showBack?: boolean backLabel?: string className?: string itemClassName?: string backClassName?: string onBackClick?: VoidFunction separator?: ReactNode } ``` ### `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… ``` ### `BtcPriceTimeSeriesEntry` ```typescript type BtcPriceTimeSeriesEntry = { ts: number priceUSD: number } ``` ### `BuildAvgAllInCostInputArgs` ```typescript type BuildAvgAllInCostInputArgs = { data?: ReadonlyArray<AvgAllInCostDataPoint> dateRange: FinancialDateRange | null } ``` ### `BuildBarChartOptionsInput` ```typescript type BuildBarChartOptionsInput = { isHorizontal?: boolean isStacked?: boolean yTicksFormatter?: (value: number) => string yRightTicksFormatter?: ((value: number) => string) | null displayColors?: boolean legendPosition?: 'top' | 'bottom' | 'left' | 'right' legendAlign?: '… ``` ### `BuildProductionCostInputArgs` ```typescript type BuildProductionCostInputArgs = { costLog: ReadonlyArray<CostTimeSeriesEntry> btcPriceLog: ReadonlyArray<BtcPriceTimeSeriesEntry> dateRange: FinancialDateRange | null } ``` ### `BulkAddSparePartsModalProps` Props for `BulkAddSparePartsModal`; `onSubmit` receives the parsed CSV records. ```typescript type BulkAddSparePartsModalProps = { isOpen: boolean; onClose: VoidFunction; onSubmit: (records: CSVRecord[]) => Promise<{ error?: string } | void>; isLoading?: boolean; } ``` ### `ButtonIconPosition` Button icon position ```typescript type ButtonIconPosition = 'left' | 'right' ``` ### `ButtonProps` Props for `Button`. Extends all native `<button>` attributes. ```typescript type ButtonProps = Partial< { /** Show a spinner instead of the content and disable the button. */ loading: boolean /** Make the button stretch to fill its container. */ fullWidth: boolean /** Icon node rendered alongside `children`. */ icon: ReactNode /** V… ``` ### `ButtonSize` Button-specific size including icon-only variant ```typescript type ButtonSize = ComponentSize | 'icon' ``` ### `ButtonVariant` Component-specific prop types ```typescript type ButtonVariant = | 'primary' | 'secondary' | 'danger' | 'tertiary' | 'link' | 'nav-link' | 'icon' | 'outline' | 'ghost' ``` ### `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… ``` ### `CabinetReadingRow` One sensor / powermeter reading row rendered in the cabinet detail. ```typescript type CabinetReadingRow = { /** Stable key — the source device id. */ id: string /** Display name (sensor / powermeter name). */ label: string /** Formatted reading, or `-` when unavailable. */ value: string /** Unit shown next to the value. */ unit: string /** Sev… ``` ### `CardBodyProps` Props for `CardBody` slot. Forwards all native `<div>` attributes. ```typescript type CardBodyProps = HTMLAttributes<HTMLDivElement> ``` ### `CardComponent` ```typescript type CardComponent = ForwardRefExoticComponent<CardProps & RefAttributes<HTMLDivElement>> & { Header: typeof CardHeader Body: typeof CardBody Footer: typeof CardFooter } ``` ### `CardFooterProps` Props for `CardFooter` slot. Forwards all native `<div>` attributes. ```typescript type CardFooterProps = HTMLAttributes<HTMLDivElement> ``` ### `CardHeaderProps` Props for `CardHeader` slot. Forwards all native `<div>` attributes. ```typescript type CardHeaderProps = HTMLAttributes<HTMLDivElement> ``` ### `CardProps` Props for `Card`. Forwards all native `<div>` attributes. ```typescript type CardProps = HTMLAttributes<HTMLDivElement> ``` ### `CascaderOption` Cascader option type - represents a hierarchical option with optional children ```typescript type CascaderOption = { /** Unique value for the option */ value: string | number | boolean /** Display label for the option */ label: string /** Child options (creates a nested category) */ children?: CascaderOption[] /** Whether the option is disabled */ disa… ``` ### `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)… ``` ### `CascaderValue` Cascader value type - array representing the path from parent to child Example: ['electronics', 'phones'] means category 'electronics', option 'phones' ```typescript type CascaderValue = (string | number | boolean)[] ``` ### `ChangeConfirmationModalProps` ```typescript type ChangeConfirmationModalProps = { open: boolean title: string onConfirm: VoidFunction onClose: VoidFunction children: ReactNode confirmText?: string destructive?: boolean } ``` ### `ChartColorKey` ```typescript type ChartColorKey = keyof typeof CHART_COLORS ``` ### `ChartContainerProps` ```typescript type ChartContainerProps = { 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 - * omit it and the title renders exactly as before. */ titleExtra?: Reac… ``` ### `ChartDataByDevice` ```typescript type ChartDataByDevice = { [deviceName: string]: ChartDataset } ``` ### `ChartDataPoint` ```typescript type ChartDataPoint = { x: number | string y: number } ``` ### `ChartEntry` ```typescript type ChartEntry = { ts: number | string container_specific_stats_group_aggr: Record<string, EntryData | null | undefined> } ``` ### `ChartExpandActionProps` ```typescript type ChartExpandActionProps = { /** Whether the parent chart is currently expanded to full width. */ isExpanded: boolean /** Toggles the expanded state. */ onToggle?: VoidFunction } ``` ### `ChartLabelKey` ```typescript type ChartLabelKey = keyof typeof CHART_LABELS ``` ### `ChartLabelValue` ```typescript type ChartLabelValue = (typeof CHART_LABELS)[ChartLabelKey] ``` ### `ChartLegendOpacityKey` ```typescript type ChartLegendOpacityKey = keyof typeof CHART_LEGEND_OPACITY ``` ### `ChartLegendOpacityValue` ```typescript type ChartLegendOpacityValue = (typeof CHART_LEGEND_OPACITY)[ChartLegendOpacityKey] ``` ### `ChartLegendPosition` ```typescript type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'center' | 'chartArea' ``` ### `ChartPerformanceKey` ```typescript type ChartPerformanceKey = keyof typeof CHART_PERFORMANCE ``` ### `ChartRange` ```typescript type ChartRange = { min: Date | number max: Date | number } ``` ### `ChartStatsFooterItem` ```typescript type ChartStatsFooterItem = { label: string value: string | number } ``` ### `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) */ statsPerColumn: number /** Secondary… ``` ### `ChartTitleKey` ```typescript type ChartTitleKey = keyof typeof CHART_TITLES ``` ### `ChartTitleValue` ```typescript type ChartTitleValue = (typeof CHART_TITLES)[ChartTitleKey] ``` ### `ChartTooltipConfig` ```typescript type ChartTooltipConfig = { /** Color for label text. Use 'dataset' to match dataset border color. Defaults to COLOR.WHITE_ALPHA_05 */ labelColor?: string | 'dataset' /** Color for value text. Use 'dataset' to match dataset border color. Defaults to 'dataset' */ va… ``` ### `ChartTypeKey` ```typescript type ChartTypeKey = keyof typeof CHART_TYPES ``` ### `ChartTypeValue` ```typescript type ChartTypeValue = (typeof CHART_TYPES)[ChartTypeKey] ``` ### `CheckboxProps` ```typescript type CheckboxProps = { /** * Size variant of the checkbox * @default 'md' */ size?: CheckboxSize /** * Color variant when checked * @default 'primary' */ color?: ComponentColor /** * Border radius variant * @default 'none' */ radius?: BorderRadius /** * Custom… ``` ### `CheckboxSize` ```typescript type CheckboxSize = 'xs' | ComponentSize ``` ### `ChipData` ```typescript type ChipData = { index: number current: number } ``` ### `ColorKey` ```typescript type ColorKey = keyof typeof COLOR ``` ### `ColorValue` ```typescript type ColorValue = (typeof COLOR)[ColorKey] ``` ### `ColorVariant` Color variants for components Comprehensive set including all semantic colors ```typescript type ColorVariant = | 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' ``` ### `ComponentColor` Component color options (subset of ColorVariant) Used by form components like Checkbox, Switch, Radio, Typography ```typescript type ComponentColor = 'default' | 'primary' | 'success' | 'warning' | 'error' ``` ### `ComponentSize` Common shared types used across components ```typescript type ComponentSize = 'sm' | 'md' | 'lg' ``` ### `ConfirmDeleteSparePartModalProps` Props for `ConfirmDeleteSparePartModal`. ```typescript type ConfirmDeleteSparePartModalProps = { isOpen?: boolean; onClose?: VoidFunction; onConfirm?: (sparePart: ConfirmDeleteSparePartModalSparePart) => Promise<void> | void; sparePart?: ConfirmDeleteSparePartModalSparePart; isLoading?: boolean; } ``` ### `ConfirmDeleteSparePartModalSparePart` The spare part targeted for deletion. ```typescript type ConfirmDeleteSparePartModalSparePart = { id: string; code: string; } ``` ### `ConsumptionNominalValueType` ```typescript type ConsumptionNominalValueType = typeof CONSUMPTION_NOMINAL_VALUE_W ``` ### `Container` ```typescript type Container = { info?: Partial<ContainerInfo> last?: Partial<ContainerLast> } & Device ``` ### `ContainerActionValue` ```typescript type ContainerActionValue = (typeof CONTAINER_ACTIONS)[number] ``` ### `ContainerActivityData` Miner-state counts fed to the embedded activity chart (online / offline / faulted / …). ```typescript type ContainerActivityData = { total?: number } & Record<string, number | undefined> ``` ### `ContainerActivityError` Error envelope surfaced by the activity chart when its data fails to load. ```typescript type ContainerActivityError = { data?: { message?: string }; [key: string]: unknown } | null ``` ### `ContainerChartCombinationOption` ```typescript type ContainerChartCombinationOption = { value: string label: string } ``` ### `ContainerChartsDatasetBorderColorResolver` ```typescript type ContainerChartsDatasetBorderColorResolver = (args: { chartTitle: string datasetLabel: string datasetIndex: number }) => string | undefined ``` ### `ContainerChartsProps` ```typescript type ContainerChartsProps = { /** When false, shows an empty state (feature gate). @default true */ featureEnabled?: boolean /** Message when `featureEnabled` is false */ disabledMessage?: string /** Options for the combination selector */ combinations: ContainerChar… ``` ### `ContainerControlsBoxProps` ```typescript type ContainerControlsBoxProps = { data?: Device isBatch?: boolean isCompact?: boolean // --- data from outside (no API calls inside) --- selectedDevices?: Device[] pendingSubmissions?: PendingSubmission[] alarmsDataItems?: TimelineItemData[] tailLogData?: UnknownRecord[]… ``` ### `ContainerDetailPlaceholderProps` ```typescript type ContainerDetailPlaceholderProps = { /** Human label of the tab this placeholder stands in for, e.g. "PDU Layout". */ label: string } ``` ### `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… ``` ### `ContainerDetailTab` A single tab in the container detail strip. ```typescript type ContainerDetailTab = { /** Route segment / Radix value, e.g. `"home"`, `"pdu"`. */ key: string /** Human label, e.g. `"PDU Layout"`. */ label: string } ``` ### `ContainerInfo` ```typescript type ContainerInfo = { container: string type?: string rack?: string nominalMinerCapacity?: string cooling_system: Record<string, unknown> cdu: Record<string, unknown> primary_supply_temp: number second_supply_temp1: number second_supply_temp2: number supply_l… ``` ### `ContainerLast` ```typescript type ContainerLast = { snap: { stats?: Partial<ContainerStats> } alerts: unknown[] | null err: string | null } ``` ### `ContainerPduData` ```typescript type ContainerPduData = { power_w: number status: number } ``` ### `ContainerPosInfo` ```typescript type ContainerPosInfo = { containerInfo: Partial<ContainerInfo> pdu: string | number socket: string | number pos: string [key: string]: unknown } ``` ### `ContainerSnap` ```typescript type ContainerSnap = { stats?: Partial<ContainerStats> config?: Record<string, unknown> } ``` ### `ContainerSpecific` ```typescript type ContainerSpecific = { pdu_data: Partial<ContainerPduData>[] [key: string]: unknown } ``` ### `ContainerStats` ```typescript type ContainerStats = { status: string ambient_temp_c: number humidity_percent: number power_w: number container_specific: Partial<ContainerSpecific> distribution_box1_power_w: number distribution_box2_power_w: number stats: Record<string, unknown> temperature_… ``` ### `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… ``` ### `ContainerWidgetItem` One container's card data plus the stable id used for keys and click routing. ```typescript type ContainerWidgetItem = ContainerWidgetCardProps & { id: string } ``` ### `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. */ isLoading?: boolean /** Error message… ``` ### `CostChartsProps` ```typescript type CostChartsProps = { costLog: ReadonlyArray<CostTimeSeriesEntry> btcPriceLog: ReadonlyArray<BtcPriceTimeSeriesEntry> totals: CostSummaryMonetaryTotals | null dateRange: FinancialDateRange | null avgAllInCostData?: ReadonlyArray<AvgAllInCostDataPoint> isLoadi… ``` ### `CostChromeProps` ```typescript type CostChromeProps = { /** Period selector element. Pass `<TimeframeControls>` for the OSS-style year/month picker. */ controls: ReactElement /** * Optional "Set Monthly Cost" header action slot. * * A `ReactElement` slot (rather than an href string) so consum… ``` ### `CostContentProps` ```typescript type CostContentProps = CostViewModelProps & CostQueryStateProps & { dateRange: FinancialDateRange | null /** Optional revenue/cost time-series for the Avg All-in Cost panel. */ avgAllInCostData?: ReadonlyArray<AvgAllInCostDataPoint> } ``` ### `CostMetricsProps` ```typescript type CostMetricsProps = { metrics: CostSummaryDisplayMetrics } ``` ### `CostProps` ```typescript type CostProps = CostContentProps & CostChromeProps ``` ### `CostQueryStateProps` ```typescript type CostQueryStateProps = { isLoading?: boolean error?: unknown } ``` ### `CostSummaryDisplayMetrics` ```typescript type CostSummaryDisplayMetrics = { allInCost: CostSummaryMetric energyCost: CostSummaryMetric operationsCost: CostSummaryMetric } ``` ### `CostSummaryLogEntry` ```typescript type CostSummaryLogEntry = { ts: number consumptionMWh: number energyCostsUSD: number operationalCostsUSD: number totalCostsUSD: number allInCostPerMWh: number | null energyCostPerMWh: number | null btcPrice: number } ``` ### `CostSummaryMetric` ```typescript type CostSummaryMetric = { label: string unit: string value: number | null isHighlighted?: boolean } ``` ### `CostSummaryMonetaryTotals` ```typescript type CostSummaryMonetaryTotals = { totalEnergyCostsUSD: number totalOperationalCostsUSD: number totalCostsUSD: number totalConsumptionMWh: number } ``` ### `CostSummaryQueryParams` ```typescript type CostSummaryQueryParams = { start: number end: number period: FinancePeriod } ``` ### `CostSummaryQueryResult` ```typescript type CostSummaryQueryResult = { data?: CostSummaryResponse isLoading?: boolean error?: unknown } ``` ### `CostSummaryResponse` ```typescript type CostSummaryResponse = FinanceResponse<CostSummaryLogEntry, CostSummaryTotals> ``` ### `CostSummaryTotals` ```typescript type CostSummaryTotals = { totalEnergyCostsUSD: number totalOperationalCostsUSD: number totalCostsUSD: number totalConsumptionMWh: number avgAllInCostPerMWh: number | null avgEnergyCostPerMWh: number | null avgBtcPrice: number | null } ``` ### `CostSummaryViewModel` ```typescript type CostSummaryViewModel = { metrics: CostSummaryDisplayMetrics | null costLog: ReadonlyArray<CostTimeSeriesEntry> btcPriceLog: ReadonlyArray<BtcPriceTimeSeriesEntry> totals: CostSummaryMonetaryTotals | null avgBtcPrice: number | null } ``` ### `CostTimeSeriesEntry` ```typescript type CostTimeSeriesEntry = { ts: number totalCostUSD: number energyCostUSD: number operationalCostUSD: number } ``` ### `CostViewModelProps` Subset of `useCostSummary` output that the Cost composite page needs. Defined as a standalone type so consumers wiring up their own data flow can pass an object of this shape without coupling to the… ```typescript type CostViewModelProps = { metrics: CostSummaryDisplayMetrics | null costLog: ReadonlyArray<CostTimeSeriesEntry> btcPriceLog: ReadonlyArray<BtcPriceTimeSeriesEntry> totals: CostSummaryMonetaryTotals | null } ``` ### `CreateIconOptions` ```typescript type CreateIconOptions = { displayName: string viewBox: string defaultWidth?: number defaultHeight?: number multiColor?: boolean path: ReactNode | ((props: { color: string }) => ReactNode) } ``` ### `CrossThingTypeKey` ```typescript type CrossThingTypeKey = keyof typeof CROSS_THING_TYPES ``` ### `CrossThingTypeValue` ```typescript type CrossThingTypeValue = (typeof CROSS_THING_TYPES)[CrossThingTypeKey] ``` ### `CSVRecord` ```typescript type CSVRecord = { partType?: string; model?: string; parentDeviceModel?: string; serialNum?: string; macAddress?: string; status?: string; location?: string; comment?: string; rackId?: string; [key: string]: unknown; } ``` ### `CurrencyKey` ```typescript type CurrencyKey = keyof typeof CURRENCY ``` ### `CurrencyUnit` ```typescript type CurrencyUnit = ValueUnit & { unit: string } ``` ### `CurrencyValue` ```typescript type CurrencyValue = (typeof CURRENCY)[CurrencyKey] ``` ### `CurrentAlertsProps` ```typescript type CurrentAlertsProps = { /** * Raw devices (with last.alerts) used to derive current alerts from. * Shape mirrors the API response from the source app. */ devices?: Device[][] isLoading?: boolean /** * Filters controlled outside (typically by URL severity param)… ``` ### `CurtailmentResult` ```typescript type CurtailmentResult = { curtailmentMWh: number curtailmentRate: number } ``` ### `DashboardDateRange` ```typescript type DashboardDateRange = { /** Window start, milliseconds since epoch. */ start: number /** Window end, milliseconds since epoch. */ end: number } ``` ### `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 f… ``` ### `DashboardProps` ```typescript type DashboardProps = { stats?: DashboardStats isStatsLoading?: boolean alerts?: Alert[] onNavigationClick: (url: string) => void onViewAllAlerts: VoidFunction } ``` ### `DashboardStats` ```typescript type DashboardStats = { items: StatItem[] } ``` ### `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`. */ label:… ``` ### `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<I, any>… ``` ### `DateFormatType` ```typescript type DateFormatType = | typeof DATE_FORMAT | typeof DATE_FORMAT_SLASHED | typeof SHORT_DATE_FORMAT ``` ### `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… ``` ### `DateRange` ```typescript type DateRange = { from: Date | undefined to?: Date | undefined } ``` ### `DateRangeKey` ```typescript type DateRangeKey = keyof typeof DATE_RANGE ``` ### `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?… ``` ### `DateRangeValue` ```typescript type DateRangeValue = (typeof DATE_RANGE)[DateRangeKey] ``` ### `DateTimeFormatType` ```typescript type DateTimeFormatType = typeof DATE_TIME_FORMAT | typeof DATE_TIME_FORMAT_WITH_SECONDS ``` ### `DetailLegendItem` ```typescript type DetailLegendItem = { /** Legend label text */ label: string /** Color for the legend icon */ color: string /** Custom icon to display (defaults to a colored square) */ icon?: ReactNode /** Current value display */ currentValue?: { value: number | string unit… ``` ### `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 } ``` ### `Device` ```typescript type Device = { id: string type: string tags?: string[] rack?: string last?: DeviceLast username?: string info?: DeviceInfo containerId?: string address?: string | null code?: string alerts?: Alert[] | null powerMeters?: Device[] tempSensors?: Device[]… ``` ### `DeviceAttributeView` A single labelled device attribute row. ```typescript type DeviceAttributeView = { label: string value: string } ``` ### `DeviceData` ```typescript type DeviceData = { id: string | undefined type: string | undefined tags?: string[] rack?: string snap: ContainerSnap alerts?: Alert[] | null username?: string info?: DeviceInfo containerId?: string address?: string | null err?: string | null [key: string]:… ``` ### `DeviceExplorerDeviceData` ```typescript type DeviceExplorerDeviceData = Device ``` ### `DeviceExplorerDeviceType` ```typescript type DeviceExplorerDeviceType = (typeof DEVICE_EXPLORER_DEVICE_TYPE)[keyof typeof DEVICE_EXPLORER_DEVICE_TYPE] ``` ### `DeviceExplorerFilterOption` ```typescript type DeviceExplorerFilterOption = { value: string label: string children?: DeviceExplorerFilterOption[] } ``` ### `DeviceExplorerProps` ```typescript type DeviceExplorerProps = { deviceType: DeviceExplorerDeviceType className?: string selectedDevices?: DataTableRowSelectionState onSelectedDevicesChange?: (selections: DataTableRowSelectionState) => void } & ForwardedToolbarProps & ForwardedTableProps ``` ### `DeviceExplorerSearchOption` ```typescript type DeviceExplorerSearchOption = { value: string label: string } ``` ### `DeviceInfo` ```typescript type DeviceInfo = { container?: string pos?: string poolConfig?: string serialNum?: string macAddress?: string | null posHistory?: Partial<PosHistoryEntry[]> [key: string]: unknown } ``` ### `DeviceLast` ```typescript type DeviceLast = { err?: string | null type?: string snap?: ContainerSnap alerts?: Alert[] | null [key: string]: unknown } ``` ### `DeviceStatus` ```typescript type DeviceStatus = (typeof DEVICE_STATUS)[keyof typeof DEVICE_STATUS] ``` ### `DialogContentProps` ```typescript type DialogContentProps = { title?: string description?: string closeOnClickOutside?: boolean closeOnEscape?: boolean } & DialogHeaderProps ``` ### `DialogHeaderProps` ```typescript type DialogHeaderProps = { bare?: boolean closable?: boolean onClose?: VoidFunction } ``` ### `DisplayMode` ```typescript type DisplayMode = typeof CURRENCY.USD_LABEL | typeof CURRENCY.BTC_LABEL ``` ### `DividerOrientation` ```typescript type DividerOrientation = 'horizontal' | 'vertical' ``` ### `DividerProps` ```typescript type DividerProps = { /** Line orientation */ orientation?: DividerOrientation /** Line style */ dashed?: boolean dotted?: boolean /** Text or node rendered in the middle of the divider */ children?: ReactNode /** Horizontal alignment of the label */ align?:… ``` ### `DividerType` ```typescript type DividerType = 'solid' | 'dashed' | 'dotted' ``` ### `DoughnutChartDataset` ```typescript type DoughnutChartDataset = { label: string value: number color?: string } ``` ### `DoughnutChartProps` ```typescript type DoughnutChartProps = { /** Array of labelled slices */ data: DoughnutChartDataset[] /** Unit suffix shown in tooltips */ unit?: string /** Chart.js options – merged with defaults */ options?: ChartJS<'doughnut'>['options'] /** Doughnut cutout percentage (defau… ``` ### `EbitdaChartsProps` ```typescript type EbitdaChartsProps = { showEbitdaBarChart: boolean ebitdaChartData: BarChartDataResult btcDisplayData: BarChartDataResult isLoading: boolean hasBtcProducedAllZeros: boolean } ``` ### `EbitdaDisplayMetrics` Display metrics for the financial EBITDA reporting surface (foundation). Values mirror Mining OS `Views/Financial/EBITDA/EBITDA.types` `EbitdaMetrics`. ```typescript type EbitdaDisplayMetrics = { bitcoinProductionCost: number bitcoinPrice: number bitcoinProduced: number ebitdaSellingBTC: number actualEbitda: number ebitdaNotSellingBTC: number } ``` ### `EbitdaHodlCardProps` ```typescript type EbitdaHodlCardProps = { value: number currentBTCPrice: number } ``` ### `EbitdaLogEntry` ```typescript type EbitdaLogEntry = { ts: number revenueBTC: number revenueUSD: number btcPrice: number powerW: number hashrateMhs: number consumptionMWh: number energyCostsUSD: number operationalCostsUSD: number totalCostsUSD: number ebitdaSelling: number ebitdaHodl: number… ``` ### `EbitdaMetricsProps` ```typescript type EbitdaMetricsProps = { metrics: EbitdaDisplayMetrics currentBTCPrice: number } ``` ### `EbitdaProps` ```typescript type EbitdaProps = { metrics: EbitdaDisplayMetrics | null ebitdaChartInput: ToBarChartDataInput | null btcProducedChartInput: ToBarChartDataInput | null hasBtcProducedAllZeros: boolean showEbitdaBarChart: boolean currentBTCPrice: number datePicker: ReactElem… ``` ### `EbitdaQueryParams` ```typescript type EbitdaQueryParams = { start: number end: number period: FinancePeriod } ``` ### `EbitdaResponse` ```typescript type EbitdaResponse = FinanceResponse<EbitdaLogEntry, EbitdaTotals> ``` ### `EbitdaSellingCardProps` ```typescript type EbitdaSellingCardProps = { value: number } ``` ### `EbitdaTotals` ```typescript type EbitdaTotals = { totalRevenueBTC: number totalRevenueUSD: number totalCostsUSD: number totalEbitdaSelling: number totalEbitdaHodl: number avgBtcProductionCost: number | null currentBtcPrice: number } ``` ### `EbitdaViewModel` ```typescript type EbitdaViewModel = { metrics: EbitdaDisplayMetrics | null ebitdaChartInput: ToBarChartDataInput | null btcProducedChartInput: ToBarChartDataInput | null hasBtcProducedAllZeros: boolean currentBTCPrice: number /** When false, hide the EBITDA bar group (Mining… ``` ### `EfficiencyDateRange` ```typescript type EfficiencyDateRange = { start: number; end: number } ``` ### `EfficiencyMinerTypeTailLog` ```typescript type EfficiencyMinerTypeTailLog = Record<string, unknown> ``` ### `EfficiencyMinerTypeViewProps` ```typescript type EfficiencyMinerTypeViewProps = Omit<EfficiencyBarViewProps, 'title'> ``` ### `EfficiencyMinerUnitTailLog` ```typescript type EfficiencyMinerUnitTailLog = Record<string, unknown> ``` ### `EfficiencyMinerUnitViewProps` ```typescript type EfficiencyMinerUnitViewProps = Omit<EfficiencyBarViewProps, 'title'> ``` ### `EfficiencySiteViewProps` ```typescript type EfficiencySiteViewProps = { log?: MetricsEfficiencyLogEntry[] avgEfficiency?: number | null nominalValue?: number | null isLoading?: boolean dateRange?: EfficiencyDateRange onDateRangeChange?: (range: EfficiencyDateRange) => void onReset?: VoidFunction } ``` ### `EfficiencyTabValue` ```typescript type EfficiencyTabValue = (typeof EfficiencyTabTypes)[keyof typeof EfficiencyTabTypes] ``` ### `EmptyStateImage` ```typescript type EmptyStateImage = 'default' | 'simple' | ReactNode ``` ### `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"… ``` ### `EmptyStateSize` ```typescript type EmptyStateSize = ComponentSize ``` ### `EnabledDisableToggleProps` ```typescript type EnabledDisableToggleProps = { value: unknown tankNumber: number | string isButtonDisabled: boolean isOffline: boolean onToggle: (params: EnabledDisableToggleCbParams) => void } ``` ### `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 } ``` ### `EnergyBalanceData` ```typescript type EnergyBalanceData = { revenueMetrics: EnergyRevenueMetrics | null costMetrics: EnergyCostMetrics | null energyRevenueChartInput: ThresholdBarChartInput averageDowntimeData: AverageDowntimeChartData powerChartInput: ThresholdLineChartInput powerChartCostInput:… ``` ### `EnergyBalanceLogEntry` ```typescript type EnergyBalanceLogEntry = { ts: number powerW: number consumptionMWh: number revenueBTC: number revenueUSD: number btcPrice: number energyCostUSD: number totalCostUSD: number energyRevenuePerMWh: number | null allInCostPerMWh: number | null profitUSD: number curtai… ``` ### `EnergyBalancePowerChartProps` ```typescript type EnergyBalancePowerChartProps = { height?: number fillHeight?: boolean periodType: PeriodType chartInput: ThresholdLineChartInput } ``` ### `EnergyBalanceProps` ```typescript type EnergyBalanceProps = { viewModel: EnergyBalanceViewModel onTabChange: (tab: EnergyBalanceTab) => void onRevenueDisplayModeChange: (mode: DisplayMode) => void onCostDisplayModeChange: (mode: DisplayMode) => void isDemoMode?: boolean /** Slot for timeframe / dat… ``` ### `EnergyBalanceQueryParams` ```typescript type EnergyBalanceQueryParams = { start: number end: number period: FinancePeriod } ``` ### `EnergyBalanceResponse` ```typescript type EnergyBalanceResponse = FinanceResponse<EnergyBalanceLogEntry, EnergyBalanceTotals> ``` ### `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 } ``` ### `EnergyBalanceTab` ```typescript type EnergyBalanceTab = 'revenue' | 'cost' ``` ### `EnergyBalanceTotals` ```typescript type EnergyBalanceTotals = { totalRevenueBTC: number totalRevenueUSD: number totalCostUSD: number totalProfitUSD: number avgCostPerMWh: number | null avgRevenuePerMWh: number | null totalConsumptionMWh: number avgCurtailmentRate: number | null avgOperationalIssuesRa… ``` ### `EnergyBalanceViewModel` ```typescript type EnergyBalanceViewModel = EnergyBalanceData & { activeTab: EnergyBalanceTab revenueDisplayMode: DisplayMode costDisplayMode: DisplayMode isLoading: boolean errors: string[] hasDateSelection: boolean } ``` ### `EnergyCostChartInput` ```typescript type EnergyCostChartInput = ThresholdBarChartInput & { btcUnit: string | null } ``` ### `EnergyCostChartProps` ```typescript type EnergyCostChartProps = { chartData: BarChartDataResult btcUnit: EnergyCostChartInput['btcUnit'] displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => void height?: number } ``` ### `EnergyCostMetrics` ```typescript type EnergyCostMetrics = { avgPowerConsumption: number avgEnergyCost: number avgAllInCost: number avgPowerAvailability: number avgOperationsCost: number avgEnergyRevenue: number } ``` ### `EnergyMetricCardProps` ```typescript type EnergyMetricCardProps = { name: string value: number unit: string fallback?: string } ``` ### `EnergyReportBarChartLegacy` ```typescript type EnergyReportBarChartLegacy = { labels: string[] dataSet1: { label: string; data: number[] } } ``` ### `EnergyReportBarViewProps` ```typescript type EnergyReportBarViewProps = { title: string isEmpty?: boolean isLoading?: boolean chartInput?: ToBarChartDataInput onTimeFrameChange?: (start: Date, end: Date) => void } ``` ### `EnergyReportContainer` ```typescript type EnergyReportContainer = Container & { containerId?: string minersCount?: number } ``` ### `EnergyReportDateRange` ```typescript type EnergyReportDateRange = { start: number; end: number } ``` ### `EnergyReportGroupedBarViewProps` ```typescript type EnergyReportGroupedBarViewProps = { isLoading?: boolean containers?: Container[] groupedConsumption?: MetricsConsumptionGroupedResponse onTimeFrameChange?: EnergyReportBarViewProps['onTimeFrameChange'] } ``` ### `EnergyReportMinerSliceConfig` ```typescript type EnergyReportMinerSliceConfig = { title: string groupBy: MetricsConsumptionGroupBy filterCategory?: (category: string) => boolean getLabelName: (category: string, containers?: Container[]) => string } ``` ### `EnergyReportMinerTypeViewProps` ```typescript type EnergyReportMinerTypeViewProps = EnergyReportGroupedBarViewProps ``` ### `EnergyReportMinerUnitViewProps` ```typescript type EnergyReportMinerUnitViewProps = EnergyReportGroupedBarViewProps ``` ### `EnergyReportMinerViewSlice` ```typescript type EnergyReportMinerViewSlice = (typeof ENERGY_REPORT_MINER_VIEW_SLICES)[keyof typeof ENERGY_REPORT_MINER_VIEW_SLICES] ``` ### `EnergyReportProps` ```typescript type EnergyReportProps = { defaultTab?: EnergyReportTabValue siteView?: Omit<EnergyReportSiteViewProps, 'dateRange'> & { dateRange?: EnergyReportDateRange } minerTypeView?: EnergyReportMinerTypeViewProps minerUnitView?: EnergyReportMinerUnitViewProps className?: s… ``` ### `EnergyReportSiteViewProps` ```typescript type EnergyReportSiteViewProps = Omit<UseEnergyReportSiteInput, 'dateRange'> & { snapshotLoading?: boolean onRefetchSnapshot?: VoidFunction dateRange: EnergyReportDateRange onDateRangeChange?: (range: EnergyReportDateRange) => void } ``` ### `EnergyReportTabValue` ```typescript type EnergyReportTabValue = (typeof ENERGY_REPORT_TAB_TYPES)[keyof typeof ENERGY_REPORT_TAB_TYPES] ``` ### `EnergyReportTailLogItem` ```typescript type EnergyReportTailLogItem = Record< string, EnergyReportTailLogNumericBucket | number | undefined > ``` ### `EnergyReportTailLogNumericBucket` ```typescript type EnergyReportTailLogNumericBucket = Record<string, number> ``` ### `EnergyRevenueChartProps` ```typescript type EnergyRevenueChartProps = { chartData: BarChartDataResult displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => void height?: number } ``` ### `EnergyRevenueMetrics` ```typescript type EnergyRevenueMetrics = { curtailmentRate: number operationalIssuesRate: number } ``` ### `EntryData` ```typescript type EntryData = { [key: string]: number | null | undefined } ``` ### `ErrorBoundaryProps` ```typescript type ErrorBoundaryProps = { /** * Fallback UI to render when an error is caught. * If not provided, a default error panel with expandable stack trace is shown. */ fallback?: ReactNode /** * Name of the wrapped component (shown in the default fallback) */ componentN… ``` ### `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… ``` ### `ErrorCardVariant` ```typescript type ErrorCardVariant = 'card' | 'inline' ``` ### `ErrorWithTimestamp` ```typescript type ErrorWithTimestamp = { msg?: string message?: string timestamp?: number | string } ``` ### `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`. */ onNavigate?: (path: string) => void /** Compact layout… ``` ### `ExplorerLayoutProps` ```typescript type ExplorerLayoutProps = { /** Page heading. */ 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/container table. */ list: ReactNode… ``` ### `ExplorerRowSelection` Row-selection map from `<DeviceExplorer>` — thing id → selected. ```typescript type ExplorerRowSelection = Record<string, boolean> ``` ### `ExplorerThingDetailRow` ```typescript type ExplorerThingDetailRow = { label: string value: string } ``` ### `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']`. */ formats?: readonly ExportFormat[] /** Button label — defau… ``` ### `ExportFormat` ```typescript type ExportFormat = 'csv' | 'json' ``` ### `ExtraTooltipData` ```typescript type ExtraTooltipData = Record<number, string> ``` ### `FeatureFlagsSettingsProps` ```typescript type FeatureFlagsSettingsProps = { featureFlags: Record<string, boolean> isEditingEnabled: boolean isLoading?: boolean isSaving?: boolean onSave: (flags: Record<string, boolean>) => void className?: string } ``` ### `FieldName` Extract field names from a form schema with type safety. Useful for creating type-safe field name constants. ```typescript type FieldName = FieldPath<TFieldValues> ``` ### `FilterSelectionTuple` ```typescript type FilterSelectionTuple = CascaderValue ``` ### `FinancePeriod` Finance v2 API types - shapes returned by `/auth/finance/*` endpoints. ```typescript type FinancePeriod = 'daily' | 'weekly' | 'monthly' | 'yearly' ``` ### `FinanceQueryParams` ```typescript type FinanceQueryParams = { start: number end: number period?: FinancePeriod overwriteCache?: boolean } ``` ### `FinanceResponse` ```typescript type FinanceResponse = { log: Log[] summary: Summary } ``` ### `FinanceRevenueLogEntry` ```typescript type FinanceRevenueLogEntry = { ts: number revenueBTC: number feesBTC: number netRevenueBTC: number } ``` ### `FinanceRevenueQueryParams` ```typescript type FinanceRevenueQueryParams = FinanceQueryParams & { pool?: string } ``` ### `FinanceRevenueResponse` ```typescript type FinanceRevenueResponse = FinanceResponse<FinanceRevenueLogEntry, FinanceRevenueTotals> ``` ### `FinanceRevenueTotals` ```typescript type FinanceRevenueTotals = { totalRevenueBTC: number totalFeesBTC: number totalNetRevenueBTC: number } ``` ### `FinancialDateRange` ```typescript type FinancialDateRange = { start: number end: number period?: PeriodValue } ``` ### `FinancialRangeChangeOptions` ```typescript type FinancialRangeChangeOptions = { year?: number month?: number period?: PeriodValue } ``` ### `FlexAlign` Flex/Grid alignment options Used by Popover, charts, and layout components ```typescript type FlexAlign = 'start' | 'center' | 'end' ``` ### `FormatHashBalanceValueOptions` ```typescript type FormatHashBalanceValueOptions = { forAxis?: boolean } ``` ### `FormCascaderProps` ```typescript type FormCascaderProps = BaseFormFieldProps<TFieldValues, TName> & { options: CascaderOption[] multiple?: boolean cascaderProps?: Omit< React.ComponentProps<typeof Cascader>, 'value' | 'onChange' | 'options' | 'placeholder' > } ``` ### `FormCheckboxProps` ```typescript type FormCheckboxProps = BaseFormFieldProps<TFieldValues, TName> & { checkboxProps?: React.ComponentProps<typeof Checkbox> layout?: 'row' | 'column' } ``` ### `FormDatePickerProps` ```typescript type FormDatePickerProps = BaseFormFieldProps<TFieldValues, TName> & { datePickerProps?: Omit<React.ComponentProps<typeof DatePicker>, 'selected' | 'onSelect'> } ``` ### `FormInputProps` ```typescript type FormInputProps = BaseFormFieldProps<TFieldValues, TName> & { type?: React.ComponentProps<typeof Input>['type'] variant?: React.ComponentProps<typeof Input>['variant'] inputProps?: Omit<React.ComponentProps<typeof Input>, 'type' | 'variant'> } ``` ### `FormProps` Form wrapper that provides react-hook-form context to child components. ```typescript type FormProps = Omit< ComponentProps<'form'>, 'children' > & { form: UseFormReturn<TFieldValues> children: ReactNode } ``` ### `FormRadioGroupProps` ```typescript type FormRadioGroupProps = BaseFormFieldProps<TFieldValues, TName> & { options: FormRadioOption[] orientation?: 'horizontal' | 'vertical' radioGroupProps?: Omit< React.ComponentProps<typeof RadioGroup>, 'onValueChange' | 'defaultValue' | 'orientation' > } ``` ### `FormRadioOption` ```typescript type FormRadioOption = { value: string label: string disabled?: boolean } ``` ### `FormSelectOption` ```typescript type FormSelectOption = { value: string label: string disabled?: boolean } ``` ### `FormSelectProps` ```typescript type FormSelectProps = BaseFormFieldProps<TFieldValues, TName> & { options: FormSelectOption[] selectProps?: Omit<React.ComponentProps<typeof Select>, 'onValueChange' | 'defaultValue'> } ``` ### `FormSwitchProps` ```typescript type FormSwitchProps = BaseFormFieldProps<TFieldValues, TName> & { switchProps?: Omit<React.ComponentProps<typeof Switch>, 'checked' | 'onCheckedChange'> layout?: 'row' | 'column' } ``` ### `FormTagInputProps` ```typescript type FormTagInputProps = BaseFormFieldProps<TFieldValues, TName> & { options?: TagInputOption[] allowCustomTags?: boolean variant?: 'default' | 'search' tagInputProps?: Omit< React.ComponentProps<typeof TagInput>, 'value' | 'onTagsChange' | 'label' | 'placeholder'… ``` ### `FormTextAreaProps` ```typescript type FormTextAreaProps = BaseFormFieldProps<TFieldValues, TName> & { textAreaProps?: React.ComponentProps<typeof TextArea> } ``` ### `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. */ colors?: string[] /** Arc thickness as a fraction of the gauge radius (0–1). */ arcWidth?: number /**… ``` ### `GetAlertsTableColumnsOptions` ```typescript type GetAlertsTableColumnsOptions = { getFormattedDate: (date: Date) => string } ``` ### `GetColumnConfigParams` ```typescript type GetColumnConfigParams = { getFormattedDate: (date: Date) => string renderAction: (device: DeviceExplorerDeviceData) => React.ReactNode } ``` ### `GlobalConfig` ```typescript type GlobalConfig = { nominalSiteHashrate_MHS?: number nominalAvailablePowerMWh?: number nominalPowerConsumption_MW?: number nominalWeightedAvgEfficiency_WThs?: number nominalMinerCapacity?: number isAutoSleepAllowed?: boolean siteEnergyDataThresholdMWh?: num… ``` ### `HashBalanceCostPanelProps` ```typescript type HashBalanceCostPanelProps = HashBalancePanelProps ``` ### `HashBalanceCurrency` ```typescript type HashBalanceCurrency = typeof CURRENCY.USD_LABEL | typeof CURRENCY.BTC_LABEL ``` ### `HashBalanceMetric` ```typescript type HashBalanceMetric = { label: string unit: string value: number isHighlighted?: boolean } ``` ### `HashBalancePanelProps` ```typescript type HashBalancePanelProps = Pick< UseHashBalanceInput, 'data' | 'log' | 'dateRange' | 'timeframeType' > & { isLoading?: boolean } ``` ### `HashBalanceProps` ```typescript type HashBalanceProps = Partial<{ isError: boolean isLoading: boolean errorMessage: string className: string tabsClassName: string tabsListClassName: string data: HashRevenueResponse | null initialDateRange: FinancialDateRange onDateRangeChange: (dateRange: Finan… ``` ### `HashBalanceRevenuePanelProps` ```typescript type HashBalanceRevenuePanelProps = HashBalancePanelProps & { currency: HashBalanceCurrency onCurrencyChange: (currency: HashBalanceCurrency) => void } ``` ### `HashrateBarChartData` ```typescript type HashrateBarChartData = { labels: string[] series: { label: string values: number[] color: string }[] } ``` ### `HashrateDateRange` ```typescript type HashrateDateRange = { start: number; end: number } ``` ### `HashrateFilterOption` ```typescript type HashrateFilterOption = { value: string label: string } ``` ### `HashrateGroupBy` groupBy axis for the v2 grouped hashrate endpoint. ```typescript type HashrateGroupBy = 'miner' | 'container' ``` ### `HashrateGroupedLog` ```typescript type HashrateGroupedLog = ReadonlyArray<HashrateGroupedLogEntry> ``` ### `HashrateGroupedLogEntry` Single bucket of a v2 `/auth/metrics/hashrate` grouped response. ```typescript type HashrateGroupedLogEntry = { ts: number hashrateMhs: Record<string, number> } ``` ### `HashrateGroupedQueryData` ```typescript type HashrateGroupedQueryData = { log?: HashrateGroupedLog } ``` ### `HashrateLabelDivisorKey` ```typescript type HashrateLabelDivisorKey = keyof typeof HASHRATE_LABEL_DIVISOR ``` ### `HashrateLabelDivisorValue` ```typescript type HashrateLabelDivisorValue = (typeof HASHRATE_LABEL_DIVISOR)[HashrateLabelDivisorKey] ``` ### `HashrateMinerTypeViewProps` ```typescript type HashrateMinerTypeViewProps = { /** Hashrate log grouped by miner type (groupBy=miner). */ log?: HashrateGroupedLog isLoading?: boolean dateRange?: HashrateDateRange onDateRangeChange?: (range: HashrateDateRange) => void onReset?: VoidFunction } ``` ### `HashrateMiningUnitViewProps` ```typescript type HashrateMiningUnitViewProps = { /** Hashrate log grouped by container / mining unit (groupBy=container). */ log?: HashrateGroupedLog isLoading?: boolean dateRange?: HashrateDateRange onDateRangeChange?: (range: HashrateDateRange) => void onReset?: VoidFunction } ``` ### `HashrateProps` ```typescript type HashrateProps = { /** Tab selected on first render. Defaults to the Site View. */ defaultTab?: HashrateTabValue /** Props forwarded to the Site View tab. */ siteView?: HashrateSiteViewProps /** Props forwarded to the Miner Type View tab. */ minerTypeView?… ``` ### `HashrateQueryState` ```typescript type HashrateQueryState = { data?: HashrateGroupedQueryData isLoading?: boolean error?: unknown } ``` ### `HashrateSeries` ```typescript type HashrateSeries = { label: string color?: string points: HashrateSeriesPoint[] } ``` ### `HashrateSeriesPoint` ```typescript type HashrateSeriesPoint = { ts: string value: number } ``` ### `HashrateSiteViewChartData` ```typescript type HashrateSiteViewChartData = { series: HashrateSeries[] } ``` ### `HashrateSiteViewProps` ```typescript type HashrateSiteViewProps = { /** Hashrate log grouped by miner type. */ log?: HashrateGroupedLog /** Loading state - drives the chart spinner. */ isLoading?: boolean /** Selected date range used by the host to drive the query. */ dateRange?: HashrateDateRange /** Fi… ``` ### `HashrateTabValue` ```typescript type HashrateTabValue = (typeof HashrateTabTypes)[keyof typeof HashrateTabTypes] ``` ### `HashrateUnit` ```typescript type HashrateUnit = ValueUnit & { unit: string } ``` ### `HashRevenueLogEntry` ```typescript type HashRevenueLogEntry = { ts: number revenueBTC: number feesBTC: number revenueUSD: number feesUSD: number btcPrice: number hashrateMhs: number hashRevenueBTCPerPHsPerDay: number | null hashRevenueUSDPerPHsPerDay: number | null hashCostBTCPerPHsPerDay: number | n… ``` ### `HashRevenueResponse` ```typescript type HashRevenueResponse = FinanceResponse<HashRevenueLogEntry, HashRevenueTotals> ``` ### `HashRevenueTotals` ```typescript type HashRevenueTotals = { avgHashRevenueBTCPerPHsPerDay: number | null avgHashRevenueUSDPerPHsPerDay: number | null avgHashCostBTCPerPHsPerDay: number | null avgHashCostUSDPerPHsPerDay: number | null avgNetworkHashPriceBTCPerPHsPerDay: number | null avgNetworkHas… ``` ### `HeaderConsumptionBoxProps` ```typescript type HeaderConsumptionBoxProps = { icon?: ReactNode /** Current site-level power consumption, in megawatts. */ valueMw?: number /** Unit label — defaults to `MW`. */ unit?: string className?: string } ``` ### `HeaderControlsSettingsProps` ```typescript type HeaderControlsSettingsProps = { preferences: HeaderPreferences isLoading?: boolean onToggle: (key: keyof HeaderPreferences, value: boolean) => void onReset: VoidFunction className?: string } ``` ### `HeaderEfficiencyBoxProps` ```typescript type HeaderEfficiencyBoxProps = { icon?: ReactNode /** Efficiency in watts per TH/s. */ valueWthS?: number /** Unit label — defaults to `W/TH/S`. */ unit?: string className?: string } ``` ### `HeaderHashrateBoxProps` ```typescript type HeaderHashrateBoxProps = { icon?: ReactNode /** MOS-side aggregate hashrate in PH/s. */ mosPhs?: number /** Pool-side aggregate hashrate in PH/s. */ poolPhs?: number /** Hashrate unit label — defaults to `PH/s`. */ unit?: string className?: string } ``` ### `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`… ``` ### `HeaderPreferences` ```typescript type HeaderPreferences = { poolMiners: boolean mosMiners: boolean poolHashrate: boolean mosHashrate: boolean consumption: boolean efficiency: boolean } ``` ### `HeaderStatsBarProps` ```typescript type HeaderStatsBarProps = { /** Stat boxes to render in order, left-to-right. */ children: ReactNode /** Optional class hook. */ className?: string } ``` ### `HeatmapCell` A single heatmap cell. ```typescript type HeatmapCell = { /** Numeric value driving the cell colour; `null` renders the empty colour. */ value: number | null /** Text shown in the cell (defaults to the value when `showValues` is on). */ label?: string /** Stable React key (defaults to the row/c… ``` ### `HeatmapCellContext` Context handed to `renderCell` for a single cell. ```typescript type HeatmapCellContext = { /** The colour resolved for this cell from the gradient (or the empty colour). */ color: string /** Zero-based row index. */ row: number /** Zero-based column index. */ col: number } ``` ### `HeatmapKey` ```typescript type HeatmapKey = keyof typeof HEATMAP ``` ### `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 /*… ``` ### `HeatmapModeKey` ```typescript type HeatmapModeKey = keyof typeof HEATMAP_MODE ``` ### `HeatmapModeValue` ```typescript type HeatmapModeValue = (typeof HEATMAP_MODE)[HeatmapModeKey] ``` ### `HeatmapProps` ```typescript type HeatmapProps = { /** Rows of cells (row-major). Rows may be ragged. */ data: HeatmapCell[][] /** Range floor; auto-derived from the finite values when omitted. */ min?: number /** Range ceiling; auto-derived from the finite values when omitted. */ max?:… ``` ### `HighlightedValueProps` ```typescript type HighlightedValueProps = { value: string | number unit?: string className?: string style?: CSSProperties } ``` ### `HistoricalAlertsProps` ```typescript type HistoricalAlertsProps = { /** * Pre-fetched historical alerts log entries (each with a `thing` device payload). */ alerts?: Alert[] isLoading?: boolean /** * Filters and search tags coming from the parent (typically shared with `CurrentAlerts`). */ localFilters:… ``` ### `HistoricalAlertsRange` ```typescript type HistoricalAlertsRange = { start: number end: number } ``` ### `IconProps` ```typescript type IconProps = { /** Sets both width and height */ size?: number | string /** Only affects single-color icons (default: 'currentColor') */ color?: string children?: never } & SVGAttributes<SVGElement> ``` ### `ImportExportSettingsProps` ```typescript type ImportExportSettingsProps = { onExport: VoidFunction onImport: (data: SettingsExportData) => void onParseFile?: (file: File) => Promise<SettingsExportData> isExporting?: boolean isImporting?: boolean className?: string } ``` ### `IndicatorColor` ```typescript type IndicatorColor = | 'red' | 'gray' | 'blue' | 'yellow' | 'green' | 'purple' | 'amber' | 'slate' ``` ### `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<ComponentProps<'input'>, 'prefix' | 'size'> & { /** * Optional label displayed above the input */ label?: string /** * HTML id for the input. Required when using label for accessibility. */ id?: string /** * Variant of the input * - `… ``` ### `InputSize` ```typescript type InputSize = 'default' | 'medium' ``` ### `LabeledCardNavigateOptions` ```typescript type LabeledCardNavigateOptions = Partial<{ href: string target: string }> ``` ### `LabeledCardProps` ```typescript type LabeledCardProps = Partial<{ isDark: boolean className: string hasNoWrap: boolean isRelative: boolean isFullWidth: boolean hasNoMargin: boolean hasNoBorder: boolean isFullHeight: boolean isScrollable: boolean label: ReactNode children: ReactNode getNavigateO… ``` ### `LabelToIgnoreValue` ```typescript type LabelToIgnoreValue = (typeof LABEL_TO_IGNORE)[number] ``` ### `LegendItem` ```typescript type LegendItem = { label: string color: string hidden?: boolean } ``` ### `LightWeightLineChartProps` ```typescript type LightWeightLineChartProps = { /** * Mutable ref to hold the LightWeightCharts reference */ chartRef?: MutableRefObject<IChartApi | null> /** * Data of the chart */ data: LineChartData /** * Callback to format ticks on y axis. If `priceFormatter` is given. It would be… ``` ### `LineChartCardData` ```typescript type LineChartCardData = { /** Chart datasets */ datasets: LineChartCardDataset[] } & Partial<{ /** Y-axis tick formatter */ yTicksFormatter: (value: number) => string /** Price formatter for lightweight-charts */ priceFormatter: (value: number) => string /** Whet… ``` ### `LineChartCardDataset` ```typescript type LineChartCardDataset = { /** Label for the dataset (used in legend) */ label?: string /** Line color */ borderColor: string /** Data points */ data: Array<{ x: number; y: number | null }> /** Whether this dataset is visible */ visible?: boolean /** Custom icon f… ``` ### `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… ``` ### `LineChartData` ```typescript type LineChartData = { datasets: LineDataset[] } ``` ### `LineDataPoint` ```typescript type LineDataPoint = { x: number; y: number | null | undefined } ``` ### `LineDataset` ```typescript type LineDataset = { label?: string visible?: boolean borderColor: string borderWidth?: number extraTooltipData?: ExtraTooltipData data: LineDataPoint[] } ``` ### `LineSeriesApi` ```typescript type LineSeriesApi = ISeriesApi<'Line', Time> ``` ### `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… ``` ### `LocalFilters` ```typescript type LocalFilters = Record<string, string | number | boolean | (string | number | boolean)[]> ``` ### `LogActivityIconProps` ```typescript type LogActivityIconProps = { status: string } ``` ### `LogData` ```typescript type LogData = { uuid: string body: string title: string status: string subtitle: string } ``` ### `LogDotProps` ```typescript type LogDotProps = { type: string status: string } ``` ### `LogFormattedAlertData` ```typescript type LogFormattedAlertData = { title: string subtitle: string status: string severityLevel: number creationDate: number | string body: string id: string uuid?: string [key: string]: unknown } ``` ### `LogItemProps` ```typescript type LogItemProps = { data: LogData onLogClicked?: (uuid: string) => void } ``` ### `LogPagination` ```typescript type LogPagination = { current: number total: number pageSize: number handlePaginationChange: (page: number) => void } ``` ### `LogRowProps` ```typescript type LogRowProps = { log: LogData type: string style?: CSSProperties onLogClicked?: (uuid: string) => void } ``` ### `LogsCardProps` ```typescript type LogsCardProps = Partial<{ type: string label: string isDark: boolean isLoading: boolean logsData: LogData[] emptyMessage: string skeletonRows: number pagination: LogPagination onLogClicked: (uuid: string) => void }> ``` ### `LvCabinetRecord` ```typescript type LvCabinetRecord = { id: string powerMeters?: PowerMeter[] } ``` ### `ManageUserModalProps` ```typescript type ManageUserModalProps = { open: boolean onClose: VoidFunction user: SettingsUser roles: RoleOption[] rolePermissions: Record<string, Record<string, PermLevel>> permissionLabels: Record<string, string> onSubmit: (data: { id: string; name: string; email: string; ro… ``` ### `MaxUnitValueKey` ```typescript type MaxUnitValueKey = keyof typeof MAX_UNIT_VALUE ``` ### `MaxUnitValueValue` ```typescript type MaxUnitValueValue = (typeof MAX_UNIT_VALUE)[MaxUnitValueKey] ``` ### `Maybe` ```typescript type Maybe = T | null | undefined ``` ### `MdkWordmarkProps` ```typescript type MdkWordmarkProps = { /** Visual size of the wordmark. `sm` ≈ 24px tall, `md` ≈ 32px, `lg` ≈ 64px. */ size?: MdkWordmarkSize /** Optional class hook on the outer `<svg>`. */ className?: string /** Accessible label. Defaults to "MDK". */ title?: string } ``` ### `MdkWordmarkSize` ```typescript type MdkWordmarkSize = 'sm' | 'md' | 'lg' ``` ### `MetricsConsumptionGroupBy` ```typescript type MetricsConsumptionGroupBy = 'container' | 'miner' ``` ### `MetricsConsumptionGroupedLogEntry` ```typescript type MetricsConsumptionGroupedLogEntry = { ts: number powerW: Record<string, number> consumptionMWh: Record<string, number> | null } ``` ### `MetricsConsumptionGroupedResponse` ```typescript type MetricsConsumptionGroupedResponse = MetricsResponse< MetricsConsumptionGroupedLogEntry, MetricsConsumptionGroupedSummary > ``` ### `MetricsConsumptionGroupedSummary` ```typescript type MetricsConsumptionGroupedSummary = { avgPowerW: number | null totalConsumptionMWh: number groupedBy?: Record<string, MetricsConsumptionGroupSummary> } ``` ### `MetricsConsumptionGroupSummary` ```typescript type MetricsConsumptionGroupSummary = { avgPowerW: number | null totalConsumptionMWh: number } ``` ### `MetricsConsumptionLogEntry` ```typescript type MetricsConsumptionLogEntry = { ts: number powerW: number consumptionMWh: number } ``` ### `MetricsConsumptionQueryParams` ```typescript type MetricsConsumptionQueryParams = MetricsQueryParams & { groupBy?: MetricsConsumptionGroupBy } ``` ### `MetricsConsumptionResponse` ```typescript type MetricsConsumptionResponse = MetricsResponse< MetricsConsumptionLogEntry, MetricsConsumptionSummary > ``` ### `MetricsConsumptionSummary` ```typescript type MetricsConsumptionSummary = { avgPowerW: number | null totalConsumptionMWh: number } ``` ### `MetricsEfficiencyLogEntry` ```typescript type MetricsEfficiencyLogEntry = { ts: number efficiencyWThs: number } ``` ### `MetricsEfficiencyResponse` ```typescript type MetricsEfficiencyResponse = MetricsResponse< MetricsEfficiencyLogEntry, MetricsEfficiencySummary > ``` ### `MetricsEfficiencySummary` ```typescript type MetricsEfficiencySummary = { avgEfficiencyWThs: number | null } ``` ### `MetricsHashrateGroupBy` ```typescript type MetricsHashrateGroupBy = 'container' | 'miner' ``` ### `MetricsHashrateGroupedLogEntry` ```typescript type MetricsHashrateGroupedLogEntry = { ts: number hashrateMhs: Record<string, number> } ``` ### `MetricsHashrateGroupedResponse` ```typescript type MetricsHashrateGroupedResponse = MetricsResponse< MetricsHashrateGroupedLogEntry, MetricsHashrateGroupedSummary > ``` ### `MetricsHashrateGroupedSummary` ```typescript type MetricsHashrateGroupedSummary = { avgHashrateMhs: number | null totalHashrateMhs: number groupedBy?: Record<string, MetricsHashrateSummary> } ``` ### `MetricsHashrateLogEntry` ```typescript type MetricsHashrateLogEntry = { ts: number hashrateMhs: number } ``` ### `MetricsHashrateQueryParams` ```typescript type MetricsHashrateQueryParams = MetricsQueryParams & { groupBy?: MetricsHashrateGroupBy } ``` ### `MetricsHashrateResponse` ```typescript type MetricsHashrateResponse = MetricsResponse< MetricsHashrateLogEntry, MetricsHashrateSummary > ``` ### `MetricsHashrateSummary` ```typescript type MetricsHashrateSummary = { avgHashrateMhs: number | null totalHashrateMhs: number } ``` ### `MetricsInterval` ```typescript type MetricsInterval = '1h' | '1d' | '1w' ``` ### `MetricsMinerStatusLogEntry` ```typescript type MetricsMinerStatusLogEntry = { ts: number online: number offline: number sleep: number maintenance: number } ``` ### `MetricsMinerStatusResponse` ```typescript type MetricsMinerStatusResponse = MetricsResponse< MetricsMinerStatusLogEntry, MetricsMinerStatusSummary > ``` ### `MetricsMinerStatusSummary` ```typescript type MetricsMinerStatusSummary = { avgOnline: number | null avgOffline: number | null avgSleep: number | null avgMaintenance: number | null } ``` ### `MetricsPowerModeLogEntry` ```typescript type MetricsPowerModeLogEntry = { ts: number low: number normal: number high: number sleep: number offline: number notMining: number maintenance: number error: number } ``` ### `MetricsPowerModeQueryParams` ```typescript type MetricsPowerModeQueryParams = MetricsQueryParams & { interval?: MetricsInterval } ``` ### `MetricsPowerModeResponse` ```typescript type MetricsPowerModeResponse = MetricsResponse< MetricsPowerModeLogEntry, MetricsPowerModeSummary > ``` ### `MetricsPowerModeSummary` ```typescript type MetricsPowerModeSummary = { avgLow: number | null avgNormal: number | null avgHigh: number | null avgSleep: number | null avgOffline: number | null avgNotMining: number | null avgMaintenance: number | null avgError: number | null } ``` ### `MetricsPowerModeTimelineLogEntry` ```typescript type MetricsPowerModeTimelineLogEntry = { minerId: string container: string segments: MetricsPowerModeTimelineSegment[] } ``` ### `MetricsPowerModeTimelineQueryParams` ```typescript type MetricsPowerModeTimelineQueryParams = { start?: number end?: number container?: string overwriteCache?: boolean } ``` ### `MetricsPowerModeTimelineResponse` ```typescript type MetricsPowerModeTimelineResponse = { log: MetricsPowerModeTimelineLogEntry[] } ``` ### `MetricsPowerModeTimelineSegment` ```typescript type MetricsPowerModeTimelineSegment = { from: number to: number powerMode: string status: string } ``` ### `MetricsQueryParams` Operational metrics v2 API types - shapes returned by `/auth/metrics/*` endpoints. ```typescript type MetricsQueryParams = { start: number end: number overwriteCache?: boolean } ``` ### `MetricsResponse` ```typescript type MetricsResponse = { log: Log[] summary: Summary } ``` ### `MetricsTemperatureContainerStats` ```typescript type MetricsTemperatureContainerStats = { maxC: number avgC: number } ``` ### `MetricsTemperatureLogEntry` ```typescript type MetricsTemperatureLogEntry = { ts: number containers: Record<string, MetricsTemperatureContainerStats> siteMaxC: number | null siteAvgC: number | null } ``` ### `MetricsTemperatureQueryParams` ```typescript type MetricsTemperatureQueryParams = MetricsQueryParams & { interval?: MetricsInterval container?: string } ``` ### `MetricsTemperatureResponse` ```typescript type MetricsTemperatureResponse = MetricsResponse< MetricsTemperatureLogEntry, MetricsTemperatureSummary > ``` ### `MetricsTemperatureSummary` ```typescript type MetricsTemperatureSummary = { avgMaxTemp: number | null avgAvgTemp: number | null peakTemp: number | null } ``` ### `MetricValueProps` ```typescript type MetricValueProps = { value: number | string unit: string } ``` ### `MicroBTWidgetBoxProps` ```typescript type MicroBTWidgetBoxProps = { data?: Device } ``` ### `MinerActionValue` ```typescript type MinerActionValue = (typeof MINER_ACTIONS)[number] ``` ### `MinerConfig` ```typescript type MinerConfig = { firmware_ver?: string power_mode?: string led_status?: boolean } ``` ### `MinerData` ```typescript type MinerData = { id: string hashrate: MinerHashrate error?: string type?: string info?: { poolConfig?: string } snap?: { config?: { power_mode: string [key: string]: unknown } stats?: { status?: string [key: string]: unknown } } [key: string]: unknown } ``` ### `MinerDeviceSnapshot` ```typescript type MinerDeviceSnapshot = { last?: { snap?: { config?: MinerConfig } } } ``` ### `MinerHashrate` ```typescript type MinerHashrate = { value?: string | number | null unit?: string realValue?: number } ``` ### `MinerHashrateMhs` ```typescript type MinerHashrateMhs = { t_5m?: number } ``` ### `MinerInfo` ```typescript type MinerInfo = { container?: string pos?: string macAddress?: string serialNum?: string } ``` ### `MinerPowerModeTimeline` ```typescript type MinerPowerModeTimeline = { ts?: number miner?: string powerMode?: string data?: { from?: number to?: number } } ``` ### `MinerRecord` ```typescript type MinerRecord = { id?: string shortCode?: string info?: MinerInfo address?: string type?: string alerts?: unknown[] stats?: MinerStats config?: MinerConfig device?: MinerDeviceSnapshot error?: string err?: string isPoolStatsEnabled?: boolean } ``` ### `MinerRow` ```typescript type MinerRow = { id: string code: string unit: string pool: string status?: string } ``` ### `MinersActivityVariant` Visual style for the per-status items. ```typescript type MinersActivityVariant = 'indicators' | 'tiles' ``` ### `MinerSpecificStats` ```typescript type MinerSpecificStats = { upfreq_speed: number [key: string]: unknown } ``` ### `MinersStatusChartData` Pre-shaped data for the miners-status bar chart. ```typescript type MinersStatusChartData = { labels: string[] datasets: MinersStatusDataset[] } ``` ### `MinersStatusDataset` Chart.js dataset for one stacked miners-status series. ```typescript type MinersStatusDataset = { label: string stack: string borderColor: string data: number[] } ``` ### `MinersSummaryBoxProps` ```typescript type MinersSummaryBoxProps = { /** Array of label-value pairs to display in a 2-column grid */ params: MinersSummaryParam[] /** Additional CSS class name */ className?: string } ``` ### `MinersSummaryParam` ```typescript type MinersSummaryParam = { /** Parameter label */ label: string /** Pre-formatted display value (including units) */ value: string } ``` ### `MinerStats` ```typescript type MinerStats = { status?: string uptime_ms?: number power_w?: number hashrate_mhs?: MinerHashrateMhs poolHashrate?: string temperature_c?: { max?: number } } ``` ### `MiningPoolsPanelProps` ```typescript type MiningPoolsPanelProps = Partial<{ /** Override the card title — defaults to `Mining Pools`. */ label: string /** Hide the title row entirely. */ hideHeader: boolean /** Loading state — renders skeleton rows. */ isLoading: boolean /** Number of skeleton rows to sh… ``` ### `MinMaxAvgFormatted` ```typescript type MinMaxAvgFormatted = Partial<{ min: string max: string avg: string }> ``` ### `MinMaxAvgProps` ```typescript type MinMaxAvgProps = MinMaxAvgValues & { className?: string } ``` ### `MinMaxAvgValues` ```typescript type MinMaxAvgValues = Partial<{ min: string max: string avg: string }> ``` ### `MonthlyEbitdaChartProps` ```typescript type MonthlyEbitdaChartProps = { chartData: BarChartDataResult height?: number } ``` ### `MovementData` A single historical device movement: a location/status transition for one device. ```typescript type MovementData = { origin: string destination: string previousStatus: string newStatus: string device?: MovementDevice comments?: ReactNode } ``` ### `MovementDetailsModalProps` Props for `MovementDetailsModal`; pass the selected movement and open/close handlers. ```typescript type MovementDetailsModalProps = Partial<{ isOpen: boolean onClose: () => void movement: MovementData }> ``` ### `MovementDetailsViewModel` Fully resolved, render-ready view of a movement. ```typescript type MovementDetailsViewModel = { device: MovementDeviceView | null origin: MovementSideView destination: MovementSideView comments?: ReactNode } ``` ### `MovementDevice` Device record attached to a movement (e.g. a miner or spare part). All fields optional. ```typescript type MovementDevice = Partial<{ code: string tags: string[] type: string info: Partial<{ subType: string site: string container: string serialNum: string macAddress: string }> }> ``` ### `MovementDeviceView` Render-ready device summary. ```typescript type MovementDeviceView = { code: string model: string attributes: DeviceAttributeView[] } ``` ### `MovementSideView` Resolved label + colors for one side (origin or destination) of a movement. ```typescript type MovementSideView = { locationLabel: string locationColors: BadgeColors statusLabel: string statusColors: BadgeColors } ``` ### `MoveSparePartModalProps` Props for `MoveSparePartModal`. ```typescript type MoveSparePartModalProps = { isOpen?: boolean; onClose?: VoidFunction; sparePart?: MoveSparePartModalSparePart; requestedValues?: { location?: string; status?: string }; locationOptions: FormSelectOption[]; statusOptions: FormSelectOption[]; onSubmit: ( values: { lo… ``` ### `MoveSparePartModalSparePart` A spare part being moved: its display attributes plus current location and status. ```typescript type MoveSparePartModalSparePart = SparePartDetailsRecord & { id: string; location: string; status: string; } ``` ### `MultiLevelSelectRootProps` ```typescript type MultiLevelSelectRootProps = ComponentPropsWithoutRef<typeof SelectPrimitive.Root> & { /** * Show a clear button when a value is selected * @default false */ allowClear?: boolean } ``` ### `MultiLevelSelectSectionProps` ```typescript type MultiLevelSelectSectionProps = { open?: boolean children?: ReactNode defaultOpen?: boolean sectionTitle: ReactNode onToggle?: (open: boolean) => void } ``` ### `MultiLevelSelectTriggerProps` ```typescript type MultiLevelSelectTriggerProps = ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> & { /** * Size of the select trigger * - `sm`: Small (32px height) * - `md`: Medium (36px height) * - `lg`: Large/Big (40px height) * @default 'lg' */ size?: SelectSize /** * Visual… ``` ### `MultiSelectOption` ```typescript type MultiSelectOption = { value: string label: ReactNode disabled?: boolean } ``` ### `MultiSelectProps` ```typescript type MultiSelectProps = { options: MultiSelectOption[] /** Controlled selected values. Omit to use `defaultValue` for uncontrolled mode. */ value?: string[] /** Initial values for uncontrolled mode. Ignored when `value` is provided. */ defaultValue?: string[] onV… ``` ### `MultiSelectSize` ```typescript type MultiSelectSize = 'sm' | 'md' | 'lg' ``` ### `MultiSelectVariant` ```typescript type MultiSelectVariant = 'default' | 'colored' ``` ### `NavigationBlockItem` ```typescript type NavigationBlockItem = { icon: ReactNode title: string description: string navText: string url: string } ``` ### `NotFoundPageProps` ```typescript type NotFoundPageProps = { /** * Callback fired when the "Go Home" button is clicked */ onGoHome?: VoidFunction /** * Page title * @default "404" */ title?: string /** * Message displayed below the title * @default "The page you are looking for does not exist." */… ``` ### `NotificationOptions` ```typescript type NotificationOptions = { /** * Duration in milliseconds (0 = no auto-close) * @default 3000 */ duration?: number /** * Toast position on screen * @default 'top-left' */ position?: ToastPosition /** * Prevent auto-close (keeps toast open until manually closed) *… ``` ### `NotificationVariant` Toast/notification variant options ```typescript type NotificationVariant = 'success' | 'error' | 'warning' | 'info' ``` ### `Nullable` ```typescript type Nullable = T | null ``` ### `OilTempThresholds` ```typescript type OilTempThresholds = { COLD: number LIGHT_WARM: number WARM: number HOT: number SUPERHOT?: number [key: string]: unknown } ``` ### `OperationalDashboardChartId` ```typescript type OperationalDashboardChartId = (typeof OPERATIONAL_DASHBOARD_CHART_IDS)[keyof typeof OPERATIONAL_DASHBOARD_CHART_IDS] ``` ### `OperationalDashboardMinersInput` ```typescript type OperationalDashboardMinersInput = Pick< OperationalMinersStatusChartProps, 'data' | 'isLoading' > ``` ### `OperationalDashboardProps` Props for the operational dashboard composite. ```typescript type OperationalDashboardProps = Partial<{ hashrate: OperationalDashboardTrendInput consumption: OperationalDashboardTrendInput efficiency: OperationalDashboardTrendInput miners: OperationalDashboardMinersInput /** Optional controls (e.g. a date-range picker) rendered abo… ``` ### `OperationalDashboardTrendInput` Data props for one card on the composite (expand state is owned internally). ```typescript type OperationalDashboardTrendInput = Pick<OperationalTrendChartProps, 'data' | 'isLoading'> ``` ### `OperationalMinersStatusChartProps` Props for the miners-status chart component. ```typescript type OperationalMinersStatusChartProps = Partial<{ data: MinersStatusChartData isLoading: boolean isExpanded: boolean onToggleExpand: VoidFunction }> ``` ### `OperationalTrendChartProps` Shared props for the three line-trend chart components. ```typescript type OperationalTrendChartProps = Partial<{ data: LineChartCardData isLoading: boolean isExpanded: boolean onToggleExpand: VoidFunction }> ``` ### `OperationsEfficiencyMinerTypeInput` ```typescript type OperationsEfficiencyMinerTypeInput = { tailLog?: EfficiencyMinerTypeTailLog | null } ``` ### `OperationsEfficiencyMinerTypeResult` ```typescript type OperationsEfficiencyMinerTypeResult = { chartInput: ToBarChartDataInput isEmpty: boolean } ``` ### `OperationsEfficiencyMinerUnitInput` ```typescript type OperationsEfficiencyMinerUnitInput = { tailLog?: EfficiencyMinerUnitTailLog | null containers?: Container[] } ``` ### `OperationsEfficiencyMinerUnitResult` ```typescript type OperationsEfficiencyMinerUnitResult = { chartInput: ToBarChartDataInput isEmpty: boolean } ``` ### `OperationsEfficiencyProps` ```typescript type OperationsEfficiencyProps = { defaultTab?: EfficiencyTabValue siteView?: EfficiencySiteViewProps minerTypeView?: EfficiencyMinerTypeViewProps minerUnitView?: EfficiencyMinerUnitViewProps } ``` ### `OperationsEnergyChartProps` ```typescript type OperationsEnergyChartProps = { totals: CostSummaryMonetaryTotals | null isLoading?: boolean } ``` ### `OperationsEnergyCostChartData` ```typescript type OperationsEnergyCostChartData = Partial<{ energyCostsUSD: number operationalCostsUSD: number }> ``` ### `OperationsEnergyCostChartProps` ```typescript type OperationsEnergyCostChartProps = Partial<{ title: string unit: string height: number className: string isLoading: boolean emptyMessage: string data: OperationsEnergyCostChartData }> ``` ### `OperationsMinersInput` DI input for the stacked miners-status chart. ```typescript type OperationsMinersInput = Partial<{ log: ReadonlyArray<OperationsMinersStatusPoint> isLoading: boolean error: unknown }> ``` ### `OperationsMinersStatusPoint` Per-day miner status counts, already aggregated by the data layer. ```typescript type OperationsMinersStatusPoint = { ts: number online: number error: number offline: number sleep: number maintenance: number } ``` ### `OperationsMinersViewModel` View-model for the miners-status chart (hook output). ```typescript type OperationsMinersViewModel = { data: MinersStatusChartData isLoading: boolean error: unknown } ``` ### `OperationsTrendInput` DI input for one of the three line-trend charts. ```typescript type OperationsTrendInput = Partial<{ /** Raw metric buckets ordered by time. */ log: ReadonlyArray<OperationsTrendPoint> /** Nominal/reference value in the same base unit; renders a flat reference line. */ nominalValue: number | null isLoading: boolean error: unknow… ``` ### `OperationsTrendPoint` A single timestamped sample of one operational metric (base unit). ```typescript type OperationsTrendPoint = { /** Bucket timestamp in epoch ms. */ ts: number /** Value in its base unit (hashrate: MH/s, power: W, efficiency: W/TH/s). */ value: number } ``` ### `OperationsTrendViewModel` View-model for one line-trend chart (hook output). ```typescript type OperationsTrendViewModel = { data: LineChartCardData isLoading: boolean error: unknown } ``` ### `Optional` ```typescript type Optional = T | undefined ``` ### `OsTypeKey` ```typescript type OsTypeKey = keyof typeof OsTypes ``` ### `OsTypeValue` ```typescript type OsTypeValue = (typeof OsTypes)[OsTypeKey] ``` ### `OverviewChartResult` ```typescript type OverviewChartResult = { yTicksFormatter: (value: number) => string timeRange: TimeRangeType | null datasets: ChartDataset[] } ``` ### `PaginatedResponse` ```typescript type PaginatedResponse = { data: T[] page: number total: number totalPages: number } ``` ### `PaginationParams` ```typescript type PaginationParams = { limit?: number offset?: number page?: number } ``` ### `PaginationProps` ```typescript type PaginationProps = { /** * Current active page number */ current?: number /** * Total number of items */ total?: number /** * Number of items per page * @default 20 */ pageSize?: number /** * Page size options for the select dropdown * @default [10, 20, 50,… ``` ### `ParameterSetting` ```typescript type ParameterSetting = { name: string value?: number | string suffix?: string type?: 'number' | 'string' } ``` ### `ParameterSettings` ```typescript type ParameterSettings = Record<string, ParameterSetting> ``` ### `ParsedAlertEntry` ```typescript type ParsedAlertEntry = { shortCode: string device: string tags: string[] alertName: string alertCode: string severity: string description?: string message?: string createdAt: string | number status?: string uuid: string id?: string type?: string actions: AlertAc… ``` ### `Pdu` ```typescript type Pdu = { pdu: string power_w?: number | string current_a?: number | string sockets?: PduSocket[] offline?: boolean } ``` ### `PduSocket` ```typescript type PduSocket = { socket: string | number enabled: boolean cooling?: boolean } ``` ### `PendingActionLike` The fields of a staged `actionsStore` submission the tray needs to render a human-readable summary. Mirrors the pool-action payloads enqueued by the add/edit/assign modals. ```typescript type PendingActionLike = { id?: number action?: string params?: Array<{ data?: { poolConfigName?: string /** Pool stratum URLs — present on create/update pool-config actions. */ poolUrls?: Array<{ url?: string }> } poolConfigId?: string configType?: string }> quer… ``` ### `PendingActionsButtonProps` ```typescript type PendingActionsButtonProps = { /** Click handler override — defaults to toggling the actionsStore sidebar. */ onClick?: (event: MouseEvent<HTMLButtonElement>) => void className?: string } ``` ### `PendingSubmission` ```typescript type PendingSubmission = { id: string | number action: string tags: string[] params: unknown[] [key: string]: unknown } ``` ### `PeriodKey` ```typescript type PeriodKey = keyof typeof PERIOD ``` ### `PeriodValue` ```typescript type PeriodValue = (typeof PERIOD)[PeriodKey] ``` ### `PollingIntervalType` ```typescript type PollingIntervalType = | typeof POLLING_5s | typeof POLLING_1m | typeof POLLING_2m | typeof POLLING_10s | typeof POLLING_15s | typeof POLLING_20s | typeof POLLING_30s ``` ### `PoolConfigData` Structurally identical to `PoolConfigEntry` from `@tetherto/mdk-ui-foundation`. Aliased here so consumers import from `@tetherto/mdk-react-devkit` without reaching into the core layer. ```typescript type PoolConfigData = PoolConfigEntry ``` ### `PoolDetailItem` ```typescript type PoolDetailItem = { title: string value?: string | number } ``` ### `PoolDetailsCardProps` ```typescript type PoolDetailsCardProps = PoolDetailsCardPartialProps & { details: PoolDetailItem[] } ``` ### `PoolEndpoint` ```typescript type PoolEndpoint = { role?: string host: string port: string pool: string url?: string } ``` ### `PoolEndpointFormValues` ```typescript type PoolEndpointFormValues = Omit<PoolEndpoint, 'role' | 'region'> ``` ### `PoolManagerMinerExplorerProps` ```typescript type PoolManagerMinerExplorerProps = { /** Miners to render in the explorer table. */ miners: ListThingsDevice[] /** Pool configurations powering the "Assign Pool" dropdown. */ poolConfig: PoolConfigData[] /** Called when the operator clicks the "Pool Manager" back link. */ b… ``` ### `PoolManagerPoolsProps` ```typescript type PoolManagerPoolsProps = { /** Array of pool configurations to render. */ poolConfig: PoolConfigData[] /** Called when the operator clicks the "Pool Manager" back link. */ backButtonClick: VoidFunction } ``` ### `PoolManagerProps` ```typescript type PoolManagerProps = { /** Pool configurations shared by every sub-view (Pools, Miner Explorer, Sites). */ poolConfig: PoolConfigData[] /** Dashboard site-level stat blocks. */ stats?: DashboardStats /** Dashboard stats loading flag. */ isStatsLoading?: boolea… ``` ### `PoolManagerSiteOverviewDetailsProps` ```typescript type PoolManagerSiteOverviewDetailsProps = { /** The site (container unit) to render details for. */ unit: UnitData /** Display name shown in the breadcrumb (`Site Overview / <unitName>`). */ unitName: string /** Pool configurations powering the per-pool detail rows. */ poolConfig:… ``` ### `PoolManagerSitesOverviewProps` ```typescript type PoolManagerSitesOverviewProps = { /** Sites to render (already normalised through `useSitesOverviewData`). */ units: ProcessedContainerUnit[] /** Pool configurations powering each card's pool summary. */ poolConfig: PoolConfigData[] /** Show a skeleton placeholder while… ``` ### `PoolManagerView` Internal surfaces the wrapper switches between on a single route. ```typescript type PoolManagerView = | 'dashboard' | 'pools' | 'sites-overview' | 'miner-explorer' | 'site-detail' ``` ### `PoolSummary` ```typescript type PoolSummary = { id: string name: string description: string units: number miners: number workerName: string | undefined workerPassword: string | undefined endpoints: PoolEndpoint[] validation?: { status: string } credentialsTemplate?: Partial<PoolCreden… ``` ### `PosHistoryEntry` ```typescript type PosHistoryEntry = { container: string pos: string removedAt: number } ``` ### `Position` Position/side options for UI elements Used by Tooltip, Popover, and chart legends ```typescript type Position = 'top' | 'right' | 'bottom' | 'left' ``` ### `PositionChangeDialogFlowKey` ```typescript type PositionChangeDialogFlowKey = keyof typeof POSITION_CHANGE_DIALOG_FLOWS ``` ### `PositionChangeDialogFlowValue` ```typescript type PositionChangeDialogFlowValue = (typeof POSITION_CHANGE_DIALOG_FLOWS)[PositionChangeDialogFlowKey] ``` ### `PowerMeter` ```typescript type PowerMeter = { last?: { snap?: { stats?: { power_w?: number } } } } ``` ### `PowerModeTableRow` ```typescript type PowerModeTableRow = { minerType: string count: number power: string [mode: string]: string | number } ``` ### `PowerModeTimelineChartData` ```typescript type PowerModeTimelineChartData = { labels: string[] datasets: PowerModeTimelineDataset[] } ``` ### `PowerModeTimelineChartProps` Props for `PowerModeTimelineChart`. ```typescript type PowerModeTimelineChartProps = Partial<{ /** Initial power-mode entries (each with start/end ts + mode). */ data: PowerModeTimelineEntry[] /** Streaming updates appended to the initial data. */ dataUpdates: PowerModeTimelineEntry[] /** Show a loading skeleton instead of… ``` ### `PowerModeTimelineDataset` ```typescript type PowerModeTimelineDataset = { label: string data: Array<{ x: [number, number]; y: string | undefined }> color: string } ``` ### `PowerModeTimelineEntry` ```typescript type PowerModeTimelineEntry = { ts?: number power_mode_group_aggr?: Record<string, string> status_group_aggr?: Record<string, string> [key: string]: unknown } ``` ### `PresetItem` ```typescript type PresetItem = { label: string value: DateRange } ``` ### `PressureThresholds` ```typescript type PressureThresholds = { CRITICAL_LOW: number MEDIUM_LOW: number NORMAL?: number MEDIUM_HIGH: number CRITICAL_HIGH: number [key: string]: unknown } ``` ### `ProductionCostChartProps` ```typescript type ProductionCostChartProps = { costLog: ReadonlyArray<CostTimeSeriesEntry> btcPriceLog: ReadonlyArray<BtcPriceTimeSeriesEntry> dateRange: FinancialDateRange | null isLoading?: boolean } ``` ### `ProfileMenuItem` ```typescript type ProfileMenuItem = { label: string onSelect: () => void /** Render as a destructive action (red). */ danger?: boolean /** Optional leading icon. */ icon?: ReactNode /** Optional secondary line under the label (e.g. "Current: Europe/Podgorica"). */ descriptio… ``` ### `ProfileMenuProps` ```typescript type ProfileMenuProps = { /** Items rendered in the dropdown, top-to-bottom. Defaults to a single "Sign out" item. */ items: ProfileMenuItem[] /** Optional user label rendered at the top of the dropdown (e.g. an email). */ user?: ReactNode /** Override the trigge… ``` ### `PumpItem` ```typescript type PumpItem = { enabled?: boolean index: number } ``` ### `RadioGroupProps` ```typescript type RadioGroupProps = { /** * Layout orientation * @default 'vertical' */ orientation?: 'horizontal' | 'vertical' /** * Remove gap between radio items * @default false */ noGap?: boolean /** * Custom className for the group */ className?: string } & ComponentPr… ``` ### `RadioProps` ```typescript type RadioProps = { /** * Size variant of the radio * @default 'md' */ size?: ComponentSize /** * Color variant when checked * @default 'default' */ color?: ComponentColor /** * Border radius variant (full makes it circular) * @default 'full' */ radius?: Bo… ``` ### `RangeKey` ```typescript type RangeKey = keyof typeof RANGES ``` ### `RangeSelectorOption` ```typescript type RangeSelectorOption = { label: string value: string } ``` ### `RangeSelectorProps` ```typescript type RangeSelectorProps = { options: RangeSelectorOption[] value: string onChange: (value: string) => void className?: string style?: CSSProperties buttonClassName?: string } ``` ### `RangeValue` ```typescript type RangeValue = (typeof RANGES)[RangeKey] ``` ### `RawCsvRow` ```typescript type RawCsvRow = { part: string; model: string; "miner model": string; "serial num": string; mac: string; status: string; location: string; comment: string; } ``` ### `RBACControlSettingsProps` ```typescript type RBACControlSettingsProps = { users: SettingsUser[] roles: RoleOption[] rolePermissions: Record<string, Record<string, PermLevel>> permissionLabels: Record<string, string> canWrite: boolean isLoading?: boolean onCreateUser: (data: { name: string; email: string; role:… ``` ### `RepairAction` A single repair action within a batch. `params[0]` carries the part-change payload. ```typescript type RepairAction = Partial<{ params: RepairActionParam[] }> ``` ### `RepairActionParam` Shape of a single inner repair action recorded inside a batch action. `params[0]` holds the part-change payload the sub-row reads. ```typescript type RepairActionParam = Partial<{ comment: string id: string rackId: string info: { parentDeviceId: string | null } }> ``` ### `RepairBatchAction` A repair batch action. Its `params` are the individual repair actions (part swaps, comments, etc.) grouped under one log entry. ```typescript type RepairBatchAction = Partial<{ params: RepairAction[] }> ``` ### `RepairDevice` Minimal device record consumed by `RepairLogChangesSubRow`. The parent fetches these (e.g. via the things API) and passes them in as props. ```typescript type RepairDevice = Partial<{ id: string rack: string info: Partial<{ serialNum: string macAddress: string }> }> ``` ### `RepairLogChangesSubRowProps` ```typescript type RepairLogChangesSubRowProps = { /** * The repair batch action whose part changes should be displayed. */ batchAction: RepairBatchAction /** * Devices referenced by the batch action, pre-fetched by the parent. */ devices: RepairDevice[] /** * Show a spinner while the pa… ``` ### `ReportTimeFrameSelectorProps` ```typescript type ReportTimeFrameSelectorProps = Pick< ReportTimeFrameSelectorState, 'presetTimeFrame' | 'dateRange' | 'setPresetTimeFrame' | 'setDateRange' > ``` ### `ReportTimeFrameSelectorState` ```typescript type ReportTimeFrameSelectorState = { start: Date end: Date presetTimeFrame: number | null dateRange: [Date, Date] setPresetTimeFrame: (value: number | null) => void setDateRange: (value: [Date, Date]) => void } ``` ### `RequireAuthProps` ```typescript type RequireAuthProps = { /** Rendered when a token is present. */ children: ReactNode /** Rendered when no token is present — typically `<Navigate to="/signin" />`. */ fallback: ReactNode /** * When true (default), the current location is persisted to sessionSto… ``` ### `ResponseCodeKey` ```typescript type ResponseCodeKey = keyof typeof RESPONSE_CODE ``` ### `ResponseCodeValue` ```typescript type ResponseCodeValue = (typeof RESPONSE_CODE)[ResponseCodeKey] ``` ### `RevenueChartProps` Props for `RevenueChart`; pass pre-fetched data and optional legend layout overrides. ```typescript type RevenueChartProps = Partial<{ data: RevenueDataItem[] isLoading: boolean siteList: (string | SiteItem)[] legendPosition: Position legendAlign: 'start' | 'center' | 'end' }> ``` ### `RevenueChartViewModel` ```typescript type RevenueChartViewModel = { /** Chart-ready series input — pass to `toBarChartData` in the component layer. */ chartInput: ToBarChartDataInput /** Resolved display unit: `'₿'` (BTC) or `'Sats'` depending on value scale. */ currencyUnit: string } ``` ### `RevenueDataItem` A single time-period revenue record; reserved keys plus one numeric value per site ID. ```typescript type RevenueDataItem = { timeKey: string period: string timestamp: number [key: string]: unknown } ``` ### `RevenueMultiplierKey` ```typescript type RevenueMultiplierKey = keyof typeof REVENUE_MULTIPLIER ``` ### `RevenueSummaryLogEntry` ```typescript type RevenueSummaryLogEntry = { ts: number revenueBTC: number feesBTC: number revenueUSD: number feesUSD: number btcPrice: number powerW: number consumptionMWh: number hashrateMhs: number energyCostsUSD: number operationalCostsUSD: number totalCostsUSD: number ebitdaSe… ``` ### `RevenueSummaryResponse` ```typescript type RevenueSummaryResponse = FinanceResponse<RevenueSummaryLogEntry, RevenueSummaryTotals> ``` ### `RevenueSummaryTotals` ```typescript type RevenueSummaryTotals = { totalRevenueBTC: number totalRevenueUSD: number totalFeesBTC: number totalFeesUSD: number totalCostsUSD: number totalConsumptionMWh: number avgCostPerMWh: number | null avgRevenuePerMWh: number | null avgBtcPrice: number | null avgCurtai… ``` ### `RgbColor` ```typescript type RgbColor = { r: number; g: number; b: number } ``` ### `RouteKey` ```typescript type RouteKey = keyof typeof ROUTE ``` ### `RouteTitleKey` ```typescript type RouteTitleKey = keyof typeof ROUTE_TITLES_MAP ``` ### `RouteTitleValue` ```typescript type RouteTitleValue = (typeof ROUTE_TITLES_MAP)[RouteTitleKey] ``` ### `RouteValue` ```typescript type RouteValue = (typeof ROUTE)[RouteKey] ``` ### `SecondaryLabel` ```typescript type SecondaryLabel = { title: string value: string | number } ``` ### `SelectProps` ```typescript type SelectProps = ComponentPropsWithoutRef<typeof SelectPrimitive.Root> & { /** * Show a clear button when a value is selected * @default false */ allowClear?: boolean } ``` ### `SelectSize` ```typescript type SelectSize = 'sm' | 'md' | 'lg' ``` ### `SelectTriggerProps` ```typescript type SelectTriggerProps = ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> & { /** * Size of the select trigger * - `sm`: Small (32px height) * - `md`: Medium (36px height) * - `lg`: Large/Big (40px height) * @default 'lg' */ size?: SelectSize /** * Visual… ``` ### `SelectVariant` ```typescript type SelectVariant = 'default' | 'colored' ``` ### `SettingsDashboardProps` ```typescript type SettingsDashboardProps = { dangerActions?: ActionButtonProps[] headerControlsProps?: HeaderControlsSettingsProps rbacControlProps?: RBACControlSettingsProps importExportProps?: ImportExportSettingsProps featureFlagsProps?: FeatureFlagsSettingsProps showFeatureFlag… ``` ### `SeverityColorKey` ```typescript type SeverityColorKey = keyof typeof SEVERITY_COLORS ``` ### `SeverityKey` ```typescript type SeverityKey = keyof typeof SEVERITY ``` ### `SeverityLevelKey` ```typescript type SeverityLevelKey = keyof typeof SEVERITY_LEVELS ``` ### `SeverityLevelValue` ```typescript type SeverityLevelValue = (typeof SEVERITY_LEVELS)[SeverityLevelKey] ``` ### `SeverityValue` ```typescript type SeverityValue = (typeof SEVERITY)[SeverityKey] ``` ### `SidebarCallbacks` ```typescript type SidebarCallbacks = Partial<{ onClose: VoidFunction onExpandedChange: (expanded: boolean) => void onItemClick: (item: SidebarMenuItem) => void }> ``` ### `SidebarMenuItem` ```typescript type SidebarMenuItem = SidebarMenuItemBase & SidebarMenuItemOptions ``` ### `SidebarMenuItemBase` ```typescript type SidebarMenuItemBase = { id: string label: string } ``` ### `SidebarMenuItemOptions` ```typescript type SidebarMenuItemOptions = Partial<{ disabled: boolean icon: React.ReactNode items: SidebarMenuItem[] }> ``` ### `SidebarOptions` ```typescript type SidebarOptions = Partial<{ activeId: string expanded: boolean visible: boolean overlay: boolean className: string defaultExpanded: boolean header: React.ReactNode }> ``` ### `SidebarProps` ```typescript type SidebarProps = SidebarOptions & SidebarCallbacks & { items: SidebarMenuItem[] } ``` ### `SignInGoogleButtonProps` ```typescript type SignInGoogleButtonProps = Omit<ButtonProps, 'onClick' | 'children'> & { /** * Base URL of the OAuth backend (no trailing slash). Click navigates to * `${oauthBaseUrl}/oauth/google`. */ oauthBaseUrl: string /** Override the visible button label. */ label?: string /*… ``` ### `SingleStatCardVariant` ```typescript type SingleStatCardVariant = 'primary' | 'secondary' | 'tertiary' | 'highlighted' ``` ### `SiteItem` A site reference used to resolve site IDs in the data to display names. ```typescript type SiteItem = { id: string name?: string } ``` ### `SiteOverviewDetailsDataOptions` ```typescript type SiteOverviewDetailsDataOptions = { pdus?: Pdu[] connectedMiners?: ListThingsDevice[] connectedMinersData?: Partial<ContainerInfo[]> containerHashRate?: string actualMinersCount?: number isLoading?: boolean } ``` ### `SitePowerConsumptionSlice` ```typescript type SitePowerConsumptionSlice = { data: Array<{ ts: number; consumption: number }> nominalValue: number | null isLoading: boolean error?: unknown } ``` ### `SiteStatsBarProps` ```typescript type SiteStatsBarProps = { /** Site label rendered in the header row. */ title: string /** Current site-level power consumption, in watts (or whatever `powerUnit` says). */ power?: number /** Display unit for `power` — defaults to `kW`. */ powerUnit?: string /** A… ``` ### `SkeletonBlockProps` ```typescript type SkeletonBlockProps = Partial<{ circle: boolean className: string width: number | string height: number | string borderRadius: number | string }> ``` ### `SocketBorderColorKey` ```typescript type SocketBorderColorKey = keyof typeof SOCKET_BORDER_COLOR ``` ### `SocketProps` ```typescript type SocketProps = { /** Current in amperes */ current_a?: number | null /** Power in watts */ power_w?: number | null /** Whether socket is enabled */ enabled?: boolean /** Socket number/index */ socket?: number | null /** Whether socket is selected */ sele… ``` ### `SparePartDetailsRecord` A spare part's display attributes, rendered by `SparePartDetails`. Extra keys are allowed. ```typescript type SparePartDetailsRecord = { code?: string; type?: string; site?: string; serialNum?: string; macAddress?: string; [key: string]: unknown; } ``` ### `SparePartSubTypesModalPartType` A selectable part type shown as a tab in the subtypes modal. ```typescript type SparePartSubTypesModalPartType = { value: string; label: string; } ``` ### `SparePartSubTypesModalProps` Props for `SparePartSubTypesModal`; the active part type is controlled by the caller. ```typescript type SparePartSubTypesModalProps = { isOpen: boolean; onClose: VoidFunction; partTypes: SparePartSubTypesModalPartType[]; activePartTypeId: string; onPartTypeChange: (id: string) => void; subTypes: string[]; onAddSubType: (name: string) => Promise<{ error?: string } | void>… ``` ### `SpinnerProps` ```typescript type SpinnerProps = { /** * Size variant of the spinner * @default 'md' */ size?: ComponentSize /** * Color variant of the spinner * @default 'primary' */ color?: 'primary' | 'secondary' /** * Whether to display in fullscreen mode * @default false */ fullScre… ``` ### `StagingEnvType` ```typescript type StagingEnvType = typeof STAGING_ENV ``` ### `StatItem` ```typescript type StatItem = { name?: string value?: number | string unit?: string } ``` ### `StatItemType` ```typescript type StatItemType = 'ERROR' | 'SUCCESS' ``` ### `StatKey` ```typescript type StatKey = typeof STAT_REALTIME | typeof STAT_5_MINUTES | typeof STAT_3_HOURS ``` ### `StatsFrequencyMhz` ```typescript type StatsFrequencyMhz = { avg: number chips: ChipData[] [key: string]: unknown } ``` ### `StatsTemperatureC` ```typescript type StatsTemperatureC = { avg: number min: number max: number chips: TempChipData[] [key: string]: unknown } ``` ### `Status` ```typescript type Status = 'idle' | 'loading' | 'success' | 'error' ``` ### `StatusVariant` Status variants for state indication Used for badges, notifications, and status indicators ```typescript type StatusVariant = 'success' | 'processing' | 'error' | 'warning' | 'default' | 'idle' ``` ### `SubsidyFeesLogEntry` ```typescript type SubsidyFeesLogEntry = { ts: number blockReward: number blockTotalFees: number avgFeesSatsVByte?: number | null } ``` ### `SubsidyFeesResponse` ```typescript type SubsidyFeesResponse = FinanceResponse<SubsidyFeesLogEntry, SubsidyFeesTotals> ``` ### `SubsidyFeesTotals` ```typescript type SubsidyFeesTotals = { totalBlockReward: number totalBlockTotalFees: number avgBlockReward: number | null avgBlockTotalFees: number | null } ``` ### `SupplyLiquidBoxContainerSettings` ```typescript type SupplyLiquidBoxContainerSettings = { thresholds?: Record<string, UnknownRecord> } ``` ### `SupplyLiquidBoxProps` ```typescript type SupplyLiquidBoxProps = { data?: Device containerSettings?: SupplyLiquidBoxContainerSettings | null } ``` ### `SwitchProps` ```typescript type SwitchProps = { /** * Size variant of the switch * @default 'md' */ size?: ComponentSize /** * Color variant when checked * @default 'default' */ color?: ComponentColor /** * Border radius variant * @default 'none' */ radius?: BorderRadius /** * Custom… ``` ### `TableColorKey` ```typescript type TableColorKey = keyof typeof TABLE_COLORS ``` ### `TagFilterBarProps` ```typescript type TagFilterBarProps = { filterTags: string[] localFilters: AlertLocalFilters onSearchTagsChange: (tags: string[]) => void onLocalFiltersChange: (filters: AlertLocalFilters) => void /** * Site-specific overrides for the "type" filter children. * If provided, the… ``` ### `TagInputDropdownProps` ```typescript type TagInputDropdownProps = { /** Filtered options to display */ filteredOptions: TagInputOption[] /** Current tags (selected values) - use to show selected state in custom dropdown */ selectedTags: string[] /** Index of the currently highlighted option (for keyboard… ``` ### `TagInputOption` ```typescript type TagInputOption = string | { value: string; label: string; disabled?: boolean } ``` ### `TagInputProps` ```typescript type TagInputProps = { /** * Controlled tags (array of tag values) */ value?: string[] /** * Callback when tags change (add/remove) */ onTagsChange?: (tags: string[]) => void /** * Callback when input value changes (typing). Receives current input value. Usefu… ``` ### `TagInputRef` ```typescript type TagInputRef = { /** Clear the input value programmatically */ clearInputValue: VoidFunction /** Focus the input */ focus: VoidFunction /** Blur the input */ blur: VoidFunction /** Get current input value */ getInputValue: () => string } ``` ### `TagProps` ```typescript type TagProps = { /** * Color variant of the tag * @default 'dark' */ color?: 'dark' | 'red' | 'green' | 'amber' | 'blue' /** * Custom className for the root element */ className?: string /** * Children content */ children?: ReactNode } & ComponentPropsWi… ``` ### `Tank` ```typescript type Tank = { cold_temp_c: number enabled: boolean color?: string flash?: boolean tooltip?: string } ``` ### `TankRowPressure` ```typescript type TankRowPressure = Partial<{ value: number flash: boolean color: string tooltip: string }> ``` ### `TankRowProps` ```typescript type TankRowProps = { label: string temperature: number unit: string oilPumpEnabled: boolean waterPumpEnabled: boolean color: string flash?: boolean tooltip?: string pressure: TankRowPressure } ``` ### `TanksBoxPressure` ```typescript type TanksBoxPressure = { value?: number flash?: boolean color?: string tooltip?: string } ``` ### `TanksBoxProps` ```typescript type TanksBoxProps = { data?: { oil_pump: Tank[] water_pump: WaterPump[] pressure: TanksBoxPressure[] } } ``` ### `TempChipData` ```typescript type TempChipData = { index: number max?: number min?: number avg?: number } ``` ### `TemperatureColorKey` ```typescript type TemperatureColorKey = keyof typeof TEMPERATURE_COLORS ``` ### `TextAlign` Text alignment options Used by Typography component ```typescript type TextAlign = 'left' | 'center' | 'right' | 'justify' ``` ### `TextAreaProps` ```typescript type TextAreaProps = ComponentProps<'textarea'> & { /** * Optional label displayed above the textarea */ label?: string /** * HTML id for the textarea. Required when using label for accessibility. */ id?: string /** * Validation error message. When provided, d… ``` ### `Theme` ```typescript type Theme = 'light' | 'dark' | 'system' ``` ### `ThemeConfig` ```typescript type ThemeConfig = { defaultTheme?: Theme storageKey?: string } ``` ### `ThingActionValue` ```typescript type ThingActionValue = (typeof THING_ACTIONS)[number] ``` ### `ThresholdBarChartInput` ```typescript type ThresholdBarChartInput = { labels: string[] series: Array<{ label: string values: number[] color?: string stack?: string }> } ``` ### `ThresholdLineChartData` ```typescript type ThresholdLineChartData = { series: ThresholdLineChartSeries[] thresholds?: ThresholdLineChartThreshold[] } ``` ### `ThresholdLineChartInput` ```typescript type ThresholdLineChartInput = { series: Array<{ label: string points: Array<{ ts: number; value: number }> color?: string }> constants?: Array<{ label: string value: number color?: string style?: { borderDash?: number[] } }> } ``` ### `ThresholdLineChartPoint` ```typescript type ThresholdLineChartPoint = { value: number timestamp: string | number } ``` ### `ThresholdLineChartProps` ```typescript type ThresholdLineChartProps = Partial<{ title: string unit: string height: number /** When true, uses a taller default height (360px). */ isTall: boolean className: string emptyMessage: string isLegendVisible: boolean data: ThresholdLineChartData yTicksFormatter: (valu… ``` ### `ThresholdLineChartSeries` ```typescript type ThresholdLineChartSeries = { label: string color?: string fill?: boolean points: ThresholdLineChartPoint[] } ``` ### `ThresholdLineChartThreshold` ```typescript type ThresholdLineChartThreshold = { label: string value: number color?: string } ``` ### `TimeFormatType` ```typescript type TimeFormatType = typeof TIME_FORMAT ``` ### `TimeframeControlsDateRange` ```typescript type TimeframeControlsDateRange = { start: number end: number } ``` ### `TimeframeControlsOnRangeChange` ```typescript type TimeframeControlsOnRangeChange = ( range: [Date, Date], options: Partial<{ year: number; month: number; period: string }>, ) => void ``` ### `TimeframeControlsProps` ```typescript type TimeframeControlsProps = Partial<{ hint: string onReset: VoidFunction showResetButton: boolean isWeekSelectVisible: boolean isMonthSelectVisible: boolean layout: 'horizontal' | 'stacked' dateRange: TimeframeControlsDateRange timeframeType: TimeframeTypeValue | nul… ``` ### `TimeframeTypeKey` ```typescript type TimeframeTypeKey = keyof typeof TIMEFRAME_TYPE ``` ### `TimeframeTypeValue` ```typescript type TimeframeTypeValue = (typeof TIMEFRAME_TYPE)[TimeframeTypeKey] ``` ### `TimeframeWeekFlatContentProps` ```typescript type TimeframeWeekFlatContentProps = { visibleWeeks: ReturnType<typeof weeksOfMonth> } ``` ### `TimeframeWeekTreeContentProps` ```typescript type TimeframeWeekTreeContentProps = { timezone: string selectedYear: number selectedMonth: number } ``` ### `TimeInterval` ```typescript type TimeInterval = { start: number end: number } ``` ### `TimeKey` ```typescript type TimeKey = keyof typeof TIME ``` ### `TimelineChartData` ```typescript type TimelineChartData = { labels: string[] datasets: TimelineChartDataset[] } ``` ### `TimelineChartDataPoint` ```typescript type TimelineChartDataPoint = { x: [number, number] y: string | undefined } ``` ### `TimelineChartDataset` ```typescript type TimelineChartDataset = { label: string data: TimelineChartDataPoint[] borderColor?: string[] backgroundColor?: string[] color?: string } ``` ### `TimelineChartProps` ```typescript type TimelineChartProps = { initialData: TimelineChartData newData?: TimelineChartData skipUpdates?: boolean range?: ChartRange axisTitleText?: AxisTitleText isLoading?: boolean title?: string height?: number } ``` ### `TimelineItemData` ```typescript type TimelineItemData = { item: AlarmItemData dot: ReactNode children: ReactNode } ``` ### `TimelineOption` ```typescript type TimelineOption = { value: string label: string disabled?: boolean } ``` ### `TimelineSelectorProps` ```typescript type TimelineSelectorProps = { /** Currently selected timeline value (e.g. `'1m'`, `'5m'`). */ value: string /** Called whenever the user picks a new option. */ onChange: (next: string) => void /** * Available options — defaults to {@link getTimelineOptions}. Pass a c… ``` ### `TimeRangeFormatted` ```typescript type TimeRangeFormatted = { start: string end: string formatted: string } ``` ### `TimeRangeType` ```typescript type TimeRangeType = (typeof TimeRangeTypes)[keyof typeof TimeRangeTypes] ``` ### `TimeSelection` ```typescript type TimeSelection = { end: Date start: Date year: number month?: number label?: string } ``` ### `TIncidentRowProps` ```typescript type TIncidentRowProps = { id: string title: string body: string subtitle: string severity: TIncidentSeverity onClick?: (id: string) => void } ``` ### `ToastPosition` ```typescript type ToastPosition = | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center' ``` ### `ToastVariant` ```typescript type ToastVariant = NotificationVariant ``` ### `TransactionEntry` ```typescript type TransactionEntry = { changed_balance?: number satoshis_net_earned?: number fees_colected_satoshis?: number mining_extra?: { tx_fee?: number } } ``` ### `TransactionSum` ```typescript type TransactionSum = { revenueBTC: number feesBTC: number } ``` ### `TypographyColor` Typography color options (includes muted variant) ```typescript type TypographyColor = 'default' | 'primary' | 'success' | 'warning' | 'error' | 'muted' ``` ### `TypographyProps` ```typescript type TypographyProps = { /** * Typography variant * @default 'body' */ variant?: 'heading1' | 'heading2' | 'heading3' | 'body' | 'secondary' | 'caption' /** * Text size * @default undefined (uses variant default) */ size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl… ``` ### `UnitData` ```typescript type UnitData = { last?: UnitLast type?: string info?: UnitInfo [key: string]: unknown } ``` ### `UnitKey` ```typescript type UnitKey = keyof typeof UNITS ``` ### `UnitLabel` ```typescript type UnitLabel = 'decimal' | 'k' | 'M' | 'G' | 'T' | 'P' ``` ### `UnitValue` ```typescript type UnitValue = (typeof UNITS)[UnitKey] ``` ### `UpdateExistedActionsParams` ```typescript type UpdateExistedActionsParams = { actionType: string pendingSubmissions: PendingSubmission[] selectedDevices: Device[] } ``` ### `UseCabinetDetailResult` ```typescript type UseCabinetDetailResult = { /** Whether a cabinet is selected at all. */ hasSelection: boolean /** Cabinet display title (`LV Cabinet 1` / transformer title). */ title: string /** The non-root powermeter reading rows. */ powerMeters: CabinetReadingRow[] /** The cab… ``` ### `UseContainerThresholdsProps` ```typescript type UseContainerThresholdsProps = { data: UnknownRecord onSave?: (params: { data: UnknownRecord }) => Promise<void> } ``` ### `UseContainerThresholdsReturn` ```typescript type UseContainerThresholdsReturn = { // State thresholds: UnknownRecord parameters: UnknownRecord isEditing: boolean isSaving: boolean isSiteLoading: boolean isSettingsLoading: boolean // Methods handleThresholdChange: (thresholdType: string, key: string, value: string | nu… ``` ### `UseContainerWidgetsDataOptions` ```typescript type UseContainerWidgetsDataOptions = UseContainerWidgetsOptions ``` ### `UseContainerWidgetsDataResult` ```typescript type UseContainerWidgetsDataResult = { /** Card-ready data for every container, one entry per widget card. */ containers: ContainerWidgetItem[] isLoading: boolean /** Human-readable message when either underlying query errors, else undefined. */ errorMessage?: string /** True… ``` ### `UseCostSummaryOptions` ```typescript type UseCostSummaryOptions = UseFinancialDateRangeOptions & { query?: CostSummaryQueryResult } ``` ### `UseDeviceAlarmsResult` ```typescript type UseDeviceAlarmsResult = { /** Timeline items ready for the detail panel's "Active Alarms" box. */ alarmsDataItems: TimelineItemData[] /** Total number of alarms across the selected devices. */ alarmsCount: number } ``` ### `UseEbitdaOptions` ```typescript type UseEbitdaOptions = UseFinancialDateRangeOptions & { ebitda?: EbitdaResponse | undefined isLoading?: boolean fetchErrors?: string[] } ``` ### `UseEnergyBalanceOptions` ```typescript type UseEnergyBalanceOptions = { data?: EnergyBalanceResponse isLoading?: boolean fetchErrors?: string[] dateRange: FinancialDateRange | null availablePowerMW: number } ``` ### `UseEnergyReportSiteInput` ```typescript type UseEnergyReportSiteInput = { consumptionError?: unknown tailLogLoading?: boolean containersLoading?: boolean consumptionLoading?: boolean consumptionFetching?: boolean nominalConfigLoading?: boolean dateRange: EnergyReportDateRange containers?: EnergyReportContainer… ``` ### `UseEnergyReportSiteResult` ```typescript type UseEnergyReportSiteResult = { isLoading: boolean powerModeData: PowerModeTableRow[] refetchSnapshotData?: VoidFunction containers: EnergyReportContainer[] tailLogData: EnergyReportTailLogItem[][] tailLogHead: EnergyReportTailLogItem | undefined miningUnitCards: Energ… ``` ### `UseExplorerDataOptions` ```typescript type UseExplorerDataOptions = { /** Which tab's things to fetch and shape. */ deviceType: DeviceExplorerDeviceType /** Free-text search chips from the toolbar (OR-matched against each row). */ searchTags?: string[] /** Active filter selections from the toolbar cascader… ``` ### `UseExplorerDataResult` ```typescript type UseExplorerDataResult = { /** Rows for the active tab, after search + filter, ready for `<DeviceExplorer>`. */ data: DeviceExplorerDeviceData[] /** Autocomplete options for the search box, derived from the fetched rows. */ searchOptions: DeviceExplorerSearchOptio… ``` ### `UseExplorerSelectionParams` ```typescript type UseExplorerSelectionParams = { /** The active Explorer tab — decides which `devicesStore` setters fire. */ deviceType: DeviceExplorerDeviceType /** All rows currently shown for the tab (the search/filter output). */ rows: DeviceExplorerDeviceData[] /** The table's row… ``` ### `UseExplorerSelectionResult` ```typescript type UseExplorerSelectionResult = { /** The resolved selected rows (post search/filter). */ selectedRows: DeviceExplorerDeviceData[] /** Whether the container detail snapshots are still loading. */ isLoading: boolean } ``` ### `UseExplorerThingDetailResult` ```typescript type UseExplorerThingDetailResult = { /** Whether an id was provided at all — drives the "select a row" empty state. */ hasSelection: boolean /** Display name of the selected thing (container name / pos / id fallback). */ title: string /** Raw status string, or `offline`. Em… ``` ### `UseFinancialDateRangeOptions` ```typescript type UseFinancialDateRangeOptions = { defaultPeriod?: PeriodValue timezone?: string } ``` ### `UseFinancialDateRangeResult` ```typescript type UseFinancialDateRangeResult = { dateRange: FinancialDateRange | null handleRangeChange: ( dates: [Date, Date] | null, rangeOptions?: FinancialRangeChangeOptions, ) => void onDateRangeReset: () => void datePicker: ReactElement } ``` ### `UseFormFieldReturn` Hook to access the current form field's state and generated IDs. Must be used inside a `<FormField>` and `<FormItem>`. ```typescript type UseFormFieldReturn = ReturnType<UseFormGetFieldState<FieldValues>> & { id: string name: string formItemId: string formDescriptionId: string formMessageId: string } ``` ### `UseFormResetOptions` ```typescript type UseFormResetOptions = { /** * The form instance from useForm() */ form: UseFormReturn<TFieldValues> /** * Optional callback called before reset */ onBeforeReset?: VoidFunction /** * Optional callback called after reset */ onAfterReset?: VoidFunction } ``` ### `UseFormResetReturn` ```typescript type UseFormResetReturn = { /** * Reset the form to default values */ resetForm: VoidFunction /** * Whether the form has been modified from its default values */ isDirty: boolean } ``` ### `UseHashBalanceDerived` ```typescript type UseHashBalanceDerived = { isEmpty: boolean periodType: PeriodType showCombinedCostChart: boolean isNetworkHashrateEmpty: boolean costMetrics: HashBalanceMetric[] showWeeklyCostDisclaimer: boolean filteredLog: HashRevenueLogEntry[] revenueMetrics: HashBalanceMetri… ``` ### `UseHashBalanceInput` ```typescript type UseHashBalanceInput = { log?: HashRevenueLogEntry[] currency: HashBalanceCurrency dateRange: FinancialDateRange data?: HashRevenueResponse | null timeframeType?: TimeframeTypeValue | null } ``` ### `UseHashrateOptions` ```typescript type UseHashrateOptions = { /** * Result of fetching the v2 `/auth/metrics/hashrate?groupBy=...` endpoint. * * Wire whichever data layer you use (RTK Query, TanStack Query, fixtures) * and pass the result here - this hook never fetches itself. */ query?: HashrateQu… ``` ### `UseHashrateResult` ```typescript type UseHashrateResult = { log: HashrateGroupedLog | undefined isLoading: boolean error: unknown } ``` ### `UseListViewFiltersParams` ```typescript type UseListViewFiltersParams = { site?: string selectedType?: string availableDevices: AvailableDevices typeFiltersForSite: CascaderOption[] } ``` ### `UseMinerDetailResult` ```typescript type UseMinerDetailResult = { /** The selected miners (post bridge dispatch). */ miners: Device[] /** The first selected miner — drives the info / chips cards. */ headMiner?: Device /** Label/value rows for {@link MinerInfoCard}. */ infoItems: InfoItem[] /** The head… ``` ### `UseOperationsDashboardInput` Aggregate DI input for `useOperationsDashboard`. ```typescript type UseOperationsDashboardInput = Partial<{ hashrate: OperationsTrendInput consumption: OperationsTrendInput efficiency: OperationsTrendInput miners: OperationsMinersInput }> ``` ### `UseOperationsDashboardResult` Full view-model returned by `useOperationsDashboard`. ```typescript type UseOperationsDashboardResult = { hashrate: OperationsTrendViewModel consumption: OperationsTrendViewModel efficiency: OperationsTrendViewModel miners: OperationsMinersViewModel } ``` ### `UsePoolConfigsResult` ```typescript type UsePoolConfigsResult = { pools: PoolSummary[] poolIdMap: Record<string, PoolSummary> isLoading: boolean error: unknown } ``` ### `UseSiteOverviewDetailsDataResult` ```typescript type UseSiteOverviewDetailsDataResult = { actualMinersCount: number containerHashRate: string pdus: Pdu[] segregatedPduSections: Record<string, Pdu[]> minersHashmap: Record<string, MinerData> connectedMiners: ListThingsDevice[] | undefined containerInfo: ContainerInfo connectedM… ``` ### `UseSubsidyFeesInput` ```typescript type UseSubsidyFeesInput = { log?: SubsidyFeesLogEntry[] data?: SubsidyFeesResponse | null dateRange: FinancialDateRange | null } ``` ### `UseTimeframeControlsParams` ```typescript type UseTimeframeControlsParams = Pick< TimeframeControlsProps, 'dateRange' | 'timeframeType' | 'onRangeChange' | 'onTimeframeTypeChange' > & { isWeekSelectVisible: boolean /** Both month + week selects visible → week nested tree. */ weekTree: boolean } ``` ### `ValidateCSVRecordsOptions` ```typescript type ValidateCSVRecordsOptions = { checkDuplicateDelegate: (params: { rackId: string; serialNum: string[]; macAddress?: string[]; }) => Promise<unknown[]>; rackIds: Record<string, string>; validLocations?: string[]; subPartTypes?: Record<string, Set<string>>; minerModels?… ``` ### `ValueUnit` Shared type definitions for utility functions ```typescript type ValueUnit = { value: number | string | null unit: string realValue: number } ``` ### `WaterPump` ```typescript type WaterPump = { enabled: boolean } ``` ### `WebappUrlsKey` ```typescript type WebappUrlsKey = keyof typeof WEBAPP_URLS ``` ### `WebappUrlsValue` ```typescript type WebappUrlsValue = (typeof WEBAPP_URLS)[WebappUrlsKey] ``` ### `WeekData` ```typescript type WeekData = { start: Date end: Date label?: string bucketYear?: number bucketMonth?: number disabled?: boolean } ``` ### `WeekRangeCacheEntry` ```typescript type WeekRangeCacheEntry = { start: Date end: Date disabled?: boolean } ``` ### `WeightedAverageResult` ```typescript type WeightedAverageResult = { avg: number totalWeight: number weightedValue: number } ``` ### `WeightedDataPoint` ```typescript type WeightedDataPoint = { value: number weight: number } ``` ### `WidgetTopRowProps` ```typescript type WidgetTopRowProps = { title: string power?: number unit?: string statsErrorMessage?: string | ErrorWithTimestamp[] | null alarms?: AlarmsMap className?: string } ``` # Foundation Dashboard Types (/reference/ui/types/foundation-dashboard) Type definitions for dashboard data structures. ## Package `@tetherto/mdk-ui-foundation` ## Types ### `ChartCardData` Minimum chart-ready payload — assignable to `LineChartCardData` from `@tetherto/mdk-react-devkit`. ```typescript type ChartCardData = { datasets: ChartDataset[] } & Partial<{ /** Y-axis tick formatter (e.g. `(v) => \`${v.toFixed(2)} MW\``). */ yTicksFormatter: (value: number) => string /** Cr… ``` ### `ChartDataPoint` A single (x, y) sample. `x` is a Unix timestamp in **seconds** (lightweight-charts convention); `y` is `null` to render gaps. ```typescript type ChartDataPoint = { x: number y: number | null } ``` ### `ChartDataset` A named line series with colour and points. Optional `visible` lets pages pre-hide datasets without removing them from the data array. ```typescript type ChartDataset = { label?: string borderColor: string data: ChartDataPoint[] visible?: boolean } ``` # Foundation General Types (/reference/ui/types/foundation-general) General type definitions from the ui-foundation package. ## Package `@tetherto/mdk-ui-foundation` ## Types ### `ApiError` Shared error contract used across HTTP/API surfaces. ```typescript type ApiError = { error: string message: string status: number data?: { message?: string } } ``` ### `ImportResult` ```typescript type ImportResult = { success: boolean applied?: string[] errors?: string[] message?: string } ``` ### `PermLevel` ```typescript type PermLevel = 'rw' | 'r' | false ``` ### `RoleOption` ```typescript type RoleOption = { label: string value: string } ``` ### `RolesPermissionsData` ```typescript type RolesPermissionsData = { permissions: Record<string, Record<string, PermLevel>> labels: Record<string, string> } ``` ### `SettingsExportData` ```typescript type SettingsExportData = { headerControls?: Record<string, boolean> featureFlags?: Record<string, boolean> timestamp?: string version?: string } & TExtra ``` ### `SettingsUser` ```typescript type SettingsUser = { id: string name?: string email: string role: string last_login?: string lastActive?: string [key: string]: unknown } ``` ### `SubscriberCallback` ```typescript type SubscriberCallback = (value: T) => void ``` ### `UnknownRecord` Generic type for objects with unknown structure. ```typescript type UnknownRecord = Record<string, unknown> ``` ### `Unsubscribe` ```typescript type Unsubscribe = () => void ``` # Utilities (/reference/ui/utilities) Helper functions, formatters, and utilities exported from `@tetherto/mdk-ui-foundation`. ## Browse by category | Category | Description | |----------|-------------| | [Alerts](/reference/ui/utilities/alerts) | Alert query builders and time-range utilities | | [Auth](/reference/ui/utilities/auth) | Authentication helper functions | | [Dashboard](/reference/ui/utilities/dashboard) | Dashboard data utilities | | [General](/reference/ui/utilities/general) | General-purpose utilities | | [Utils](/reference/ui/utilities/utils) | Core utility functions | ## Import pattern ```tsx ``` # Alert Utilities (/reference/ui/utilities/alerts) Utilities for building alert queries and managing time ranges. ## Package `@tetherto/mdk-ui-foundation` ## Utilities ### `breakTimeIntoIntervals` Split `[start, end]` into consecutive windows of `intervalMs`. The final window is clamped to `end`. Returns an empty array when the range is empty or inverted. Mirrors Mining OS's `breakTimeIntoIntervals`. **Function** ```typescript (start: number, end: number, intervalMs: number = ONE_DAY_MS) => TimeInterval[] ``` ### `buildCurrentAlertDevicesParams` `list-things` params for the current-alerts table: every device that currently carries one or more alerts, with the fields the `<CurrentAlerts>` table reads. Consumed by `useCurrentAlertDevices`. **Function** ```typescript (filterTags: string[] = []) => ListThingsParams ``` ### `buildHistoricalAlertsParams` `history-log` params for a single alerts window. The chunked fetch (`useHistoricalAlerts`) calls this once per 24h sub-window. **Function** ```typescript (range: HistoricalAlertsRange) => HistoryLogParams ``` ### `fetchHistoricalAlertsInChunks` Fetch a historical-alerts range as successive 24h windows, merging the results by `uuid`. `fetchWindow` is called once per window (oldest → newest); individual window failures are swallowed (matches Mining OS) so one bad window doesn't dro… **Function** ```typescript (range: { start: number; end: number }, fetchWindow: (window: TimeInterval) => Promise<T[]>, options: FetchHistoricalAlertsOptions = {}) => Promise<T[]> ``` ### `getAlertsForDevices` Flatten an array of devices into a list of incident rows, one per alert. Devices without `last.alerts` are skipped. The output is **not yet sorted**; pair with `sortIncidentsBySeverity` for the final list-view order. **Function** ```typescript (devices: ListThingsDevice[], formatDate: (d: Date) => string = (d) => d.toISOString()) => IncidentRow[] ``` ### `getDefaultHistoricalAlertsRange` Default historical-alerts range: the last `DEFAULT_HISTORICAL_WINDOW_MS` ending now. Used by the devkit `<Alerts>` feature and the shell Alerts page to seed their range state. **Function** ```typescript (now: number = Date.now()) => HistoricalAlertsRange ``` ### `mapDevicesToIncidents` One-shot helper: `devices → sorted rows`. Used by the `useActiveIncidents` hook's `select` projection. **Function** ```typescript (devices: ListThingsDevice[], formatDate?: (d: Date) => string) => IncidentRow[] ``` ### `mapHistoryLogToAlerts` Normalise raw `history-log` alert rows into the shape the devkit `<HistoricalAlerts>` table consumes. The table derives its device label, short code, and filter tokens from each row's `thing` (treated as a device), so this guarantees `thin… **Function** ```typescript (rows: HistoricalAlert[] = []) => HistoricalAlert[] ``` ### `mergeAlertsByUuid` Concatenate `next` onto `prev`, replacing any row that shares a `uuid` (later windows win) and appending the rest. Rows without a `uuid` are always appended. Mirrors Mining OS's `updateHistoricalData`. **Function** ```typescript (prev: T[], next: T[]) => T[] ``` ### `sortIncidentsBySeverity` Sort rows by severity (critical → high → medium), then by `id` for deterministic ordering when severities tie. Returns a new array. **Function** ```typescript (rows: IncidentRow[]) => IncidentRow[] ``` # Auth Utilities (/reference/ui/utilities/auth) Helper functions for authentication flows. ## Package `@tetherto/mdk-ui-foundation` ## Utilities ### `extractAuthTokenFromUrl` Extract `?authToken=` from a URL search string. Accepts either a full URL, a query string with leading `?`, or a bare query string. **Function** ```typescript (search: string) => string | null ``` ### `stripAuthTokenFromUrl` Build a URL string with the `?authToken=` parameter stripped. Used after the OAuth callback to remove the token from the address bar without losing any other query state. **Function** ```typescript (search: string) => string ``` # Dashboard Utilities (/reference/ui/utilities/dashboard) Utilities for dashboard data processing. ## Package `@tetherto/mdk-ui-foundation` ## Utilities ### `buildHashrateTailLogParams` Hashrate tail-log params — per-miner 1-minute aggregate, summed across the `t-miner` tag. **Function** ```typescript (range: DashboardQueryRange) => TailLogParams ``` ### `buildMinerpoolStatsHistoryExtDataParams` Ext-data params for `type=minerpool, key=stats-history` — per-pool hashrate snapshots over time. Pair with `extDataQuery` to feed the multi-series Hash Rate chart (Mining OS + Aggr Pool + per-pool lines). **Function** ```typescript (range: MinerpoolStatsHistoryRange = {}) => ExtDataParams ``` ### `buildSiteConsumptionTailLogParams` Site-level consumption tail-log params — reads the dedicated powermeter's `site_power_w` aggregate (Mining OS's `type=powermeter, tag=t-powermeter, aggrFields={site_power_w:1}` query). Returns the same series the header's `useSitePowerMete… **Function** ```typescript (range: DashboardQueryRange) => TailLogParams ``` ### `DEFAULT_TIMELINE_OPTIONS` Canonical short-form intervals exposed by MDK UI Shell. The keys map onto the `key=stat-<value>` query parameter expected by `GET /auth/tail-log`. **Constant** ```typescript readonly TimelineOption[] ``` ### `getTimelineOptions` Default options for the dashboard timeline selector. Mirrors Mining OS's `timelineRadioButtons` (5m / 30m / 3h / 1D) — the production dashboard doesn't expose `stat-1m` because the backend typically only emits 5-minute and longer aggregate… **Function** ```typescript (opts: { includeOneMinute?: boolean } = {}) => TimelineOption[] ``` ### `normalizeAlertSeverity` Narrow an arbitrary backend severity string to the `AlertSeverity` literal union expected by the `ActiveIncidentsCard` row component. Unknown values fall back to `'medium'` so the row still renders rather than crashing on an unexpected pay… **Function** ```typescript (raw: string | null | undefined) => AlertSeverity ``` ### `readHashrateMhs` Reads the hashrate aggregate from a tail-log entry. Mining OS emits `hashrate_mhs_1m_sum_aggr` across every `stat-*` bucket, so a single field check covers all timelines; the `_5m_` legacy fallback is retained as a defensive secondary in c… **Function** ```typescript (entry: { hashrate_mhs_1m_sum_aggr?: unknown hashrate_mhs_5m_sum_aggr?: unknown }) => number | undefined ``` ### `SEVERITY_WEIGHT` Severity level → numeric weight. Higher is more urgent. Used for sorting the active-incidents list (most-severe first). **Constant** ```typescript Record<AlertSeverity, number> ``` # General Utilities (/reference/ui/utilities/general) General-purpose helper functions. ## Package `@tetherto/mdk-ui-foundation` ## Utilities ### `ALERT_TYPE_POOL_NAME` **Constant** ```typescript { readonly ip_worker_name: "IP worker name"; readonly wrong_miner_pool: "Wrong miner pool"; readonly wrong_worker_name: "Wrong worker name"; readonly wrong_miner_subaccount: "Wrong miner subaccount";… ``` ### `ALERT_TYPE_POOL_VALUE` **Constant** ```typescript { readonly IP_WORKER_NAME: "ip_worker_name"; readonly WRONG_MINER_POOL: "wrong_miner_pool"; readonly WRONG_WORKER_NAME: "wrong_worker_name"; readonly WRONG_MINER_SUBACCOUNT: "wrong_miner_subaccount";… ``` ### `appendContainerToTag` **Function** ```typescript (deviceId: string) => string ``` ### `appendIdToTag` **Function** ```typescript (deviceId: string) => string ``` ### `appendIdToTags` **Function** ```typescript (deviceIdList: string[]) => string[] ``` ### `AUTH_LEVELS` **Constant** ```typescript { readonly READ: "r"; readonly WRITE: "w"; } ``` ### `AUTH_PERMISSIONS` **Constant** ```typescript { readonly TEMP: "temp"; readonly MINER: "miner"; readonly USERS: "users"; readonly ALERTS: "alerts"; readonly TICKETS: "tickets"; readonly ACTIONS: "actions"; readonly REVENUE: "revenue"; readonly F… ``` ### `AUTH_TOKEN_QUERY_PARAM` Pure URL helpers shared by the auth flow. Kept framework-agnostic so the react-adapter (and any future framework adapter) can call them without pulling in router-specific APIs. **Constant** ```typescript "authToken" ``` ### `buildCabinetDetailParams` List-things params for one LV cabinet's family of devices — the powermeters and temperature sensors whose `info.pos` sits under the cabinet `root`. Mirrors the reference app's `getLvCabinetDevicesByRoot(root)`; the detail hook groups the r… **Function** ```typescript (root: string) => ListThingsParams ``` ### `buildContainerCrossThing` `{ type: 'container', params: { containers } }` fan-out for miner-level actions. **Function** ```typescript (containers: string[]) => DeviceActionCrossThing ``` ### `buildContainerDetailParams` List-things params for the selected containers' detail snapshots. Takes the raw container keys (the `selectedDevicesTags` outer keys / `info.container` names), tags them with `container-` and filters to `t-container` things — mirrors the r… **Function** ```typescript (containerKeys: string[]) => ListThingsParams ``` ### `buildContainerWidgetsListParams` List-things params for the Site Overview container widgets grid. **Function** ```typescript () => ListThingsParams ``` ### `buildContainerWidgetsRealtimeTailLogParams` Tail-log params for the Container Widgets realtime snapshot — the latest `stat-realtime` sample across all miners, grouped so the cards can slice per container. **Function** ```typescript () => TailLogParams ``` ### `buildDeviceActionSubmission` Core submission assembler. Prefer the per-action builders below — they pin each action's param arity/encoding; this is the escape hatch for actions without a dedicated builder. `extras` is spread first so it can never override the pinned s… **Function** ```typescript (action: DeviceActionValue, tags: string[], params: VotingActionParam[] = [], extras: Record<string, unknown> = {}) => DeviceActionSubmission ``` ### `buildExplorerListThingsParams` List-things params for one Explorer tab: tag-filtered, status-enriched, projected to `OP_CENTRE_LIST_THINGS_FIELDS`. **Function** ```typescript (tab: ExplorerTabValue, options: { limit?: number; offset?: number } = {}) => ListThingsParams ``` ### `buildMinerCrossThing` `{ type: 'miner', params: { containers } }` fan-out for container-level actions. **Function** ```typescript (containers: string[]) => DeviceActionCrossThing ``` ### `buildRebootAction` `reboot` — no params. **Function** ```typescript (tags: string[]) => DeviceActionSubmission ``` ### `buildResetAlarmAction` `resetAlarm` — no params. **Function** ```typescript (tags: string[]) => DeviceActionSubmission ``` ### `buildSetAirExhaustEnabledAction` `setAirExhaustEnabled` — single boolean param. **Function** ```typescript (tags: string[], isOn: boolean) => DeviceActionSubmission ``` ### `buildSetLedAction` `setLED` — single boolean param. **Function** ```typescript (tags: string[], isOn: boolean) => DeviceActionSubmission ``` ### `buildSetPlcRegistersAction` `setPlcRegisters` (Gamma) — single `{ register: value }` map param. **Function** ```typescript (tags: string[], registers: Record<string, unknown>) => DeviceActionSubmission ``` ### `buildSetPowerModeAction` `setPowerMode` — single power-mode param, optional container fan-out. **Function** ```typescript (tags: string[], mode: PowerModeValue, crossThing?: DeviceActionCrossThing) => DeviceActionSubmission ``` ### `buildSetPowerPctAction` `setPowerPct` — percentage encoded as a string, optional container fan-out. **Function** ```typescript (tags: string[], percentage: number, crossThing?: DeviceActionCrossThing) => DeviceActionSubmission ``` ### `buildSetTankEnabledAction` `setTankEnabled` — positional `[tankNumber, isOn]`. **Function** ```typescript (tags: string[], tankNumber: number, isOn: boolean) => DeviceActionSubmission ``` ### `buildSwitchContainerAction` `switchContainer` — single boolean param. **Function** ```typescript (tags: string[], isOn: boolean) => DeviceActionSubmission ``` ### `buildSwitchCoolingSystemAction` `switchCoolingSystem` — single boolean param, optional miner fan-out. **Function** ```typescript (tags: string[], isOn: boolean, crossThing?: DeviceActionCrossThing) => DeviceActionSubmission ``` ### `buildSwitchSocketAction` `switchSocket` — one `{ pdu, socket, enabled }` param per toggled socket. **Function** ```typescript (tags: string[], sockets: SocketSwitch[]) => DeviceActionSubmission ``` ### `buildUpdateThingBatchEntry` One `updateThing` entry inside a move/add/replace-miner batch — carries the miner's new rack/position/network config plus the owning `minerId` the backend uses to group batch progress. **Function** ```typescript (params: UpdateThingParams, minerId: string = params.id) => VotingActionPayload ``` ### `CABINET_DEVICES_TYPES_NAME_MAP` **Constant** ```typescript { readonly "powermeter-abb-b24": "Powermeter ABB B24"; readonly "sensor-temp-seneca": "Sensor Temp Seneca"; readonly "powermeter-abb-m4m20": "Powermeter ABB M4M20"; readonly "powermeter-abb-m1m20": "… ``` ### `checkPermission` Check if user has the requested permission **Function** ```typescript (config: AuthConfig | null | undefined, { perm, write, cap }: PermissionCheck) => boolean ``` ### `COMPLETE_CONTAINER_TYPE` **Constant** ```typescript { readonly BITMAIN_HYDRO: "container-as-hk3"; readonly BITDEER_M30: "container-bd-d40-m30"; readonly BITDEER_M56: "container-bd-d40-m56"; readonly MICROBT_ALPHA: "container-mbt-alpha"; readonly BITDE… ``` ### `COMPLETE_MINER_TYPES` **Constant** ```typescript { readonly ANTMINER_AM_S21: "miner-am-s21"; readonly WHATSMINER_WM_63: "miner-wm-m63"; readonly WHATSMINER_WM_53: "miner-wm-m53s"; readonly AVALON_AV_a1346: "miner-av-a1346"; readonly WHATSMINER_WM_5… ``` ### `CONTAINER_LIST_THINGS_LIMIT` **Constant** ```typescript 1000 ``` ### `CONTAINER_MODEL` Container tag / type / threshold literals. Data-layer contracts shared across the toolkit — owned by ui-foundation so the React layers stay free of tag strings. **Constant** ```typescript { readonly M221: "m221"; readonly GAMMA: "gamma"; readonly BITDEER: "bitdeer"; readonly BITMAIN: "bitmain"; readonly MICROBT: "microbt"; readonly ANTSPACE: "antspace"; readonly BITMAIN_IMM: "bitmain-… ``` ### `CONTAINER_MODEL_FAMILY` Container model families the tab matrix distinguishes. Detection order matters and mirrors the reference app's if/else chain — see `resolveContainerModelFamily`. **Constant** ```typescript { readonly BITDEER: "bitdeer"; readonly ANTSPACE_HYDRO: "antspace-hydro"; readonly ANTSPACE_IMMERSION: "antspace-immersion"; readonly MICROBT: "microbt"; readonly GAMMA: "gamma"; } ``` ### `CONTAINER_SETTINGS_MODEL` **Constant** ```typescript { BITDEER: string; MICROBT: string; HYDRO: string; IMMERSION: string; } ``` ### `CONTAINER_STATUS` **Constant** ```typescript { readonly RUNNING: "running"; readonly OFFLINE: "offline"; readonly STOPPED: "stopped"; } ``` ### `CONTAINER_TAB` Container detail-view tab keys. The per-model availability matrix lives in `utils/container-tabs.ts`. **Constant** ```typescript { readonly PDU: "pdu"; readonly HOME: "home"; readonly ALARM: "alarm"; readonly CHARTS: "charts"; readonly HEATMAP: "heatmap"; readonly CONTROLS: "controls"; readonly SETTINGS: "settings"; readonly P… ``` ### `CONTAINER_TAB_LABEL` Display labels for the container detail tabs, mirroring the reference app's `containerTabsHelper` (`PDU` renders as "PDU Layout", the rest are capitalised keys). **Constant** ```typescript { readonly pdu: "PDU Layout"; readonly home: "Home"; readonly alarm: "Alarm"; readonly charts: "Charts"; readonly heatmap: "Heatmap"; readonly controls: "Controls"; readonly settings: "Settings"; rea… ``` ### `CONTAINER_TAB_MATRIX` Base tab sequence per model family — order is display order. Power Adjustment is intentionally absent here: it is inserted positionally by `getSupportedContainerTabs`. **Constant** ```typescript Record<ContainerModelFamily, readonly ContainerTabValue[]> ``` ### `CONTAINER_TACTICS_TYPE` **Constant** ```typescript { readonly COIN: "coin"; readonly DISABLED: "disabled"; readonly ELECTRICITY: "electricity"; } ``` ### `CONTAINER_TYPE` **Constant** ```typescript { readonly BITDEER: "bd"; readonly ANTSPACE: "as"; readonly MICROBT: "mbt"; readonly ANTSPACE_HYDRO: "as-hk3"; readonly ANTSPACE_IMMERSION: "as-immersion"; } ``` ### `CONTAINER_TYPE_NAME_MAP` **Constant** ```typescript { readonly "container-bd-d40-m30": "Bitdeer M30"; readonly "container-bd-d40-m56": "Bitdeer M56"; readonly "container-bd-d40-s19xp": "Bitdeer S19XP"; readonly "container-as-hk3": "Bitmain Hydro"; rea… ``` ### `CONTAINER_WIDGETS_AGGR_FIELD_KEYS` All realtime aggregate fields the cards read — the tail-log `aggrFields` set. **Constant** ```typescript readonly string[] ``` ### `CONTAINER_WIDGETS_SUMMARY_FIELD` Realtime summary aggregate field names (these carry the `_aggr` suffix). **Constant** ```typescript { readonly HASHRATE_MHS_1M_SUM: "hashrate_mhs_1m_group_sum_aggr"; readonly TEMPERATURE_MAX: "temperature_c_group_max_aggr"; readonly TEMPERATURE_AVG: "temperature_c_group_avg_aggr"; } ``` ### `CONTAINERS_MINER_TYPE` **Constant** ```typescript { readonly M56: "m56"; readonly M30: "m30"; readonly A1346: "a1346"; readonly S19XP: "s19xp"; } ``` ### `DEFAULT_HISTORICAL_WINDOW_MS` Default historical-alerts look-back window (14 days), matching the devkit `<Alerts>` feature default. Wider ranges fan out into more 24h requests — see `fetchHistoricalAlertsInChunks`. **Constant** ```typescript number ``` ### `deriveContainerActivity` Slice the realtime aggregate into one container's per-status miner counts. `total` is the container's nominal miner capacity; miners not accounted for by any status count collapse into `disconnected` (never negative). With no realtime samp… **Function** ```typescript (realtime: TailLogEntry | undefined, containerModel: string, total: number) => ContainerActivity ``` ### `deriveContainerSummary` **Function** ```typescript (realtime: TailLogEntry | undefined, containerModel: string) => ContainerSummary ``` ### `deriveContainerTanks` Derive the per-tank readings for a container's immersion cooling system — one entry per oil pump, joined with the matching water pump and (when present) the tank pressure. Returns an empty array for containers without an immersion cooling… **Function** ```typescript (container: ListThingsDevice) => TankReading[] ``` ### `deriveSelectedSockets` Derive the store's `selectedSockets` map (keyed by container tag) from the selected device-tags — the pure body of the reference app's `findAndSetSelectedSockets`. Each per-container tag key (`pos-…` / `id-…`) is stripped of its `pos-` pre… **Function** ```typescript (containers: ContainerSnapshotForSockets[] | undefined, selectedDevicesTags: Record<string, Record<string, unknown>>, allDevices: MinerForSocket[] | undefined) => Record<string, { sockets: DerivedSoc… ``` ### `DEVICE_ACTION` Action identifiers accepted by `POST /auth/actions/voting` (the reference app's `ACTION_TYPES`, camelCase vocabulary). **Constant** ```typescript { readonly SWITCH_CONTAINER: "switchContainer"; readonly SWITCH_COOLING_SYSTEM: "switchCoolingSystem"; readonly SET_TANK_ENABLED: "setTankEnabled"; readonly SET_AIR_EXHAUST_ENABLED: "setAirExhaustEna… ``` ### `DEVICE_BATCH_ACTION` Batch action identifiers (`POST /auth/actions/voting/batch`) — each groups a set of per-thing sub-actions under one `batchActionUID`. **Constant** ```typescript { readonly MOVE_MINER: "moveMiner"; readonly DELETE_MINER: "deleteMiner"; readonly ATTACH_SPARE_PARTS: "attachSpareParts"; readonly BULK_ADD_SPARE_PARTS: "bulkAddSpareParts"; readonly BATCH_MOVE_SPAR… ``` ### `EXPLORER_TAB` Explorer list-view tabs. **Constant** ```typescript { readonly MINER: "miner"; readonly CABINET: "cabinet"; readonly CONTAINER: "container"; } ``` ### `EXPLORER_TAB_TAGS` Thing tags each Explorer tab lists. The cabinet tab unions powermeters and sensors — there is no dedicated `t-cabinet` tag. **Constant** ```typescript Record<ExplorerTabValue, readonly string[]> ``` ### `exportSettingsToFile` **Function** ```typescript (data: SettingsExportData) => string ``` ### `filterUsers` **Function** ```typescript ({ users, email, role }: FilterUsersParams) => SettingsUser[] ``` ### `findMatchingContainer` Find the container-settings row for a container type: an exact `model` match first, else the settings-model family fallback. Mirrors the reference app's `findMatchingContainer`. **Function** ```typescript (settings: ContainerSettingsEntry[] | undefined, containerType: string | undefined) => ContainerSettingsEntry | null ``` ### `flattenKernelEnvelope` Flattens the per-Kernel response envelope the gateway wraps around merged worker responses (`/auth/list-things`, `/auth/list-racks`, ... return `[[row, ...], [row, ...]]` — one inner array per Kernel). Null-safe on both levels: a missing e… **Function** ```typescript (envelope: ReadonlyArray<readonly (T | null | undefined)[] | null | undefined> | null | undefined) => T[] ``` ### `formatLastActive` **Function** ```typescript (timestamp: string | undefined) => string ``` ### `formatRoleLabel` **Function** ```typescript (role: string) => string ``` ### `getAntspaceHydroIndexes` Antspace Hydro position → `[rack, pdu, socket]`. **Function** ```typescript (pos: string) => string[] ``` ### `getAntspaceImmersionIndexes` Antspace Immersion position → `[pdu, socket]`. **Function** ```typescript (pos: string) => string[] ``` ### `getBitdeerIndexes` Bitdeer / MicroBT position → `[pdu, socket]`. **Function** ```typescript (pos: string) => string[] ``` ### `getByIdsQuery` **Function** ```typescript (ids: string[], allowEmptyArray?: boolean) => string ``` ### `getByTagsQuery` **Function** ```typescript (filterTags: string[], allowEmptyArray?: boolean) => string ``` ### `getByTagsWithAlertsQuery` **Function** ```typescript (filterTags: string[], allowEmptyArray?: boolean) => string ``` ### `getByTagsWithCriticalAlertsQuery` **Function** ```typescript (filterTags: string[], allowEmptyArray?: boolean) => string ``` ### `getByThingsAttributeQuery` **Function** ```typescript (filterAttributes: FilterAttribute[], selectedTypes: string[], allowEmptyArray?: boolean) => UnknownRecord ``` ### `getByTypesQuery` **Function** ```typescript (filterTypes: string[], allowEmptyArray?: boolean) => string ``` ### `getConnectedMinerForSocket` The selected miner sitting at `pos`, if any (miners only, exact position). **Function** ```typescript (devices: MinerForSocket[] | undefined, pos: string) => MinerForSocket | undefined ``` ### `getContainerByContainerTagsQuery` **Function** ```typescript (filterTags: string[], allowEmptyArray?: boolean) => string ``` ### `getContainerMinersByContainerTagsQuery` **Function** ```typescript (filterTags: string[], allowEmptyArray?: boolean) => string ``` ### `getContainerSettingsModel` Map a container type string to its settings-model key (`bd` / `mbt` / `hydro` / `immersion`), or `null` for an unknown family. Mirrors the reference app's `getContainerSettingsModel`. **Function** ```typescript (containerType: string | undefined) => string | null ``` ### `getDeviceByAlertId` **Function** ```typescript (uuid: string) => string ``` ### `getFiltersQuery` **Function** ```typescript (filterTags?: string[], filters?: Record<string, string[]>, selectedTypes: string[] = ['t-container']) => UnknownRecord ``` ### `getListQuery` **Function** ```typescript (filterTags: string[], filters?: Record<string, string[]>, selectedTypes: string[] = ['t-container']) => string ``` ### `getLvCabinetDevicesByRoot` **Function** ```typescript (root: string) => string ``` ### `getMinersByContainerTagsQuery` **Function** ```typescript (filterTags: string[], allowEmptyArray?: boolean) => string ``` ### `getPduByIndex` The PDU row whose `pdu` matches `pduIndex` on this container, or undefined. **Function** ```typescript (container: ContainerSnapshotForSockets | undefined, pduIndex: string | number) => PduSnapshot | undefined ``` ### `getPduData` The `pdu_data` array off a container detail snapshot, or undefined. **Function** ```typescript (last: ContainerSnapshotForSockets['last']) => PduSnapshot[] | undefined ``` ### `getRolesFromAuthToken` Extract roles from authentication token **Function** ```typescript (authToken?: string) => string[] ``` ### `getSignInRedirectUrl` Get redirect URL based on user's primary role **Function** ```typescript (authToken: string | null | undefined) => string ``` ### `getSitePowerMeterQuery` **Function** ```typescript () => string ``` ### `getSocketInfo` Resolve one socket for `pos` on `container`: pick the vendor index scheme off the container name, then (for Bitdeer / MicroBT) join the live PDU row so `enabled` / `cooling` reflect the snapshot. Hydro / Immersion have no live socket table… **Function** ```typescript (container: ContainerSnapshotForSockets, pos: string, allDevices: MinerForSocket[] | undefined) => DerivedSocket ``` ### `getSupportedContainerTabs` Full tab sequence for a container type: the family's base sequence, plus Power Adjustment spliced in after the PDU tab for Whatsminer containers. Unknown types resolve to an empty list. **Function** ```typescript (type: string | undefined) => ContainerTabValue[] ``` ### `getWidgetAlarmState` Resolve a container's alarm state from its live stats and matched settings. **Function** ```typescript (_container: ListThingsDevice, _settings: ContainerSettingsEntry | null = null) => ContainerAlarmState ``` ### `isAntminer` **Function** ```typescript (type: string | undefined) => boolean ``` ### `isAntspaceHydroContainer` Antspace/Bitmain hydro family (`as-hk3`, `antspace-hydro`, `bitmain-hydro`). **Function** ```typescript (type: string | undefined) => boolean ``` ### `isAntspaceImmersionContainer` Antspace/Bitmain immersion family (`as-immersion`, `bitmain-imm[ersion]`). **Function** ```typescript (type: string | undefined) => boolean ``` ### `isAvalon` **Function** ```typescript (type: string | undefined) => boolean ``` ### `isBitdeerContainer` Bitdeer family — `container-bd-*` and anything mentioning `bitdeer`. **Function** ```typescript (type: string | undefined) => boolean ``` ### `isContainer` **Function** ```typescript (type: string | undefined) => boolean ``` ### `isGammaContainer` Gamma family (`m221`, `gamma`). **Function** ```typescript (type: string | undefined) => boolean ``` ### `isMicroBTContainer` MicroBT family (`mbt`, `microbt`). **Function** ```typescript (type: string | undefined) => boolean ``` ### `isMiner` **Function** ```typescript (type: string | undefined) => boolean ``` ### `isPduContainerTab` The PDU grid renders under the `pdu` tab key. **Function** ```typescript (tab: string | undefined) => boolean ``` ### `isWhatsminer` **Function** ```typescript (type: string | undefined) => boolean ``` ### `isWhatsminerContainer` Containers populated with Whatsminer miners (`m56` / `m30` positions, or any MicroBT container) — the set that gets the Power Adjustment tab. **Function** ```typescript (type: string | undefined) => boolean ``` ### `LV_CABINET_DEVICES_TAG` **Constant** ```typescript { readonly POWERMETER: "t-powermeter"; readonly SENSOR_TEMP: "t-sensor-temp"; } ``` ### `LV_CABINET_DEVICES_TYPE` **Constant** ```typescript { readonly POWERMETER_ABB_B24: "powermeter-abb-b24"; readonly SENSOR_TEMP_SENECA: "sensor-temp-seneca"; readonly POWERMETER_ABB_M1M20: "powermeter-abb-m1m20"; readonly POWERMETER_ABB_M4M20: "powermet… ``` ### `MAINTENANCE_CONTAINER` **Constant** ```typescript "maintenance" ``` ### `MINER_BRAND_NAMES` **Constant** ```typescript { readonly av: "Avalon"; readonly am: "Antminer"; readonly wm: "Whatsminer"; } ``` ### `MINER_MODEL` Device / miner / power-meter tag + type literals. These are data-layer contracts shared between the API surface and the UI — owned by ui-foundation so the React layers can stay free of tag strings. **Constant** ```typescript { readonly AVALON: "avalon"; readonly ANTMINER: "antminer"; readonly WHATSMINER: "whatsminer"; } ``` ### `MINER_MODEL_TO_TYPE_MAP` **Constant** ```typescript { readonly av: "avalon"; readonly am: "antminer"; readonly wm: "whatsminer"; } ``` ### `MINER_POWER_MODE` **Constant** ```typescript { readonly SLEEP: "sleep"; readonly LOW: "low"; readonly NORMAL: "normal"; readonly HIGH: "high"; } ``` ### `MINER_TYPE` **Constant** ```typescript { readonly AVALON: "av"; readonly ANTMINER: "am"; readonly WHATSMINER: "wm"; } ``` ### `MINER_TYPE_MESSAGE` **Constant** ```typescript { readonly "miner-av-a1346": "A1346 miners do not report consumption individually, so Avg. efficiency cannot be calculated"; } ``` ### `MINER_TYPE_NAME_MAP` **Constant** ```typescript { readonly "miner-av-a1346": "Avalon A1346"; readonly "miner-am-s21": "Antminer S21"; readonly "miner-wm-m63": "Whatsminer M63"; readonly "miner-wm-m56s": "Whatsminer M56S"; readonly "miner-wm-m53s":… ``` ### `MinerStatuses` **Constant** ```typescript { readonly MINING: "mining"; readonly OFFLINE: "offline"; readonly SLEEPING: "sleeping"; readonly ERROR: "error"; readonly NOT_MINING: "not_mining"; readonly MAINTENANCE: "maintenance"; readonly ALER… ``` ### `NO_MAINTENANCE_CONTAINER` **Constant** ```typescript "no_maintenance" ``` ### `ONE_DAY_MS` One day in milliseconds — the historical-log fetch window size. **Constant** ```typescript number ``` ### `OP_CENTRE_CABINET_DETAIL_FIELDS` The cabinet-detail field projection — the sensor/powermeter fields the LV cabinet detail reads: each device's `power_w` / `temp_c` reading, status (for the offline marker) and `last.alerts` (for the warnings timeline). **Constant** ```typescript string ``` ### `OP_CENTRE_CONTAINER_DETAIL_FIELDS` The container-detail field projection — a superset of the list projection that also pulls the full `last.snap.stats` (so the socket transform sees `container_specific.pdu_data`, ambient temp, humidity, …) and the full `last.snap.config` (p… **Constant** ```typescript string ``` ### `OP_CENTRE_CONTAINER_WIDGETS_FIELDS` Container list projection for the Site Overview widgets — the lean list fields plus `last.snap.stats.container_specific` (cooling system: oil / water pumps, tanks) and `last.snap.config` (per-vendor thresholds), which the vendor boxes (e.g… **Constant** ```typescript string ``` ### `OP_CENTRE_LIST_THINGS_FIELDS` The list-things field projection the Explorer tables and Container Widgets cards read — the reference app's `LIST_THINGS_FIELDS`, kept as one projection so every consumer sees the same row shape. **Constant** ```typescript string ``` ### `parseSettingsFile` **Function** ```typescript (file: File) => Promise<SettingsExportData> ``` ### `PM_ATTRIBUTE_LABEL_MAP` **Constant** ```typescript { readonly 'I1 a': "Current L1"; readonly 'I2 a': "Current L2"; readonly 'I3 a': "Current L3"; readonly 'V3 n v': "Voltage L3-N"; readonly 'V2 n v': "Voltage L2-N"; readonly 'V1 n v': "Voltage L1-N";… ``` ### `POWER_MODE` Miner power modes accepted by `setPowerMode`. **Constant** ```typescript { readonly SLEEP: "sleep"; readonly LOW: "low"; readonly NORMAL: "normal"; readonly HIGH: "high"; } ``` ### `removeContainerPrefix` **Function** ```typescript (text: string) => string ``` ### `resolveContainerModelFamily` Resolves a raw container `type` string (e.g. `container-bd-d40-m56`) to its model family, or `undefined` for unknown types. First match wins, in the reference app's original branch order. **Function** ```typescript (type: string | undefined) => ContainerModelFamily | undefined ``` ### `SITE_OVERVIEW_STATUSES` **Constant** ```typescript { readonly OFFLINE: "offline"; readonly EMPTY: "empty"; readonly NOT_MINING: "not_mining"; readonly MINING: "mining"; } ``` ### `SOCKET_STATUSES` **Constant** ```typescript { readonly ERROR_MINING: "errorMining"; readonly MINER_DISCONNECTED: "disconnected"; readonly CONNECTING: "connecting"; readonly SLEEP: "sleep"; readonly LOW: "low"; readonly NORMAL: "normal"; readon… ``` ### `THRESHOLD_LEVEL` **Constant** ```typescript { readonly ALERT: "alert"; readonly ALARM: "alarm"; readonly NORMAL: "normal"; readonly ALARM_LOW: "alarmLow"; readonly ALARM_HIGH: "alarmHigh"; readonly CRITICAL_LOW: "criticalLow"; readonly CRITICA… ``` ### `THRESHOLD_TYPE` **Constant** ```typescript { readonly TANK_PRESSURE: "tankPressure"; readonly OIL_TEMPERATURE: "oilTemperature"; readonly WATER_TEMPERATURE: "waterTemperature"; readonly SUPPLY_LIQUID_PRESSURE: "supplyLiquidPressure"; } ``` ### `USER_ROLE` **Constant** ```typescript { readonly ADMIN: "admin"; readonly READ_ONLY: "read_only_user"; readonly SITE_MANAGER: "site_manager"; readonly SITE_OPERATOR: "site_operator"; readonly FIELD_OPERATOR: "field_operator"; readonly RE… ``` ### `validateSettingsJson` **Function** ```typescript (data: unknown) => data is SettingsExportData ``` ### `VOTING_SUBMISSION_TYPE` Submission `type` for the voting/approval workflow. **Constant** ```typescript "voting" ``` # Core Utils (/reference/ui/utilities/utils) Core utility functions for formatting, validation, and data processing. ## Package `@tetherto/mdk-ui-foundation` ## Utilities ### `getLatestSample` Tiny projection helper used by the dashboard's header-stat hooks. **Function** ```typescript (entries: readonly T[] | null | undefined) => T | undefined ``` # Code of Conduct (/support/community/code-of-conduct) ## Our Commitment MDK is committed to fostering an open, professional, and respectful community. We welcome contributors of all backgrounds and experience levels. Participation in the MDK community should be harassment-free and inclusive for everyone. --- ## Expected Behavior All participants in the MDK community are expected to: - Be respectful and constructive in communication - Provide helpful and professional feedback - Assume good intent - Focus on what is best for the project - Accept constructive criticism gracefully --- ## Unacceptable Behavior The following behaviors are not tolerated: - Harassment, discrimination, or hateful conduct - Personal attacks or insulting language - Public or private harassment - Trolling, intimidation, or deliberate disruption - Publishing private information without consent - Any conduct that would be considered unprofessional in a workplace setting --- ## Scope This Code of Conduct applies to: - GitHub repositories - Issues and pull requests - Discussions and community channels - Official MDK communication platforms - Any other space officially associated with the MDK project --- ## Enforcement The Community Manager is responsible for enforcing this Code of Conduct. **Community Manager:** Gio\ **Lead Maintainer:** Hemant T If you experience or witness unacceptable behavior, report it privately to the Community Manager. Reports will be handled confidentially and reviewed in coordination with the MDK core team. --- ## Enforcement Guidelines The MDK core team may take any action deemed appropriate, including: - Warning the participant - Temporarily restricting access - Permanently banning a participant from the community - Removing content that violates this Code of Conduct Decisions regarding enforcement are final. --- ## Amendments This Code of Conduct may be updated from time to time by the MDK core team to reflect evolving community needs. # Contributing (/support/community/contributing) # Contribute to MDK Thank you for your interest in contributing to [MDK](https://github.com/tetherto/mdk/). This document outlines the contribution workflow for the MDK repository, from setting up your development environment to submitting pull requests and participating in releases. ## Security If you discover a security vulnerability, do not report it in a public issue. Please follow the private disclosure instructions in [SECURITY.md](https://github.com/tetherto/mdk/blob/main/SECURITY.md). ## Monorepo structure MDK is a monorepo with separate backend and frontend workspaces: - Backend: - `backend/core/`: Backend services, container modules, and integration/unit tests (npm-based) - `backend/workers/`: Protocol-translator worker packages (miners, miner-pools, power-meter, temperature, containers), per-worker mock servers, and per-worker tests (npm-based) - Frontend: `ui/`: Frontend packages, demo app, and shared UI foundation (npm + Turbo-based) Choose the backend or frontend workflow that matches the area you are contributing to. ### Root configuration must be domain-aware The repo top level is a fixed set of domains (`ui/`, `backend/`, `docs/`, `examples/`) plus tooling and repo-meta files. Shared root config (today just `.gitignore`) is read across all of them, so every pattern must be written so it cannot silently match another domain's source: - **Anchor anything that targets one domain's build or runtime output.** Use `/name/` for the repo root or `domain/**/name/` for a subtree. A bare `status` / `store` / `tmp` / `Checklist*` matches a file or directory of that name *anywhere*, including UI source. That is exactly what caused a prior root ignore regression, where bare `status` / `store` swallowed `ui/packages/ui-foundation/src/store/`. - **Keep per-domain ignores in that domain's own `.gitignore`** (`ui/.gitignore`, the per-package backend `.gitignore`s), not the root. Things like `dist`, `.turbo`, and `build` belong to a domain. - **Lint/format/type config is domain-owned, not shared at the root.** `ui/` ships its own `eslint.config.mjs` / `tsconfig.base.json` / `.prettierrc`; backend uses `standard`. Do not add a root-level eslint/tsconfig/prettier that would apply across domains. - **A genuinely shared convention is fine if it applies identically to every domain** - e.g. committing `config/*.json.example` while ignoring the generated `config/*.json`. Note it as shared so the intent is clear. ## Get started ### Prerequisites Before contributing, ensure you have the following installed: - **Node.js** (version >=24) - **Git** (latest stable version) - **npm** (version 11 or higher) ### Licensing MDK is released under the [**Apache License 2.0**](https://github.com/tetherto/mdk/blob/main/LICENSE). By contributing, you agree that: - You retain copyright over your contributions - You grant a perpetual, worldwide, royalty-free license for their use - Contributions are provided **“AS IS”**, without warranty ## Development environment setup <details> <summary>1. Fork and clone</summary> 1. Fork [the repository](https://github.com/tetherto/mdk.git) on GitHub. 2. Clone your fork locally and navigate into the project directory: ```bash git clone https://github.com/username/mdk.git cd mdk ``` 1. Add the upstream remote: ```bash git remote add upstream https://github.com/tetherto/mdk.git ``` </details> <details> <summary>2. Stay in sync</summary> Keep your fork in sync with the main repository. For example: ```bash git fetch upstream git merge --ff-only upstream/main # fails loudly if main has diverged ``` </details> ### Backend contribution setup Use this workflow when contributing to backend code under `backend/core/`. ```bash cd backend/core npm install ``` #### Common commands ```bash # Lint backend code npm run lint # Run backend test suite (lint + unit + integration + package tests) npm test ``` ### Frontend contribution setup Use this workflow when contributing to frontend code under `ui/`. ```bash cd ui npm install ``` #### Common commands ```bash # Build packages npm run build # Run dev mode (all packages + demo) npm run dev # Lint and type-check npm run lint npm run typecheck # Run tests npm test ``` ## Pull request workflow ### Conventional types MDK uses Conventional Commits-style types for both branch names and PR titles. | Type | Use for | |---|---| | `feat` | New features | | `fix` | Bug fixes | | `docs` | Documentation changes | | `refactor` | Code refactoring without behaviour change | | `test` | Test additions or changes | | `chore` | Tooling, dependencies, repo maintenance | | `perf` | Performance improvements | | `style` | Formatting only (no logic change) | | `ci` | CI configuration changes | | `build` | Build system or external dependency changes | ### Branch naming convention Create branches using the following pattern: ```bash {type}/{short-description} ``` Where `{type}` is one of the [conventional types](#conventional-types). #### Branch naming examples ```bash # New feature git checkout -b feat/mdk-new-device # Bug fix git checkout -b fix/timeout-handling ``` ### Commit message template The repository ships a commit message template at `.gitmessage` that pre-fills the commit editor with the expected format (type, summary, body, and Asana/Related PR references). Enable it once per clone: ```bash git config commit.template .gitmessage ``` This is a local convenience only — it is not enforced, and the [conventional types](#conventional-types) above remain the source of truth for commit, branch, and PR naming. ### Pull request steps 1. Sync your local main with upstream `main`. 2. Create a branch from local `main`. 3. Make your code changes. 4. Write or update tests. 5. Run linting and tests locally in the workspaces you changed: - `core`: `npm run lint && npm test` - `ui`: `npm run lint && npm test` (and `npm run typecheck` for TypeScript changes) 6. Commit changes with meaningful messages. 7. Push your branch and open a Pull Request targeting the upstream `main`. ### PR checklist Before submitting your PR, ensure that: - [ ] Code builds locally (`npm run build` for `ui` changes) - [ ] Tests pass in affected workspaces (`npm test`) - [ ] Linting passes (`npm run lint`) - [ ] Type-check passes for frontend TypeScript changes (`npm run typecheck`) - [ ] New features include tests - [ ] Public behavior or APIs changes have a [`docs-needed` issue](https://github.com/tetherto/mdk/issues/new?template=docs-needed.yml) linked to the PR ### PR title format Use the following convention: ```bash {type}({scope}): {description} ``` Where `{type}` is one of the [conventional types](#conventional-types) and `{scope}` is the affected area, for example `miner` or `ui`. Examples: - `feat(miner): add Antminer S21 support` - `fix(timeout): resolve action timeout handling` - `docs(api): update stats documentation` ## PR review All pull requests go through the following review steps: 1. **Automated checks**: Linting and tests must pass. 2. **Code review**: At least 2 maintainer approvals are required. 3. **Feedback resolution**: All requested changes must be addressed. 4. **Squash and merge**: Maintainers squash commits to keep history clean. ### Workflow diagram ```mermaid flowchart TB subgraph contributor [Contributor] start((Start)) --> createBranch[Create branch from main] createBranch --> test[Run tests] test --> testGw{Tests pass?} testGw -->|No| fix[Fix issues] fix --> test testGw -->|Yes| createPR[Create PR] createPR --> review address[Address feedback] --> pushFixes[Push fixes] pushFixes --> test end subgraph reviewer [Reviewer / Maintainer] review[Code review] reviewGw{Approved?} review --> reviewGw reviewGw -->|Request changes| address reviewGw -->|Rejected| cancel[Close PR] reviewGw -->|Approved| merge[Merge to main] merge --> tagGw{Tag release?} tagGw -->|No| endNoTag((End)) tagGw -->|Yes| tag[Tag version] tag --> deploy[Deploy] deploy --> deployGw{Deploy success?} deployGw -->|Yes| endSuccess((End)) deployGw -->|No| rollback[Rollback] rollback --> fix end ``` ## Code standards MDK uses **StandardJS** style to keep the codebase consistent and easy to review across repositories. Key rules: - 2-space indentation - No semicolons - Single quotes for strings - Space after keywords (`if`, `for`, `while`) - No unused variables ## Versioning and tagging MDK follows **Semantic Versioning**: - **MAJOR** (`1.x.x`): breaking changes - **MINOR** (`x.1.x`): new backward-compatible features - **PATCH** (`x.x.1`): backward-compatible bug fixes When the MDK team provides a release, they are cut from a `release/<version>` branch, verified in CI, promoted to the public repo, then tagged. For the full release process and checklist, see RELEASING.md. Happy contributing, and thanks for helping improve MDK! 🚀 # Governance (/support/community/governance) This document describes how the MDK project is governed and how decisions are made. MDK is an open-source project. While the code is publicly available and community contributions are welcome, final decision-making authority rests with the MDK core team. --- ## Project Roles ### Users Anyone who uses MDK and provides feedback, bug reports, or feature requests. ### Contributors Community members who contribute code, documentation, tests, or other improvements via pull requests or issues. Contributors do not have merge access. --- ### Maintainers Maintainers are responsible for reviewing pull requests, maintaining code quality, and ensuring alignment with the project roadmap. Maintainers may be appointed by the Lead Maintainer. The following GitHub IDs currently hold maintainer status for MDK: - arif-dewi - eugeneglova - robdll - eskawl - boris91 - habrahamyanbf - efr-nox - rob-aslanian - mukama - paragmore - tekwani Only the GitHub accounts listed above have maintainer privileges within the MDK repositories. Maintainer status is granted based on demonstrated technical expertise, sustained contribution, and alignment with project goals. --- ### MDK core team The MDK Core Team consists of all active developers, the Project Manager, and the Community Manager. The Core Team is responsible for the overall health, sustainability, and long-term success of the project. While specific authorities are defined for the Lead Maintainer (technical) and the Community Manager (strategic), the Core Team operates as the primary collaborative decision-making body. ### Lead Maintainer **Hemant T** is the Lead Maintainer and Technical Lead for MDK. The Lead Maintainer has final authority over: - Pull request approval and merging - Architecture and design decisions - Release planning and versioning - Accepting or rejecting features - Appointing or removing maintainers If consensus cannot be reached among maintainers, the Lead Maintainer makes the final decision. --- ### Community Manager **Gio** is the Community Manager for MDK. The Community Manager is responsible for: - Managing community communication channels - Moderating discussions and enforcing the Code of Conduct - Supporting contributors during onboarding - Acting as a bridge between the community and the MDK core team - Defining, maintaining, and communicating the project vision and long-term direction - Leading roadmap prioritization and strategic planning --- ## Decision-Making Process - Community members may propose changes via issues or pull requests - Maintainers review contributions for quality, security, and alignment with MDK goals - The Lead Maintainer has final approval authority on all technical decisions - Strategic, roadmap, or breaking changes are determined by the MDK core team - The Community Manager has final decision-making authority over all strategic and directional matters, including project vision, roadmap prioritization, major feature introductions, partnerships, and significant pivots - In cases where strategic direction and technical considerations intersect, the Community Manager determines the final strategic outcome, while the Lead Maintainer determines the final technical implementation approach. --- ## Contribution Review Process - All contributions must follow `CONTRIBUTING.md` - Pull requests require review by a maintainer - Final approval and merge is performed by the Lead Maintainer - The MDK team reserves the right to decline contributions that do not align with the project direction --- ## Inactivity and Removal Maintainers who become inactive for an extended period or violate project policies may be removed by the Lead Maintainer. --- ## Code of Conduct All participants are expected to follow the project's Code of Conduct. Violations are handled by the Community Manager in coordination with the MDK core team. See [Code of Conduct](/support/community/code-of-conduct) for details. --- ## Changes to Governance This governance model may evolve over time. Any changes will be proposed and approved by the MDK core team. # MDK Repositories (/support/resources/repositories) The MDK monorepo makes the frontend and backend components publicly accessible: - [https://github.com/tetherto/mdk](https://github.com/tetherto/mdk) *MDK is developed by Tether and released under the [Apache 2.0 license](/support/community/contributing#licensing).* # Roadmap (/support/resources/roadmap) MDK follows a **two-week release cadence** to keep progress visible, collect feedback early, and progressively harden the platform — from a rudimentary end-to-end foundation toward a production-ready release. ## Release principles - **Release every two weeks** to keep momentum and feedback loops short - **Use four maturity phases** to mark clear readiness jumps - **Start with a working end-to-end developer experience**, then harden progressively - **Reach production readiness progressively**, not by a single large release - **Follow standard [semantic versioning](https://semver.org)** — the `0.x` line means MDK is still in development and not intended for production ## Versioning and naming strategy MDK uses standard [semantic versioning](https://semver.org) (`MAJOR.MINOR.PATCH`): - A **new version ships every two weeks**, bumping the **minor**: `0.2.0` → `0.3.0` → `0.4.0` → … - **Patch** releases (`0.x.1`) go out only when a fix is needed between the scheduled releases, e.g. 0.2.1 - While MDK is in the **`0.x` line**, interfaces may change and the platform is **not intended for production** — this is the standard semver signal, and we use it deliberately so developers can read it literally - **`1.0.0`** marks the first **production-ready** release Maturity is tracked by **phase**, not by version number — each phase spans several bi-weekly releases. The four phases describe how ready MDK is at each stage: | Phase | Production-readiness | |---|---| | **Foundation** | Experimental. End-to-end but rudimentary. Not stable. | | **Lab testing** | Complete enough to build against end-to-end, in a lab. Not stable, not for production. | | **On site testing** | Stable enough to test at real sites under real operating conditions, closely monitored. Not yet production-ready. | | **Production Ready** | Ready for production deployment, with stable interfaces and compatibility guarantees. | ## 2026 2026 moves MDK through **four phases**: - **May:** [Foundation](#foundation) - **July:** [Lab testing](#lab-testing) - **October:** [On site testing](#on-site-testing) - **December:** [Production Ready](#production-ready) Between phases, MDK ships a new release **every two weeks**, starting from the Foundation release at the end of May. The diagram below shows only the phase milestones; the bi-weekly releases land in the windows between them. ```mermaid graph TB subgraph foundation [Foundation] p1([May 2026<br/><b>Foundation</b><br/>Public, end-to-end but rudimentary]) it1[[Jun–Jul 2026<br/>New release every 2 weeks]] end subgraph lab [Lab testing] p2([Jul 2026<br/><b>Lab testing</b><br/>Complete end-to-end, lab only]) it2[[Aug–Oct 2026<br/>New release every 2 weeks]] end subgraph onsite [On site testing] p3([Oct 2026<br/><b>On site testing</b><br/>Testing at real sites]) it3[[Nov–Dec 2026<br/>New release every 2 weeks]] end subgraph prod [Production Ready] p4([Dec 2026<br/><b>Production Ready</b><br/>Production-ready baseline]) end p1 --> it1 --> p2 --> it2 --> p3 --> it3 --> p4 style foundation fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A style lab fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A style onsite fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A style prod fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A ``` ## Release plan Phase descriptions below focus on the **level of maturity and production-readiness** at each stage. The exact feature scope of each two-week release is decided as we go and is not fixed by this roadmap. ### Foundation *Released end of May 2026.* The first public release is about **visibility, direction, and feedback**. It is intentionally rudimentary: developers can clone it, run an end-to-end example, and get a concrete feel for how MDK fits together. Interfaces are expected to change. The goal is to show where MDK is heading and invite feedback from developers, partners, and early contributors — not to support real workloads. ### Lab testing *Target: end of July 2026.* At this stage MDK is **complete enough to build against end to end**. Developers can run a full workflow and experiment with MDK in their own labs. It is **not stable** — breaking changes are still expected between releases — and it is **not ready for production**. The goal is to validate the end-to-end developer workflow and surface integration gaps before MDK is exposed to real operational conditions. ### On site testing *Target: end of October 2026.* This is the first stage intended for **testing at real sites**. MDK should be stable enough to run on site under real operating conditions, while still being monitored closely. The goal is to validate performance, robustness, deployment workflows, and operational fit in real scenarios. This is not yet a stability commitment — interfaces may still change before production readiness. ### Production Ready *Target: end of December 2026.* This is the first **production-ready** release (`1.0.0`). By this point MDK offers a solid baseline for production deployment, with stable core interfaces, validated workflows, and documentation that supports adoption by operators, integrators, and developers building on top of the platform. From here, standard semver compatibility guarantees apply. # Tutorials (/tutorials) ## New to MDK? Go from stack to dashboard Three short tutorials take you from a running MDK stack to a browser dashboard demo. First you watch the stack run, then you drive it from the CLI, then you launch the demo dashboard on top. Climb straight through, or jump to the rung you need. <Cards className="grid-cols-1 md:grid-cols-3"> <Card icon={<Play />} className="@max-lg:col-span-1" title={<span style={cardTitle}>1. Run the stack</span>} href="/tutorials/backend-stack/run" description={ <span style={cardProse}> <strong>Observe</strong> — one command brings up Kernel with a mock device registered </span> } /> <Card icon={<Terminal />} className="@max-lg:col-span-1" title={<span style={cardTitle}>2. Control from the CLI</span>} href="/tutorials/backend-stack/cli" description={ <span style={cardProse}> <strong>Interact</strong> — drive a running stack from a REPL over IPC </span> } /> <Card icon={<LayoutDashboard />} className="@max-lg:col-span-1" title={<span style={cardTitle}>3. Run a dashboard demo</span>} href="/tutorials/full-stack/dashboard" description={ <span style={cardProse}> <strong>Demo</strong> — run a React dashboard with live charts on the stack </span> } /> </Cards> ## Get started with your framework <Cards> <Card icon={<Atom />} title={<span style={cardTitle}>React</span>} href="/tutorials/ui/react" description={ <span style={cardProse}> Pick a path: lean Quickstart, full Tutorial, or browse the component packages </span> } /> <Card icon={<Bot />} title={<span style={cardTitle}>Build with your AI agent</span>} href="/quickstart/connect-agents" description={ <> <span style={cardProse}> Reactive hooks for Vue </span> </> } /> </Cards> ## Next steps - Learn more about the high-level [architecture](/concepts/architecture): runtime stack and deployment modes - Compare [deployment topologies](/concepts/deployment-topologies): single process or supervised services - Run a site from the [deployment guides](/guides/deployment) - [Contribute](/support/community/contributing) # Backend stack tutorials (/tutorials/backend-stack) <Callout type="idea"> See the [whole stack demo at once](/tutorials/quickstart/full-stack) booting all the Worker families for a live site, mock hardware, a Gateway API, and a React dashboard in one command. </Callout> ## Overview This page presents three short tutorials that build on each other. Each rung adds one layer of capability: first you watch the stack run, then you drive it, then you run a browser demo on top. | Rung | You'll | You'll end with | Mock hardware | Time | |---|---|---|---|---| | [1. Run the stack](/tutorials/backend-stack/run) | **Observe** — run one command and watch a stack come up | Device list, telemetry, and commands printed | Whatsminer M56S | `< 3 min` | | [2. Control devices from the CLI](/tutorials/backend-stack/cli) | **Interact** — drive a running stack from a REPL | Live telemetry and commands over HRPC via the kernel key file | Whatsminer M56S | `< 3 min` | | [3. Run the dashboard demo](/tutorials/full-stack/dashboard) | **Run** — launch a browser dashboard on the stack | A React dashboard with live charts at `:3030` | Whatsminer M56S | `< 15 min` after a one-time UI build | **New to MDK? Start with [1. Run the stack](/tutorials/backend-stack/run).** Each rung links to the next, so you can climb straight through. <Callout type="info"> All three rungs use the same Whatsminer example to keep things simple. To see MDK working with different hardware, check out the [full site example](/tutorials/quickstart/full-stack) which runs multiple Worker families (Antminers, Whatsminers, containers, power meters) simultaneously — all using the same MDK API. </Callout> Each rung is self-contained and repeats the clone-and-install step, so you can start at whichever one you need. ## Next steps - If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary) - Build the [smallest version of the full MDK stack: **one Worker, one Gateway route, one static HTML page](/tutorials/quickstart/build-a-dashboard) - Run the [full stack demo](/tutorials/quickstart/full-stack) # 2. Control from CLI (/tutorials/backend-stack/cli) *Get started · 2 of 3 · Control devices from the CLI* <Callout type="info"> If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary) first. </Callout> ## Overview This is rung 2 of the [Get started](/tutorials/backend-stack) ladder: **interact**. It walks the shortest path from a fresh clone to a fully wired MDK stack you can drive interactively from a CLI. Everything runs in one Node process, no real hardware required. What you'll have at the end: - A mock Whatsminer M56S serving telemetry on `127.0.0.1:14028` - An Kernel with one Worker registered and one device discovered - An interactive `client.js` REPL talking to Kernel over HRPC — pull metrics, list Workers, send commands like `reboot` and `setpower` - (Optional) A Gateway HTTP API on `:3000` so non-Node consumers (browsers, AI agents over MCP) can hit the same stack over REST <Callout type="info"> Same shape as [rung 1](/tutorials/backend-stack/run): the stack still boots with `getKernel()`, `startWhatsminerWorker()`, and `kernel.registerWorker()`. What's new here is a second process — `client.js` — that connects over HRPC (using the key Kernel publishes to its key file) and drives the running stack. </Callout> The example lives in [`examples/backend/mdk-e2e/`](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md#end-to-end-mdk-e2e) and contains six runnable scripts. This tutorial uses three of them: `run.js` for a smoke test, `server.js` for the long-running stack, and `client.js` for interactive control. ## Prerequisites - Node.js >=24 (LTS) - npm >=11 <Callout type="warn"> HRPC relies on HyperDHT for peer connectivity, including when Kernel and the Worker share a process. Review the [network requirements and checks](/guides/miners/troubleshooting#example-does-not-print-a-kernel-key) if startup stalls. </Callout> <Steps> <Step> ### Clone and install #### 1.1 Clone the repo ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` #### 1.2 Install dependencies The monorepo has two workspaces with their own dependency trees. Install both: ```bash backend/core/install-packages.sh ci backend/workers/install-packages.sh ci ``` <Callout type="info"> Each script walks every `package.json` under its workspace and runs `npm ci`. The `examples/mdk-e2e/` package is included automatically — no extra install step needed. </Callout> </Step> <Step> <details> <summary>(1.3 Optional) Smoke test the stack</summary> Before going interactive, prove the wiring works. `run.js` starts a mock Whatsminer + Worker + Kernel in one process, exercises a few queries, prints the results, and exits cleanly: ```bash node examples/backend/mdk-e2e/run.js ``` Expected output (the UUID and metric values vary): ```text Devices: [ '8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b [miner-wm-m56s]' ] Telemetry: ONLINE hashrate=170000 power=3500W Commands: reboot, setPowerMode, setLED, setPowerPct, setupPools, saveComment ``` If you see those three lines, every layer is working: the mock is responding, the Worker registered the device with Kernel directly in-process (no DHT lookup), and envelope routing is delivering messages both ways. The script tears itself down and exits with code 0. <Callout type="warn"> If the smoke test fails with `EADDRINUSE` on port 14028, a previous run left a Node process alive. Kill stragglers with `pkill -f mdk-e2e` and retry. </Callout> </details> </Step> <Step> ### Run the interactive demo #### 3.1 Start the stack In your terminal: ```bash node examples/backend/mdk-e2e/server.js ``` `server.js` starts the same mock + Worker + Kernel as `run.js`, but stays running and prints the IDs you'll need: ```text Kernel key: 7a4c8b...e3f0 Device: 8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}' hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}' Ctrl+C to stop. ``` The `Kernel key` is a 64-char hex public key. `Device` is a UUIDv4 generated at registration time. Both vary per run — note the device UUID for the next step. The two `hp-rpc-cli` lines are paste-ready commands for inspecting Kernel over HRPC from another machine. You don't need them for this tutorial — they're there if you have [`hp-rpc-cli`](https://github.com/holepunchto/hp-rpc-cli) installed and want to go off-script. #### 3.2 Connect the interactive client Open a second terminal in the same `mdk` directory: ```bash node examples/backend/mdk-e2e/client.js ``` `client.js` reads the Kernel key from the key file Kernel published at startup (`os.tmpdir()/mdk/.kernel-key` — or pass a key as the first argument), connects over HRPC, and gives you an MDK REPL: ```text Client — connected to Kernel over HRPC: 7a4c8b… Type "help" for commands, "quit" to exit. mdk> ``` #### 3.3 Drive the stack 3.3.1 Discover the telemetry of your (mock) device by entering commands at the `mdk>` prompt, substituting `<deviceId>` with the UUID printed in Step 3.1: ```text mdk> metrics <deviceId> ``` Each command builds an MDK Protocol envelope, sends it to Kernel over HRPC, and prints the JSON response. 3.3.2 Try changing the power mode and observing the effect: ```text mdk> setpower <deviceId> low mdk> metrics <deviceId> ``` After `setpower ... low` the second `metrics` call should reflect the power mode change. <details> <summary>Full command reference</summary> **Reads** ```text workers — list workers list [deviceId] — list devices count [deviceId] — device count metrics <deviceId> — live telemetry from hardware logs <deviceId> — recent logs settings [deviceId] — worker settings stats [deviceId] — fleet stats config <deviceId> — device config (pools, etc.) capabilities <deviceId> — mdk-contract capabilities state [deviceId] — worker state snapshot ``` **Commands** ```text reboot <deviceId> — reboot miner setpower <deviceId> <mode> — set power mode (normal/low/high) setled <deviceId> [on|off] — toggle LED ``` ```text quit / exit — exit client ``` </details> #### 3.4 Tear down When you're done, exit the client and stop the stack: ```text mdk> quit ``` Then `Ctrl+C` in Terminal 1. </Step> <Step> ### 4 (Optional) enable Gateway for HTTP access In **Terminal 1**, `Ctrl+C` the running stack, then restart with `--gateway`: ```bash node examples/backend/mdk-e2e/server.js --gateway ``` You'll see an extra line in the startup banner: ```text Gateway: http://localhost:3000 (noAuth mode) ``` Confirm it's alive — Gateway has no index page, so hit `/auth/site` directly: ```bash curl http://localhost:3000/auth/site ``` You should see something like `{"site":"Site_Name"}`. <Callout type="warn"> In `noAuth` mode, routes that call `services.authLib` (`/auth/miners`, `/auth/permissions`) crash with `Cannot read properties of undefined` because `authLib` is never instantiated. Routes that call `services.dataProxy` (`/auth/list-things`) fail with `UNKNOWN_METHOD` because the underlying RPC method requires the full DCS cluster registration that the production Gateway service provides. Use `/site-monitor/workers` and `/site-monitor/hashrate` for local inspection — those routes call `services.mdkClient` directly over HRPC and work without auth. </Callout> <Callout type="warning"> `--gateway` runs in `noAuth` mode for development convenience. Do not expose port 3000 outside localhost. </Callout> </Step> </Steps> ## What just happened Your stack wired up, in order: 1. **Mock device**:`server.js` calls `wmMock.createServer({ port: 14028, ... })` — an HTTP server speaking the Whatsminer protocol with canned telemetry. 2. **Kernel**: `getKernel()` boots the kernel, generates a random DHT topic, and publishes its HRPC public key to the well-known key file (`os.tmpdir()/mdk/.kernel-key`). 3. **Worker**: `startWhatsminerWorker({ ..., seedDevices })` constructs a `WorkerRuntime` seeded with one device at `127.0.0.1:14028` and starts it. 4. **Registration**: `kernel.registerWorker(worker.runtime.getPublicKey())` registers the Worker with Kernel directly — no DHT round-trip because they share the process. 5. **Client**: `client.js` reads the key file from a second process, connects over HRPC, and sends MDK Protocol envelopes (`worker.list`, `telemetry.pull`, `command.request`, ...). Kernel routes them to the Worker, the Worker hits the mock, and the response flows back over HRPC. <Callout type="info"> No Gateway here? Right. Gateway is the translator that lets non-Node consumers — browser UIs, AI agents over MCP — speak MDK Protocol to Kernel. `client.js` already speaks MDK Protocol over HRPC, so it talks to Kernel directly. Gateway becomes mandatory only when the consumer can't speak HRPC. See [`architecture.md#gateway`](/concepts/architecture#gateway). </Callout> ## Cleanup `Ctrl+C` in Terminal 1 stops the Worker, Kernel, and mock cleanly. `run.js` deletes its own state directory on exit. `server.js` leaves data under `os.tmpdir()/mdk/` — safe to ignore, or remove with: ```bash rm -rf "$TMPDIR/mdk" /tmp/mdk ``` ## Continue Next: [3. Run the dashboard demo](/tutorials/full-stack/dashboard): put a browser dashboard on a running stack with live charts. ## Go deeper - Walk the simpler single-script path: [1. Run the stack](/tutorials/backend-stack/run) - Run a [full site (multiple Workers and devices):](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-site/site.js) - Understand the [install pattern for any Worker](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md) - Read all [runnable examples in one place](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md) # 1. Run the stack (/tutorials/backend-stack/run) *Get started · 1 of 3 · Run the stack* <Callout type="info"> If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary) first. </Callout> ## Overview This is rung 1 of the [Get started](/tutorials/backend-stack) ladder: **observe**. It walks the shortest path from a fresh clone to a running Kernel with one mock Whatsminer registered, no hardware required. Everything runs in one Node process. What you'll have at the end: - A mock Whatsminer M56S serving telemetry on `127.0.0.1:14028` - An Kernel started and aware of one registered device - Device list, telemetry, and available commands printed to the terminal ## Prerequisites - Node.js >=24 (LTS) - npm >=11 <Callout type="warn"> HRPC relies on HyperDHT for peer connectivity, including when Kernel and the Worker share a process. Review the [network requirements and checks](/guides/miners/troubleshooting#example-does-not-print-a-kernel-key) if startup stalls. </Callout> <Steps> <Step> ### Clone and install #### 1.1 Clone the repo ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` #### 1.2 Install dependencies The monorepo has two workspaces with their own dependency trees. Install both: ```bash backend/core/install-packages.sh ci backend/workers/install-packages.sh ci ``` <Callout type="info"> Each script walks every `package.json` under its workspace and runs `npm ci`. </Callout> </Step> <Step> ### Run the example ```bash node examples/backend/mdk-e2e/run.js ``` Expected output: ```text Devices: [ 'WM-001 [miner-wm-m56s]' ] Telemetry: mining hashrate=295764693.45 power=4000W Commands: reboot, setPowerMode, setLED, setupPools, setPowerPct, setUpfreqSpeed, registerThing, updateThing, forgetThings, saveSettings, saveComment, editComment, deleteComment ``` If you see those three lines, the whole stack is up: mock device responding, Worker registered, Kernel started and aware of the device. The script queries the device and then exits cleanly. <Callout type="warn"> If the example fails with `EADDRINUSE`, a previous run left port 14028 bound. Kill stale Node processes with `pkill -f mdk-e2e` and retry. </Callout> </Step> </Steps> ## What just happened Here is what `run.js` does — the minimum runnable shape for an MDK stack: ```js const { getKernel, waitForDiscovery } = require('../../../backend/core/mdk') const { createMdkClient } = require('../../../backend/core/client') const { startWhatsminerWorker } = require('../../../backend/workers/miners/whatsminer') const wmMock = require('../../../backend/workers/miners/whatsminer/mock/server') // Start a mock Whatsminer M56S on port 14028 wmMock.createServer({ port: 14028, host: '127.0.0.1', type: 'm56s', serial: 'WM-001', password: 'admin' }) // Start the Whatsminer Worker with one seeded device const worker = await startWhatsminerWorker({ workerId: 'whatsminer-m56s-e2e', model: 'm56s', storeDir: path.join(ROOT, 'worker-store'), kernelTopic: TOPIC, seedDevices: [{ id: 'WM-001', info: { serialNum: 'WM-001' }, opts: { address: '127.0.0.1', port: 14028, password: 'admin' } }] }) // Start Kernel — discovers the Worker via DHT const kernel = await getKernel({ root: ROOT, topic: TOPIC }) await waitForDiscovery(kernel) // Connect an MDK client over HRPC const client = createMdkClient({ hrpc: { key: kernel.getPublicKey() } }) await client.connect() // Query the device and print results const list = await client.pullTelemetry(deviceId, 'list') const tel = await client.pullTelemetry(deviceId, 'metrics') const caps = await client.getCapabilities(deviceId) ``` Six steps, in order: 1. **Starts a mock miner.** `wmMock.createServer({ port: 14028, type: 'm56s', serial: 'WM-001', password: 'admin' })` binds port 14028 with a Whatsminer-compatible API serving canned telemetry. 2. **Starts a Worker.** `startWhatsminerWorker({ ...seedDevices })` instantiates the Whatsminer manager and seeds it with one device registration at `127.0.0.1:14028`. The Worker stores the registration and begins polling the mock. 3. **Starts Kernel.** `getKernel({ topic })` brings up the kernel and joins the DHT topic. It discovers the Worker and pulls its identity and capabilities. 4. **Waits for discovery.** `waitForDiscovery(kernel)` blocks until the Worker appears in Kernel's registry. 5. **Connects a client.** `createMdkClient({ hrpc: { key: kernel.getPublicKey() } })` creates an MDK Protocol client that speaks to Kernel over HRPC. 6. **Queries and prints.** The script pulls device list, telemetry, and capabilities, prints them, cleans up, and exits. <Callout type="info"> No Gateway here? Right. Gateway is the translator that lets non-Node consumers — browser UIs, AI agents over MCP — speak MDK Protocol to Kernel. This script holds the Kernel handle in-process and speaks MDK Protocol to it directly. See [`architecture.md#gateway`](/concepts/architecture#gateway) for when Gateway is mandatory. </Callout> ## Cleanup The script cleans up automatically on exit. Temporary data lives at `os.tmpdir()/e2e-run/` and is removed by the script. If needed, you can manually clean with: ```bash rm -rf "$TMPDIR/e2e-run" /tmp/e2e-run ``` ## Continue Next: [2. Control devices from the CLI](/tutorials/backend-stack/cli) — keep a stack running and drive it interactively (Whatsminer plus an MDK REPL). ## Next steps - Try different miner hardware — the same MDK API works with [Antminers](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/USAGE.md), [Avalonminers](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md), and more - Run a full site (5 Workers, 26 devices) — [`examples/backend/mdk-site/site.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-site/site.js) - See Kernel and a Worker as separate OS processes — [`dht-worker.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-e2e/dht-worker.js) + [`dht-kernel.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-e2e/dht-kernel.js) + [`client.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-e2e/client.js) - Understand the install pattern for any Worker — [`backend/workers/docs/install-pattern.md`](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md) - Read all runnable examples in one place — [`examples/backend/README.md`](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md) # Run a demo from stack to dashboard (/tutorials/full-stack/dashboard) *Get started · 3 of 3 · Run the dashboard demo* <Callout type="info"> If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary) first. </Callout> ## Overview This is rung 3 of the [Get started](/tutorials/backend-stack) ladder: **run**. It puts a real browser dashboard on top of the stack you already know, using the [`mdk-site-monitor`](https://github.com/tetherto/mdk/tree/main/examples/e2e) example. What you'll have at the end: - The same mock Whatsminer M56S stack from [rung 2](/tutorials/backend-stack/cli), fronted by a Gateway REST API on `:3000` - A React dashboard on `:3030` — total hashrate, total power, and active device count as metric cards, a live hashrate chart, and a per-device breakdown - The dashboard polling Gateway every 5 seconds, built entirely from MDK UI components (`MetricCard`, `HashRateLineChart`, `Typography`, ...) <Callout type="info"> Same shape as rungs 1 and 2: underneath, the stack still boots with `getKernel()`, `startWhatsminerWorker()`, and `kernel.registerWorker()`, and the device is the same Whatsminer M56S mock as [rung 2](/tutorials/backend-stack/cli). What's new is two layers on top — Gateway translating MDK Protocol to REST, and a Vite React UI consuming that REST. </Callout> ## Prerequisites - Node.js >=24 (LTS) - npm >=11 <Callout type="warn"> HRPC relies on HyperDHT for peer connectivity, including when Kernel and the Worker share a process. Review the [network requirements and checks](/guides/miners/troubleshooting#example-does-not-print-a-kernel-key) if startup stalls. </Callout> <Steps> <Step> ### Clone and install the stack #### 1.1 Clone the repo ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` #### 1.2 Install dependencies ```bash backend/core/install-packages.sh ci backend/workers/install-packages.sh ci ``` </Step> <Step> ### Build the UI packages (one time) The dashboard imports pre-built MDK UI packages from `ui`. Build them once: ```bash cd ui npm install npm run build cd - ``` <Callout type="info"> This is the slow step — it compiles the UI workspace. You only do it once; re-running the dashboard later skips straight to the next step. </Callout> </Step> <Step> ### Install the dashboard's dependencies ```bash cd examples/e2e/ui npm install cd - ``` </Step> <Step> ### Start everything `start.js` is an interactive launcher. From the repo root: ```bash node examples/e2e/start.js ``` It prints the available services and a prompt. Type `start all` to launch the backend and UI together: ```text mdk> start all ``` This starts: 1. **Gateway** (`server.js --gateway`) — Kernel + mock Whatsminer + a REST API on `http://localhost:3000`, in `noAuth` mode 2. **UI** — a Vite dev server on `http://localhost:3030`, launched with `VITE_NO_AUTH=true` so it skips the login screen Wait a few seconds for both to come up, then open: ```text http://localhost:3030 ``` You'll see the dashboard populate within ~5 seconds (its first poll), then update live. Other launcher commands: ```text status — show running services and their URLs stop [kernel|gateway|ui|all] — stop a service (default: all) start [kernel|gateway|ui|all] — start a service (default: all) help — show usage exit — stop everything and quit ``` <Callout type="warning"> `start all` runs Gateway in `noAuth` mode for development convenience. Do not expose port 3000 outside localhost. </Callout> </Step> </Steps> ## What you'll see ```mermaid flowchart TD mock["Mock Whatsminer M56S (TCP :14028)"] --> worker["MDK Worker"] worker --> kernel["Kernel (HRPC)"] kernel --> gateway["Gateway (HTTP :3000)"] gateway -->|"GET /site-monitor/hashrate every 5s"| ui["Dashboard (Vite :3030)"] ``` The page renders three metric cards (Total Hashrate in TH/s, Total Power in W, Active Devices), a live hashrate line chart that grows as new data points arrive, and a per-device table. All of it comes from `@tetherto/mdk-react-devkit` components driven by the `@tetherto/mdk-react-adapter` data hooks — no hand-rolled UI. See [`SiteHashratePage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/e2e/ui/src/SiteHashratePage.tsx) for the page source. ## Cleanup At the launcher prompt: ```text mdk> exit ``` `exit` stops Gateway, the mock, Kernel, and the UI dev server. `server.js` leaves data under `os.tmpdir()/mdk-e2e/` — safe to ignore, or remove with: ```bash rm -rf "$TMPDIR/mdk-e2e" /tmp/mdk-e2e ``` <details> <summary>Add real auth (Google OAuth)</summary> The `start all` shortcut above runs in `noAuth` mode so you can see the dashboard immediately. To exercise the real authentication flow — a Google sign-in that issues a bearer token the dashboard sends on every request — configure OAuth and start the services without the `noAuth` shortcut. **1. Create a Google OAuth 2.0 client** 1. Go to [Google Cloud Console API credentials](https://console.cloud.google.com/apis/credentials) 2. Create an **OAuth 2.0 Client ID** (type: *Web application*) 3. Add to **Authorized redirect URIs**: `http://localhost:3000/oauth/google/callback` 4. Add to **Authorized JavaScript origins**: `http://localhost:3030` 5. Copy the **Client ID** and **Client Secret** **2. Configure Gateway** Edit `backend/core/gateway/config/facs/httpd-oauth2.config.json` (copy from `.example` if it doesn't exist) and fill in your client ID and secret: ```json { "h0": { "method": "google", "credentials": { "client": { "id": "<YOUR_CLIENT_ID>", "secret": "<YOUR_CLIENT_SECRET>" } }, "startRedirectPath": "/oauth/google", "callbackUri": "http://localhost:3000/oauth/google/callback", "callbackUriUI": "http://localhost:3000", "users": [] } } ``` **3. Set yourself as super-admin** In `backend/core/gateway/config/facs/auth.config.json`, set `superAdmin` to your Google account email: ```json { "a0": { "superAdmin": "you@example.com" } } ``` **4. Run with auth** Start Gateway and the UI without the `VITE_NO_AUTH` shortcut (run them directly rather than via `start all`), open `http://localhost:3030`, click **Sign in with Google**, and authorise with the super-admin email. The dashboard then shows live data behind the token. For the full setup, see the example's [`README.md`](https://github.com/tetherto/mdk/tree/main/examples/e2e). </details> ## Continue Previous: [2. Control devices from the CLI](/tutorials/backend-stack/cli) You've climbed the whole ladder: observed a stack, driven it from a CLI, and built a live UI on it. ## Go deeper - The [full example, including the OAuth setup and how to add a new data panel](https://github.com/tetherto/mdk/tree/main/examples/e2e) - Learn more about [MDK UI toolkit (components, hooks, theming)](https://github.com/tetherto/mdk/blob/main/ui/README.md) - [Run a full site (multiple Workers and devices)](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-site/site.js) - Read [all runnable examples in one place](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md) # Build a minimal single-page dashboard (/tutorials/quickstart/build-a-dashboard) # Build a minimal single-page dashboard [`examples/full-site`](https://github.com/tetherto/mdk/tree/main/examples/full-site) is the fullest demonstration of the MDK stack: multiple Worker processes spanning miners, containers, power meters, sensors, and miner pools, plus a multi-page React + Vite dashboard built on `@tetherto/mdk-react-devkit`. That breadth is the point of that example — but it also means it's a lot to read through if all you want is to understand (or prototype against) the actual wiring: Kernel, one Worker, a Gateway route, a page that polls it. This guide builds the smallest version of that same shape: **one Worker, one Gateway route, one React page**. It teaches the same end-to-end shape as `examples/full-site` — including its UI layer, `@tetherto/mdk-react-devkit` components driven by `@tetherto/mdk-react-adapter` hooks — without that example's family-specific adapters, persistence, history, commands, multi-page router, or chart aggregation. <Callout type="info"> If **Kernel**, **Worker**, or **Gateway** are unfamiliar terms, read [the architecture overview](/concepts/architecture) first. This tutorial also assumes you've skimmed [Build a third-party Worker](/guides/workers/build-a-worker) — the one Worker used here is [`backend/workers/samples/demo-worker`](https://github.com/tetherto/mdk/blob/main/backend/workers/samples/demo-worker/index.js), the same zero-dependency reference Worker that tutorial is built around. </Callout> ## Overview This tutorial builds the smallest version of the full MDK stack: **one Worker, one Gateway route, one React page**. What you'll have at the end: ```text examples/minimal-dashboard/ package.json start.js # boots Kernel + the one Worker + Gateway, one process plugins/ dashboard/ mdk-plugin.json # one route: GET /overview controllers/ overview.js # lists every Worker's devices + live telemetry ui/ package.json tsconfig.json vite.config.ts index.html src/ main.tsx # <MdkProvider> + render OverviewPage OverviewPage.tsx # polls /overview, renders devkit components ``` No router, no charts, no hand-rolled CSS — one page built from three `@tetherto/mdk-react-devkit` primitives (`LabeledCard`, `DataTable`, `Badge`) and one `@tetherto/mdk-react-adapter` hook (`useQuery`), the same building blocks `examples/full-site/ui` uses, minus the parts (router, sidebar, line charts, domain panels) this single-page, single-Worker dashboard doesn't need. ## Prerequisites - Node.js `>=24` - This repo checked out, with the backend and UI dependencies installed once from the repository root: ```bash npm run setup:core npm run setup:workers npm run setup:ui npm run build:ui ``` Running `npm run setup` from `examples/full-site` is also supported, but it is broader: it installs these backend and UI dependencies plus the full-site example and UI dependencies and builds the UI packages. - Commands below assume a new `examples/minimal-dashboard/` directory alongside `examples/full-site/` <Steps> <Step> ### Pick the Worker Use [`backend/workers/samples/demo-worker`](https://github.com/tetherto/mdk/blob/main/backend/workers/samples/demo-worker/index.js) as-is — it needs no worker-infra services (provisioning stores, alert templates), just `WorkerRuntime` and its own bundled mock device. Nothing in the steps below is specific to it, though: swap in `startWhatsminerWorker`, `startAntminerWorker`, or your own Worker from [Build a third-party Worker](/guides/workers/build-a-worker) and everything past the next step is unchanged. </Step> <Step> ### Boot Kernel and Worker in the same process The simplest of the three discovery modes ([full trade-offs here](/concepts/deployment-topologies#the-trade-off)): one Node process owns both the Kernel and the Worker, so there's no key file or DHT topic to manage. `examples/minimal-dashboard/start.js`: ```js 'use strict' const path = require('path') const { getKernel, waitForDiscovery } = require('../../backend/core/mdk') const { startDemoWorker } = require('../backend/demo-worker-caller') const demoMock = require('../../backend/workers/samples/demo-worker/mock/server') const ROOT = path.join(__dirname, '.mdk-data') const MOCK_PORT = 9101 const HTTP_PORT = Number(process.env.MDK_HTTP_PORT) || 3000 function onceListening (mock) { if (mock.server.listening) return Promise.resolve() return new Promise((resolve) => mock.server.once('listening', resolve)) } async function main () { // the one fake device this dashboard will show — swap for real hardware later const mock = demoMock.createServer({ host: '127.0.0.1', port: MOCK_PORT, serial: 'WM3-0001' }) await onceListening(mock) // Kernel + the one Worker, same process const kernel = await getKernel({ root: ROOT }) const worker = await startDemoWorker({ workerId: 'demo-worker-1', storeDir: path.join(ROOT, 'demo-worker-store'), seedDevices: [{ id: 'demo-0', opts: { host: '127.0.0.1', port: MOCK_PORT } }] }) await kernel.registerWorker(worker.runtime.getPublicKey()) await waitForDiscovery(kernel, { minWorkers: 1 }) console.log('worker registered: %s', worker.deviceIds.join(', ')) } module.exports = { main, ROOT, HTTP_PORT } if (require.main === module) main().catch((err) => { console.error(err); process.exit(1) }) ``` The demo Worker package exports a plugin and SQLite helper, not a boot function. The separate [`demo-worker-caller`](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js) used here owns `WorkerRuntime`, device configuration, persistence, sampling, and shutdown. `getKernel({ root: ROOT })` with no `topic`/`discovery` option defaults to DHT discovery with a fresh random topic. This example then registers the Worker's public key directly because both objects are in the same process. See the [discovery model](/concepts/stack/workers#discovery-model) for the DHT, Local, and Same-process options to use in other deployments. </Step> <Step> ### Write the one Gateway plugin route A [Gateway plugin](/guides/gateway/plugins) is a directory with a manifest and a controller. This one has a single read-only route that lists every registered Worker's devices and pulls each one's default `metrics` telemetry bundle — no per-device-family branching, because there's only one family here. #### 3.1 Write the plugin manifest `examples/minimal-dashboard/plugins/dashboard/mdk-plugin.json`: ```json { "name": "@your-org/mdk-plugin-dashboard", "version": "0.1.0", "description": "Minimal dashboard plugin: one route that lists every registered device and its live telemetry.", "routes": [ { "id": "dashboard.overview", "handler": "./controllers/overview.js", "auth": false, "http": { "method": "GET", "path": "/overview" }, "description": "Live snapshot of every device across every registered Worker.", "safety": "read-only" } ] } ``` #### 3.2 Write the controller `examples/minimal-dashboard/plugins/dashboard/controllers/overview.js`: ```js 'use strict' module.exports = async function overview (req, services) { const { workers } = await services.mdkClient.listWorkers() const devices = await Promise.all( workers.flatMap((w) => (w.deviceIds || []).map(async (deviceId) => { const tel = await services.mdkClient.pullTelemetry(deviceId, 'metrics') return { deviceId, workerId: w.workerId, workerState: w.state, ...tel.metrics } })) ) return { ts: Date.now(), devices } } ``` A controller is `async (req, services) => value` — return a plain object, the Gateway serializes it to JSON itself; you never touch `res`. `services.mdkClient` is the same client used everywhere else in MDK — no knowledge of the underlying MDK Protocol envelope required. <Callout type="info"> With more than one Worker family mixed in (miners, powermeters, sensors, ...) you'd branch by `deviceFamily` instead of spreading `tel.metrics` blindly — see [`examples/full-site/plugins/site/lib/site.js`](https://github.com/tetherto/mdk/blob/main/examples/full-site/plugins/site/lib/site.js) for that pattern once you outgrow this one. </Callout> </Step> <Step> ### Serve the plugin and static page from the same Gateway Add `startGateway` to `start.js`, mounting the plugin via `extraPluginDirs` and the built UI (Step 5's `ui/dist`) via `common.staticRootPath`. This is the complete canonical file; its boot order is mock, Kernel, Worker, registration, readiness, then Gateway: ```js 'use strict' const path = require('path') const { getKernel, startGateway, waitForDiscovery } = require('../../backend/core/mdk') const { startDemoWorker } = require('../backend/demo-worker-caller') const demoMock = require('../../backend/workers/samples/demo-worker/mock/server') const ROOT = path.join(__dirname, '.mdk-data') const MOCK_PORT = 9101 const HTTP_PORT = Number(process.env.MDK_HTTP_PORT) || 3000 function onceListening (mock) { if (mock.server.listening) return Promise.resolve() return new Promise((resolve) => mock.server.once('listening', resolve)) } async function main () { // Start the mock device before its Worker tries to connect. const mock = demoMock.createServer({ host: '127.0.0.1', port: MOCK_PORT, serial: 'WM3-0001' }) await onceListening(mock) // Start Kernel, then the Worker runtime that hosts the demo Worker plugin. const kernel = await getKernel({ root: ROOT }) const worker = await startDemoWorker({ workerId: 'demo-worker-1', storeDir: path.join(ROOT, 'demo-worker-store'), seedDevices: [{ id: 'demo-0', opts: { host: '127.0.0.1', port: MOCK_PORT } }] }) // Register the Worker and wait until it is ready before accepting HTTP traffic. await kernel.registerWorker(worker.runtime.getPublicKey()) await waitForDiscovery(kernel, { minWorkers: 1 }) await startGateway({ kernel, noAuth: true, port: HTTP_PORT, root: path.join(ROOT, 'gateway'), tmpdir: path.join(ROOT, 'gateway'), extraPluginDirs: [path.join(__dirname, 'plugins', 'dashboard')], common: { staticRootPath: path.join(__dirname, 'ui', 'dist') } }) console.log('worker registered: %s', worker.deviceIds.join(', ')) console.log(`dashboard up: http://localhost:${HTTP_PORT}/`) } module.exports = { main, ROOT, HTTP_PORT } if (require.main === module) main().catch((err) => { console.error(err); process.exit(1) }) ``` <Callout type="warn"> The route's `"auth": false` and Gateway's `noAuth: true` are **local-development settings**. Do not expose this Gateway directly to an untrusted network. Production deployments require TLS termination, authentication, authorization, and network policy. Before production, remove `noAuth: true`, set the route's `"auth"` to `true`, and declare its required `"permissions"`. Write routes also need input validation, rate limits, and auditing. </Callout> <Callout type="warn"> Serve the built page from `common.staticRootPath`, not a separate server on its own port. Gateway plugin controllers only receive `(req, services)` — never the underlying reply object — so a controller has no way to set `Access-Control-Allow-Origin`, and Gateway has no built-in CORS support. Building the UI (Step 5) and serving `ui/dist` from `staticRootPath` keeps `fetch('/overview')` same-origin with zero CORS configuration. This is also why `examples/full-site`'s Vite *dev* server proxies `/site/*` to the Gateway port instead of calling it cross-origin — Step 5's `vite.config.ts` proxies `/overview` the same way for hot-reload development. </Callout> </Step> <Step> ### Write the single-page UI with MDK devkit components Instead of hand-rolled HTML, the page is a small React + Vite app built from the same packages `examples/full-site/ui` uses — `@tetherto/mdk-react-adapter` for the provider and data hook, `@tetherto/mdk-react-devkit` for the components — scaled down to what one route needs: no router (one page), no charts (no history endpoint here), no sidebar. Three primitives do the job: `LabeledCard` for the section container, `DataTable` for the sortable device grid, and `Badge` to color-code `workerState`. `examples/minimal-dashboard/ui/package.json`: ```json { "name": "@your-org/mdk-minimal-dashboard-ui", "type": "module", "version": "0.1.0", "private": true, "scripts": { "dev": "vite", "build": "tsc --noEmit && vite build" }, "dependencies": { "@tetherto/mdk-react-adapter": "file:../../../ui/packages/react-adapter", "@tetherto/mdk-react-devkit": "file:../../../ui/packages/react-devkit", "react": "^19.2.0", "react-dom": "^19.2.0" }, "devDependencies": { "@types/react": "^19.2.14", "@types/react-dom": "^19.2.3", "@vitejs/plugin-react": "^4.3.4", "typescript": "^5.7.3", "vite": "^6.3.5" } } ``` `examples/minimal-dashboard/ui/tsconfig.json`: ```json { "compilerOptions": { "target": "ES2022", "jsx": "react-jsx", "lib": ["ES2022", "DOM", "DOM.Iterable"], "types": ["vite/client"], "module": "ESNext", "moduleResolution": "bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "vite.config.ts"], "exclude": ["node_modules", "dist"] } ``` `examples/minimal-dashboard/ui/vite.config.ts` — the dev-only proxy so `fetch('/overview')` stays same-origin against the Gateway port, the same pattern [`examples/full-site/ui/vite.config.ts`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/vite.config.ts) uses for `/site/*`: ```ts declare const process: { env: Record<string, string | undefined> } const apiPort = process.env.VITE_API_PORT || '3000' plugins: [react()], server: { port: Number(process.env.MDK_UI_PORT) || 3041, proxy: { '/overview': `http://localhost:${apiPort}` } } }) ``` `examples/minimal-dashboard/ui/index.html`: ```html <!doctype html> <html> <head> <meta charset="utf-8" /> <title>MDK dashboard</title> </head> <body> <div id="root"></div> <script type="module" src="/src/main.tsx"></script> </body> </html> ``` `examples/minimal-dashboard/ui/src/main.tsx` — `<MdkProvider>` wires the TanStack Query client `useQuery` needs and resolves the API base URL, exactly as it does in [`examples/full-site/ui/src/main.tsx`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/src/main.tsx): ```tsx const rootElement = document.getElementById('root') if (!rootElement) throw new Error('ERR_ROOT_ELEMENT_MISSING') // Same-origin: the Vite dev proxy forwards /overview to the gateway; // in production the Gateway serves this build from staticRootPath. ReactDOM.createRoot(rootElement).render( <StrictMode> <MdkProvider apiBaseUrl=""> <OverviewPage /> </MdkProvider> </StrictMode> ) ``` `examples/minimal-dashboard/ui/src/OverviewPage.tsx` — `useQuery` polls the route from Step 3 the same way [`examples/full-site/ui/src/SitePage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/src/SitePage.tsx) polls `/site/overview`; `DataTable` and `Badge` replace that page's hand-rolled markup: ```tsx type Device = { deviceId: string workerId: string workerState: string hashrate_rt?: number power?: number temperature?: number } type Overview = { ts: number; devices: Device[] } function get<T>(base: string, path: string): Promise<T> { return fetch(`${base}${path}`).then((res) => { if (!res.ok) throw new Error(`HTTP ${res.status}`) return res.json() as Promise<T> }) } function stateBadgeStatus(state: string): 'success' | 'error' | 'default' { if (state === 'ready') return 'success' if (state === 'offline') return 'error' return 'default' } const columns: DataTableColumnDef<Device, unknown>[] = [ { accessorKey: 'deviceId', header: 'Device' }, { accessorKey: 'workerId', header: 'Worker' }, { id: 'workerState', header: 'Worker state', cell: ({ row }) => { const state = (row.original.workerState || 'unknown').toLowerCase() return <Badge status={stateBadgeStatus(state)} text={state} /> } }, { accessorKey: 'hashrate_rt', header: 'Hashrate (TH/s)', cell: ({ getValue }) => (Number(getValue()) || 0).toFixed(2) }, { accessorKey: 'power', header: 'Power (W)', cell: ({ getValue }) => (Number(getValue()) || 0).toFixed(0) }, { accessorKey: 'temperature', header: 'Temp (°C)', cell: ({ getValue }) => (Number(getValue()) || 0).toFixed(1) } ] const { apiBaseUrl } = useMdkContext() const overview = useQuery({ queryKey: ['dashboard-overview'], queryFn: () => get<Overview>(apiBaseUrl, '/overview'), refetchInterval: 3000 }) return ( <div style={{ padding: 24 }}> <LabeledCard label="Devices" isFullWidth> <DataTable<Device> data={overview.data?.devices ?? []} columns={columns} getRowId={(row) => row.deviceId} loading={overview.isLoading} enablePagination={false} /> </LabeledCard> </div> ) } ``` A controller is `async (req, services) => value`; a page is `useQuery` + devkit components — neither one touches the other's plumbing. `OverviewPage` never imports `mdkClient`, and `overview.js` never imports React. </Step> <Step> ### Run it #### 6.1 Add package.json `examples/minimal-dashboard/package.json`: ```json { "name": "@your-org/mdk-minimal-dashboard", "version": "0.1.0", "private": true, "scripts": { "build": "npm --prefix ui run build", "start": "node start.js" } } ``` #### 6.2 Start the dashboard Install each package's own dependencies, build the UI once, then boot the backend: ```bash cd examples/minimal-dashboard npm install npm --prefix ui install npm run build npm run start ``` Open `http://localhost:3000/` — the page polls `/overview` every 3 seconds and shows the one `demo-0` device reporting live telemetry from its mock. Confirm the API directly with: ```bash curl -s http://localhost:3000/overview ``` You should see JSON shaped like `{ "ts": ..., "devices": [{ "deviceId": "demo-0", "workerId": "demo-worker-1", "workerState": "READY", "hashrate_rt": ..., "power": ..., "temperature": ... }] }`. ### Hot-reload UI development Vite does **not** replace the Gateway. Without hot reload you open `:3000` (Gateway serves the built `ui/dist`). With hot reload you still need the Gateway for `/overview`, and Vite only serves the React app and proxies that path. Keep **both** terminals running: **Terminal 1 — Gateway** (do not stop this): ```bash cd examples/minimal-dashboard npm run start ``` Wait for `dashboard up: http://localhost:3000/`. **Terminal 2 — Vite**: ```bash cd examples/minimal-dashboard VITE_API_PORT=3000 npm --prefix ui run dev ``` Open **`http://localhost:3041/`** (the Vite port), not `:3000`. Step 5's proxy forwards `/overview` to the Gateway on `VITE_API_PORT`. If Terminal 1 is down, Vite logs `http proxy error: /overview` / `ECONNREFUSED` and the table stays empty. </Step> </Steps> ## Next steps - **More Workers, zero controller changes**: `overview.js` already loops over every registered Worker generically. Register a second Worker the same way (Step 2's `startDemoWorker` + `startWhatsminerWorker`, etc., both followed by `kernel.registerWorker(...)`) and it appears in `/overview` for free. - **A write route**: Add a second manifest entry (`POST /devices/{deviceId}/command`) calling `services.mdkClient.sendCommand(deviceId, 'setPowerMode', { mode })`, following the `command.js` example in [Gateway plugins](/guides/gateway/plugins), and a `Button` in `OverviewPage.tsx` that `POST`s to it. Before deploying any physical write command, require narrowly scoped authorization, validate its payload and target state, apply rate limits, and record an audit trail. - **More pages, charts, history**: Add `react-router-dom` and a second route/page, or graduate to the domain layer (`@tetherto/mdk-react-devkit/domain`'s `LineChartCard`, `MetricCard`, header stats bar) once the Gateway plugin grows a history endpoint to feed them — see [`examples/full-site/ui/src/DashboardPage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/src/DashboardPage.tsx) and [`examples/full-site/plugins/site/controllers/history.js`](https://github.com/tetherto/mdk/blob/main/examples/full-site/plugins/site/controllers/history.js) for that shape. - **Separate processes or hosts**: Replace the direct registration in Step 2 with Local discovery for processes on one machine or DHT discovery for separate hosts, as described in the [discovery model](/concepts/stack/workers#discovery-model). ## Troubleshooting | Symptom | Cause | | --- | --- | | `/overview` returns `{ devices: [] }` | `kernel.registerWorker(...)` wasn't awaited, or `startGateway` was called before `waitForDiscovery` resolved | | `/overview` returns `500` / `Cannot read properties of null` | Controller spread `tel.metrics` when `pullTelemetry` returned `null` — use `(tel && tel.metrics) \|\| {}` as in Step 3 | | `pullTelemetry` throws / device shows zeros | The Worker's `connect()` couldn't reach the mock at boot — confirm the mock's `listening` event fired before `startDemoWorker` seeded it (Step 2's `onceListening`) | | Vite shows `http proxy error: /overview` / `ECONNREFUSED`, page at `:3041` has no data | Gateway is not listening on the proxy target — keep `npm run start` running in another terminal, and set `VITE_API_PORT` to that Gateway port (default `3000`). Open `:3041`, not `:3000` | | Browser `fetch('/overview')` fails from Vite with CORS / wrong host when Gateway is up | See the CORS note in Step 4 — the Vite proxy must target the Gateway (`VITE_API_PORT`); do not call a different origin from the page | | `ERR_PLUGIN_HANDLER_NOT_FOUND: routes.dashboard.overview: ./controllers/overview.js` on Gateway boot | `extraPluginDirs` must point at the directory *containing* `mdk-plugin.json`, not the controller file itself | | Gateway boots but the page 404s | `common.staticRootPath` must be an absolute path (`path.join(__dirname, 'ui', 'dist')`) pointing at a *built* UI (`npm run build` in Step 6), not a relative string or the unbuilt `ui/src` | | `Cannot find module '@tetherto/mdk-react-devkit'` when building `ui/` | Run the Prerequisites' `npm run setup:ui && npm run build:ui` from the repo root first — the UI packages ship pre-built `dist/` output that `ui/`'s `package.json` depends on via `file:` links | # Run the full-site example (/tutorials/quickstart/full-stack-demo) ## Overview This tutorial presents the [full-site example](https://github.com/tetherto/mdk/tree/main/examples/full-site) end to end running the full MDK stack: multiple configured Workers across a range of device families, their mock device servers, a Gateway HTTP API, and a React dashboard, all in one command. What you'll have at the end: - The supported fleet: multiple miner types, container types, and power meters; one sensor family with two inlet sensors; and two mining pools, each backed by mock hardware that speaks the real wire protocol - A Gateway API at `:3007` serving `/site/overview`, `/site/history`, and `/site/miners/:id/command` - A React dashboard at `:3040` with live hashrate, power, and device status - An MCP server exposing the site's device registry, telemetry, and commands as tools for AI agents The example can boot in one Node.js process (`node start.js`) or as separate processes through an interactive REPL (`node cli.js`). This tutorial uses `start.js` — the simplest path. ## Prerequisites - Node.js >=24 (LTS) - npm >=11 <Steps> <Step> ### Install the example #### 1.1 Clone the repo ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` #### 1.2 Run setup ```bash cd examples/full-site npm run setup ``` `setup` installs `backend/core`, `backend/workers`, the UI workspace devkit packages, and this example's own dependencies. It runs once; subsequent starts skip it. <Callout type="info"> The script walks several workspaces; first run takes 1-2 minutes. </Callout> </Step> <Step> ### Start the site Start with a small fleet (3 miners per family, 9 total) for a fast first boot: ```bash node start.js --miners 3 ``` Wait for the terminal to print the Gateway and UI URLs: ```text Gateway http://localhost:3007 UI http://localhost:3040 ``` Open `http://localhost:3040` in a browser. The dashboard shows live hashrate, total power, and a per-device breakdown. Verify via the API: ```bash curl -s http://localhost:3007/site/overview | jq '{miners: (.miners|length), containers: (.containers|length), pools: (.pools|length), sensors: (.sensors|length)}' ``` Expected output: ```text { "miners": 9, "containers": 2, "pools": 2, "sensors": 2 } ``` <Callout type="warn"> The default fleet (100 miners per family, 300 total) opens 900+ file descriptors simultaneously. Before switching from `--miners 3` to the full fleet, run `ulimit -n 4096` in the same terminal session. </Callout> </Step> </Steps> ## What just happened 1. **Setup** installed `backend/core`, `backend/workers`, the MDK UI devkit, and this example — all the packages `start.js` imports at boot. 2. **Mock hardware** — `mocks.js` started one server per device family (miners on TCP, containers on HTTP and MQTT, power meters and sensors on Modbus, pools on REST). They speak the real wire protocols; every Worker driver runs its true connect, collect, and command paths against them. 3. **Kernel** — `getKernel()` started the orchestration layer that discovers Workers as they register and routes telemetry pulls and commands to them. 4. **Workers** — eleven `bootWorker()` calls, one per configured Worker spec, each dispatching to that family's `start{X}Worker()` boot function (`startWhatsminerWorker`, `startAvalonWorker`, ...) to construct a `WorkerRuntime` and connect it to the Kernel. 5. **Gateway** — `startGateway()` mounted the site plugin from `plugins/site/` and opened the HTTP server on `:3007`. The plugin aggregates data across the configured Workers through `mdkClient`. 6. **UI** — a Vite React dev server started on `:3040`, serving a dashboard built from MDK devkit components. 7. **MCP server** — an MCP server started over HRPC, exposing the site's device registry, telemetry, and command dispatch as tools for AI agents. ## Cleanup `Ctrl+C` stops mocks, Workers, Kernel, Gateway, and the UI dev server cleanly. State (Kernel key, Worker seeds, device registry, and tail-log history) persists in `.mdk-data/`. To wipe it: ```bash rm -rf examples/full-site/.mdk-data ``` ## Next steps - If Kernel, Gateway, Worker, manager, or thing are unfamiliar, read [terminology](/reference/glossary) - Run the same supported Worker fleet under PM2 or Docker — [Multi-process deployment guide](/guides/deployment/run-all-workers-site) - Add [custom plugins to the Gateway HTTP API](/guides/gateway/plugins) - Connect an [AI agent to the MCP server](https://github.com/tetherto/mdk/blob/main/examples/full-site/docs/mcp-server.md) to query and command the site - Explore [the interactive CLI process manager](https://github.com/tetherto/mdk/tree/main/examples/full-site) for per-process logs, runtime seeding, and live status # Explore the demo (/tutorials/ui/explore-the-demo) This page presents a copy/paste method to clone the MDK UI monorepo, run the demo, and browse the full component library live. ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ ## Run the demo One copy/paste: four steps — clone, install, build, run. <Tabs> <Tab value="ssh" label="SSH" default> ```bash # Requires an SSH key configured for your GitHub account git clone git@github.com:tetherto/mdk.git cd mdk/ui npm install && npm run build npm run dev:catalog ``` </Tab> <Tab value="https" label="HTTPS"> ```bash git clone https://github.com/tetherto/mdk.git cd mdk/ui npm install && npm run build npm run dev:catalog ``` </Tab> </Tabs> Open [http://localhost:5173/mdk](http://localhost:5173/mdk). You'll land in the demo browser — a sidebar of the full MDK component library, covering core primitives (buttons, inputs, tables, charts, dialogs) and mining-domain components (operations centre, vendor containers, alerts, pool manager, settings). ### What the demo wires The demo app uses [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation), `@tetherto/mdk-react-adapter`, and `@tetherto/mdk-react-devkit` with `<MdkProvider>`. ## Next steps - [Wire React](/quickstart/wire-react): install all three packages and wrap your app in `MdkProvider` - [Wire a React app](/tutorials/ui/react/tutorial): scaffold an app with `MdkProvider` and adapter hooks - [Learn more about the React MDK UI Devkit](/tutorials/ui/react) # Get started with React (/tutorials/ui/react) ## TL;DR - **One provider, zero Redux**: install and wrap your app in `<MdkProvider>` so connected foundation components and adapter hooks share the same stores and API client - Presentational [`/core`](/reference/ui/react/core) and [`/foundation`](/reference/ui/react/foundation) imports can work without the provider - Anything that reads app state needs the provider ## Choose your path <Cards> <Card icon={<Rocket />} title={<span style={cardTitle}>Quickstart</span>} href="/quickstart/wire-react" description={ <> <span style={cardProse}> Install all three packages, wrap in MdkProvider, wire stores and theming </span> <span style={cardTime}>⏱️ <3 min</span> </> } /> <Card icon={<Compass />} title={<span style={cardTitle}>Explore the demo</span>} href="/tutorials/ui/explore-the-demo" description={ <> <span style={cardProse}> Single copy/paste to clone the monorepo and browse the full demo app in your browser </span> <span style={cardTime}>⏱️ <1 min</span> </> } /> <Card icon={<BookOpen />} title={<span style={cardTitle}>Tutorial</span>} href="/tutorials/ui/react/tutorial" description={ <> <span style={cardProse}> Step-by-step app scaffold with MdkProvider, adapter hooks, and foundation components </span> <span style={cardTime}>⏱️ <5 min</span> </> } /> <Card icon={<Bot />} title={<span style={cardTitle}>Build dashboards with your AI agent</span>} href="/quickstart/connect-agents" description={ <span style={cardProse}> Wire Cursor or Claude to MDK with the UI CLI, then build from plain-language prompts </span> } /> </Cards> ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ ## About the React stack The React UI Devkit is published as **three workspace packages** in the [MDK monorepo](https://github.com/tetherto/mdk): - **[`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation)** — headless state (Zustand vanilla stores), a TanStack `QueryClient` factory, telemetry primitives, and the command state machine. No React. - **`@tetherto/mdk-react-adapter`** — React bindings: `<MdkProvider>`, store hooks (`useAuth`, `useDevices`, `useNotifications`, `useTimezone`, `useActions`) and re-exports of `useQuery` / `useMutation`. - **`@tetherto/mdk-react-devkit`** — the React UI library: `./core` primitives and `./foundation` mining-domain components, hooks, and styles. `@tetherto/mdk-ui-foundation` is framework-agnostic; the adapter and devkit are React-specific. Add all three to your app’s `package.json`, then wrap the tree once in **`<MdkProvider>`** from `@tetherto/mdk-react-adapter`. <Accordions> <Accordion title="Explain it like I'm 12"> **`@tetherto/mdk-ui-foundation`** is the brain in the back room. It remembers who is logged in, which miners are selected, and what timezone the operator uses — but it has no buttons and no React. Other code (including non-React utilities) can read and update it with `getState()` / `setState()`. **`@tetherto/mdk-react-adapter`** plugs that brain into React. `<MdkProvider>` turns it on for your whole app. Hooks like `useAuth` and `useDevices` let components listen to one slice of state and re-render when that slice changes. **[`/core`](/reference/ui/react/core)** (`import … from '@tetherto/mdk-react-devkit/core'`) is the generic UI toolkit. Buttons, inputs, dialogs, tabs, charts, sidebars, toasts, tables. Nothing in it knows what a miner is. It owns colours, fonts, spacing, and the shared styling recipes. **[`/foundation`](/reference/ui/react/foundation)** (`import … from '@tetherto/mdk-react-devkit/foundation'`) is built on top of core. It knows about miners, containers, pools, hashrate, alarms, operators, permissions, and settings dashboards. Domain hooks and connected components expect `<MdkProvider>` to be in place. </Accordion> </Accordions> ## Next steps - Explore the [Core primitives](/reference/ui/react/core) in `@tetherto/mdk-react-devkit/core`: buttons, forms, charts, and themes - Explore the [Foundation components](/reference/ui/react/foundation) in `@tetherto/mdk-react-devkit/foundation`: mining-domain components and hooks - See the [UI Devkit overview](/reference/ui) for how the headless layer fits other frameworks - Browse the [Hooks](/reference/app-toolkit/hooks) reference — [state](/reference/app-toolkit/hooks/state), [component](/reference/app-toolkit/hooks/components), and [utility](/reference/app-toolkit/hooks/utilities) hooks # Build a dashboard with an agent (/tutorials/ui/react/build-any-dashboard-with-an-agent) This tutorial walks a **realistic agent session** end to end: the same two-step flow as [Build dashboards with your AI agent](/quickstart/connect-agents). ## Overview MDK's React UI Devkit's library of presentational and composable building blocks can be used wherever suits you. Mining is one of many disciplines that benefits from charts, tables, tabs, and stat cards. Your telemetry; your dash. You bring *your* labels, *your* mock data, and *your* layout. The first thing we built was [Mining Dashboards](/tutorials/ui/react). What will you build? IoT fleet backend reporting, workout metrics motivation app, weather stats? Your data; your choice. The prompt asked for a **statistics tutorial page** so students can explore distributions, trends, and raw grades. You see every: - [UI CLI](/reference/app-toolkit/ui-cli) command the agent would run - Resulting page code - Run instructions <Callout type="info"> We use mock JSON in the browser. No Kernel, Worker, pool API, or fleet backend is required. Presentational imports from `@tetherto/mdk-react-devkit/core` are enough for a highly visual, shippable UI. </Callout> ## What you'll learn 1. **Domain is yours.** Component contracts describe shape and behavior (chart datasets, table columns), not industry vocabulary. 2. **The agent path is unchanged.** `init` → plain-language intent → local manifests → scaffold → `check`. 3. **Visual density is supported.** Bar charts, line trends, sortable tables, and stat cards compose into a dashboard that *looks* like a product, not a wireframe. The demo app is **Stats Lab**: a fictional intro statistics course where Teaching Assistants review quiz score histograms, weekly class averages, and per-student grades. ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ - A project folder inside the MDK UI monorepo (this walkthrough uses `apps/stats-lab`, same pattern as [Wire a React app](/tutorials/ui/react/tutorial#create-your-app)) - [Build dashboards with your AI agent](/quickstart/connect-agents) wired once (`mdk-ui init`) or willingness to run `init` in step 1 ## Agent session walkthrough <Steps> <Step> ### Wire the IDE (same as agents) From your app or monorepo project root: ```bash npx @tetherto/mdk-ui-cli init --ide cursor ``` This writes `.mdk/context.md` and `.cursor/rules/mdk.mdc` so the session already knows the UI CLI surface. See [init](/reference/app-toolkit/ui-cli#init). </Step> <Step> ### State a non-mining intent Paste a prompt that names the domain explicitly so the agent does not reach for hashrate widgets: > Build a **statistics tutorial dashboard** for students in `apps/stats-lab`. Include: > > - A **histogram** of final exam scores (bar chart buckets 50–59 through 90–100) > - A **line chart** of weekly class average over six weeks > - A **sortable table** of students with midterm, final, and section > - Three **summary stat cards**: mean final, median final, enrollment count > > Use mock data in the repo. Import only from `@tetherto/mdk-react-devkit/core` and `@tetherto/mdk-react-devkit/foundation` where > needed. No mining APIs. The agent's job is unchanged from [Build dashboards with your AI agent](/quickstart/connect-agents#prompt-your-agent): discover exports, scaffold, and verify compile. </Step> <Step> ### Discovery commands the agent runs Behind the prompt, a well-behaved session issues deterministic CLI lookups (no model calls). A representative transcript: <Accordions> <Accordion title="Rank intent → shortlist"> ```bash npx @tetherto/mdk-ui-cli suggest "statistics dashboard histogram line chart data table stat cards" ``` Typically returns chart-category components near the top — `BarChart`, `LineChart`, and closely related chart primitives. General-purpose components like `DataTable`, `SingleStatCard`, and `Tabs` score lower on chart-focused queries and are best found with the `find --category` commands in the next accordion. Because we asked for mock data only, the agent skips adapter hooks like `useDevices`. </Accordion> <Accordion title="Filter by capability"> ```bash npx @tetherto/mdk-ui-cli find --category charts --format table npx @tetherto/mdk-ui-cli find --category tables --format table ``` Narrows to chart primitives and table components with stable exports. </Accordion> <Accordion title="Read contracts before coding"> ```bash npx @tetherto/mdk-ui-cli docs BarChart npx @tetherto/mdk-ui-cli docs LineChart npx @tetherto/mdk-ui-cli example LineChart npx @tetherto/mdk-ui-cli docs DataTable ``` The agent copies real prop shapes (`LineChartData` millisecond `x` values, `DataTableColumnDef` accessors) instead of inventing APIs. </Accordion> <Accordion title="Scaffold and verify"> ```bash npx @tetherto/mdk-ui-cli add page StatsLab \ --component BarChart \ --component LineChart \ --component DataTable \ --component SingleStatCard npx @tetherto/mdk-ui-cli check apps/stats-lab/src/App.tsx ``` `add page` emits a starter layout; the agent fills in mock datasets and labels. `check` validates imports and component prop contracts against the real package barrels; the app build in the local run verifies the final Vite project. </Accordion> </Accordions> Full command reference: [UI CLI](/reference/app-toolkit/ui-cli). </Step> <Step> ### Review the scaffolded page After the agent edits `App.tsx`, a Stats Lab dashboard might look like this: <Accordions> <Accordion title="Full Stats Lab page source"> ```tsx BarChart, LineChart, DataTable, Tabs, TabsList, TabsTrigger, TabsContent, } from '@tetherto/mdk-react-devkit/core' type Student = { id: string name: string section: 'A' | 'B' midterm: number final: number } const students: Student[] = [ { id: '1', name: 'Alex Kim', section: 'A', midterm: 82, final: 88 }, { id: '2', name: 'Jordan Lee', section: 'B', midterm: 74, final: 79 }, { id: '3', name: 'Sam Rivera', section: 'A', midterm: 91, final: 94 }, { id: '4', name: 'Taylor Ng', section: 'B', midterm: 68, final: 72 }, { id: '5', name: 'Casey Park', section: 'A', midterm: 85, final: 90 }, ] const weekStart = (weekIndex: number): number => new Date(2025, 0, 6 + weekIndex * 7).valueOf() const StatsLab = (): React.JSX.Element => { const [sorting, setSorting] = useState<DataTableSortingState>([]) const finals = students.map((s) => s.final) const meanFinal = finals.reduce((a, b) => a + b, 0) / finals.length const sortedFinals = [...finals].sort((a, b) => a - b) const medianFinal = sortedFinals[Math.floor(sortedFinals.length / 2)] const histogram = useMemo( () => ({ labels: ['50–59', '60–69', '70–79', '80–89', '90–100'], datasets: [ { label: 'Students', data: [1, 2, 4, 6, 3], backgroundColor: '#6366f1', }, ], }), [], ) const weeklyAverage = useMemo( () => ({ datasets: [ { label: 'Class average', borderColor: '#22c55e', data: [71, 74, 76, 79, 81, 83].map((y, i) => ({ x: weekStart(i), y, })), }, ], }), [], ) const columns: DataTableColumnDef<Student>[] = [ { accessorKey: 'name', header: 'Student' }, { accessorKey: 'section', header: 'Section' }, { accessorKey: 'midterm', header: 'Midterm' }, { accessorKey: 'final', header: 'Final' }, ] return ( <div style={{ padding: '2rem', display: 'grid', gap: '1.5rem' }}> <header> <h1 style={{ margin: 0 }}>Stats Lab</h1> <p style={{ margin: '0.5rem 0 0', opacity: 0.8 }}> Intro statistics — interpret distributions and trends </p> </header> <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))', gap: '1rem', }} > <SingleStatCard name="Mean final" value={Math.round(meanFinal)} unit="pts" variant="primary" /> <SingleStatCard name="Median final" value={medianFinal} unit="pts" variant="secondary" /> <SingleStatCard name="Enrollment" value={students.length} unit="students" variant="tertiary" /> </div> <Tabs defaultValue="charts"> <TabsList> <TabsTrigger value="charts">Charts</TabsTrigger> <TabsTrigger value="roster">Roster</TabsTrigger> </TabsList> <TabsContent value="charts"> <div style={{ display: 'grid', gap: '1.5rem', gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))', }} > <section> <h2 style={{ fontSize: '1rem' }}>Final exam distribution</h2> <BarChart data={histogram} height={280} /> </section> <section> <h2 style={{ fontSize: '1rem' }}>Weekly class average</h2> <LineChart data={weeklyAverage} height={280} unit="pts" beginAtZero /> </section> </div> </TabsContent> <TabsContent value="roster"> <DataTable columns={columns} data={students} sorting={sorting} onSortingChange={setSorting} /> </TabsContent> </Tabs> </div> ) } ``` </Accordion> </Accordions> Nothing in this file references pools, workers, or TH/s. The same components appear on mining pages because the **data model is generic**. </Step> </Steps> ## Run Stats Lab locally Follow the same monorepo workflow as [Wire a React app](/tutorials/ui/react/tutorial). If you already completed that tutorial, skip to **Run the app** with `stats-lab` as the workspace name. <Steps> <Step> ### Clone and build the UI monorepo <Tabs> <Tab value="https" label="HTTPS" default> ```bash git clone https://github.com/tetherto/mdk.git cd mdk ``` </Tab> <Tab value="ssh" label="SSH"> ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` </Tab> </Tabs> ```bash npm install npm run build ``` </Step> <Step> ### Scaffold `apps/stats-lab` ```bash cd apps npm create vite@latest stats-lab -- --template react-ts cd stats-lab ``` Add workspace dependencies to `package.json`: ```jsonc "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*", ``` Install from the monorepo root: ```bash cd ../.. npm install ``` </Step> <Step> ### Wrap with `MdkProvider` In `apps/stats-lab/src/main.tsx`, mirror [Wire a React app — Wrap your app in MdkProvider](/tutorials/ui/react/tutorial#wrap-your-app-in-mdkprovider): ```tsx // … <MdkProvider apiBaseUrl="https://example.invalid"> <App /> </MdkProvider> ``` Mock data does not call the API; the provider satisfies components that expect React context. </Step> <Step> ### Run the app From the monorepo root: ```bash npm -w stats-lab run build ``` Then start Vite: ```bash npm -w stats-lab run dev ``` Or from the app folder: ```bash cd apps/stats-lab npm run dev ``` Open the URL Vite prints (typically `http://localhost:5173`). You should see **Stats Lab** with histogram, trend line, stat cards, and a sortable roster tab. </Step> <Step> ### Optional: compare with the MDK demo app Same commands as [Wire a React app — Run the demo app](/tutorials/ui/react/tutorial#run-the-demo-app): ```bash npm run dev:catalog ``` Open [http://localhost:5173/mdk](http://localhost:5173/mdk) to browse mining-oriented examples, then contrast with Stats Lab: **same primitives, different story**. </Step> </Steps> ## Why the agent stays accurate Manifests list real exports, `check` catches many invented props, and `docs` / `example` ground the session in shipped contracts. The app build remains the final TypeScript and Vite verification. ## Next steps - [Build dashboards with your AI agent](/quickstart/connect-agents): the two-step entry point - [UI CLI reference](/reference/app-toolkit/ui-cli): every command in the discovery transcript - [Chart components](/reference/ui/react/core/components/charts): `BarChart`, `LineChart`, and related data shapes - [Data display](/reference/ui/react/core/components/data-display): `DataTable` sorting and pagination - [Wire a React app](/tutorials/ui/react/tutorial): hands-on monorepo setup without an agent # Your first component (/tutorials/ui/react/first-component) This tutorial assists first-time users to understand how to render a single MDK component in a React app as fast as possible. <Callout type="warn"> This path skips `<MdkProvider>` which works for presentational `/core` and `/foundation` imports. For adapter hooks or connected foundation components, continue with [Wire a React app](/tutorials/ui/react/tutorial). </Callout> ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ <Steps> <Step> ### Clone and build <Callout type="info"> The MDK UI (`mdk/ui`) is an npm workspace. Clone the repository, install at the workspace root, and build all packages before adding an app or running the demo. </Callout> #### 1.1 Clone the repository <Tabs> <Tab value="https" label="HTTPS" default> ```bash git clone https://github.com/tetherto/mdk.git cd mdk/ui ``` </Tab> <Tab value="ssh" label="SSH"> ```bash # Requires an SSH key configured for your GitHub account git clone git@github.com:tetherto/mdk.git cd mdk/ui ``` </Tab> </Tabs> #### 1.2 Install and build ```bash npm install npm run build ``` This builds `@tetherto/mdk-react-devkit` and the other packages in the `ui/` workspace. </Step> <Step> ### Create your app #### 2.1 Scaffold a Vite React app Create a new React app in the `apps/` folder: ```bash cd apps npm create vite@latest my-app -- --template react-ts cd my-app ``` <Callout type="info"> Ignore the CLI "Now run" instructions — follow the MDK-specific steps below. </Callout> #### 2.2 Add MDK to `package.json` Open `package.json` and add the workspace dependency: <Tabs> <Tab value="add" label="Add dependency" default> ```jsonc "@tetherto/mdk-react-devkit": "*", ``` </Tab> <Tab value="context" label="In context"> ```jsonc { "name": "my-app", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "tsc -b && vite build", "lint": "eslint .", "preview": "vite preview" }, "dependencies": { "@tetherto/mdk-react-devkit": "*", // [!code ++] "react": "^19.2.6", // [!code highlight] "react-dom": "^19.2.6" // [!code highlight] }, } ``` <Callout type="info"> Vite also adds a `devDependencies` block (`eslint`, `typescript`, `vite`, `@types/*`); leave that block as is. </Callout> </Tab> </Tabs> #### 2.3 Install from the workspace root ```bash cd ../.. # from apps/my-app back up to the workspace root mdk/ui npm install ``` </Step> <Step> ### Import styles #### 3.1 Import the MDK stylesheet Import the MDK stylesheet once in your app's entry point (typically `src/main.tsx`): <Tabs> <Tab value="add" label="Add styles import" default> ```tsx ``` </Tab> <Tab value="context" label="In context"> ```tsx createRoot(document.getElementById('root')!).render( <StrictMode> <App /> </StrictMode>, ) ``` </Tab> </Tabs> </Step> <Step> ### Render your first component > This example replaces `App.tsx` with a single mining metric tile that toggles between a normal and an alarmed state. #### 4.1 Replace `App.tsx` with the demo This pulls a button from `@tetherto/mdk-react-devkit/core` and a domain component (`SingleStatCard`) from `@tetherto/mdk-react-devkit/foundation`: ```tsx function App() { const [overheating, setOverheating] = useState(false) return ( <div style={{ padding: '2rem', display: 'grid', gap: '1rem', maxWidth: 320 }}> <h1>Miner status</h1> <SingleStatCard name="Inlet temperature" value={overheating ? 78 : 28} unit="°C" variant={overheating ? 'tertiary' : 'primary'} color="red" flash={overheating} /> <Button onClick={() => setOverheating((on) => !on)}> {overheating ? 'Cool down' : 'Simulate overheat'} </Button> </div> ) } ``` #### 4.2 Run your app From the workspace root mdk/ui, start the dev server for your app. The `-w` name must match the `name` field in `apps/my-app/package.json` (`my-app` from step 2.1): ```bash npm -w my-app run dev ``` Alternatively, from the app folder: ```bash cd apps/my-app npm run dev ``` You should see a card showing `Inlet temperature 28 °C` with a **Simulate overheat** button below it. Click the button and the card flips into an alarm state: red border, red text, value jumps to `78 °C`, and the whole card pulses. Click **Cool down** to reset. That is `@tetherto/mdk-react-devkit/core` (the `Button`) and `@tetherto/mdk-react-devkit/foundation` (the `SingleStatCard`) working together: generic primitives plus mining-domain components, in one app. </Step> </Steps> ## Next steps - To browse the full kit in one app first, see [Explore the demo](/tutorials/ui/explore-the-demo) - [Wire a React app](/tutorials/ui/react/tutorial): add `<MdkProvider>` and adapter hooks for connected foundation components - [Quickstart](/quickstart/wire-react): minimum integration reference (install, provider, stores, theming) - [Core](/reference/ui/react/core): primitives reference (`@tetherto/mdk-react-devkit/core`) - [Foundation](/reference/ui/react/foundation): mining-domain components (`@tetherto/mdk-react-devkit/foundation`) # Wire a React app (/tutorials/ui/react/tutorial) This tutorial walks you through the full React stack: three workspace packages, `<MdkProvider>`, and adapter hooks. <Callout type="info"> For a faster path that renders one presentational component without the provider, see [Your first component](/tutorials/ui/react/first-component). </Callout> ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ <Steps> <Step> ### Clone and build <Callout type="info"> The `mdk/ui` directory is the npm workspace root. Clone the repository, install at the workspace root, and build all packages before adding an app or running the demo. </Callout> #### 1.1 Clone the repository <Tabs> <Tab value="https" label="HTTPS" default> ```bash git clone https://github.com/tetherto/mdk.git cd mdk/ui ``` </Tab> <Tab value="ssh" label="SSH"> ```bash # Requires an SSH key configured for your GitHub account git clone git@github.com:tetherto/mdk.git cd mdk/ui ``` </Tab> </Tabs> #### 1.2 Install and build ```bash npm install npm run build ``` This builds `@tetherto/mdk-react-devkit` and the other packages in the `ui/` workspace. </Step> <Step> ### Create your app #### 2.1 Scaffold a Vite React app Create a new React app in the `apps/` folder: ```bash cd apps npm create vite@latest my-app -- --template react-ts cd my-app ``` <Callout type="info"> Ignore the CLI "Now run" instructions — follow the MDK-specific steps below. </Callout> #### 2.2 Add MDK to `package.json` Open `package.json` and add all three workspace packages: <Tabs> <Tab value="add" label="Add dependencies" default> ```jsonc "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*", ``` </Tab> <Tab value="context" label="In context"> ```jsonc { "name": "my-app", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "tsc -b && vite build", "lint": "eslint .", "preview": "vite preview" }, "dependencies": { "@tetherto/mdk-react-devkit": "*", // [!code ++] "@tetherto/mdk-react-adapter": "*", // [!code ++] "@tetherto/mdk-ui-foundation": "*", // [!code ++] "react": "^19.2.6", // [!code highlight] "react-dom": "^19.2.6" // [!code highlight] }, } ``` <Callout type="info"> Vite also adds a `devDependencies` block (`eslint`, `typescript`, `vite`, `@types/*`); leave that block as is. </Callout> </Tab> </Tabs> #### 2.3 Install from the workspace root ```bash cd ../.. # from apps/my-app back up to the workspace root mdk/ui npm install ``` </Step> <Step> ### Wrap your app in MdkProvider `<MdkProvider>` wires the headless stores from [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation) into React and sets up the TanStack `QueryClient`. It is required for adapter hooks and connected foundation components. See also [Quickstart — Wrap your app in MdkProvider](/quickstart/wire-react#wrap-your-app-in-mdkprovider). #### 3.1 Update `main.tsx` <Tabs> <Tab value="add" label="Add provider" default> ```tsx ``` Wrap `<App />`: ```tsx <MdkProvider apiBaseUrl="https://app-node.example.com"> <App /> </MdkProvider> ``` </Tab> <Tab value="context" label="In context"> ```tsx createRoot(document.getElementById('root')!).render( <StrictMode> <MdkProvider apiBaseUrl="https://app-node.example.com"> <App /> </MdkProvider> </StrictMode>, ) ``` </Tab> </Tabs> </Step> <Step> ### Use adapter hooks and render a component Adapter hooks subscribe to Zustand stores and re-render when the selected slice changes. This example uses `useAuth` and `useDevices` from the adapter, then renders a presentational `SingleStatCard` from foundation. #### 4.1 Replace `App.tsx` ```tsx function App() { const { permissions } = useAuth() const { selectedDevices } = useDevices() return ( <div style={{ padding: '2rem', display: 'grid', gap: '1rem', maxWidth: 360 }}> <h1>Operator dashboard</h1> <p>Selected devices: {selectedDevices?.length ?? 0}</p> <p>Permissions loaded: {permissions ? 'yes' : 'no'}</p> <SingleStatCard name="Inlet temperature" value={28} unit="°C" variant="primary" /> <Button onClick={() => console.log('Ready for connected components')}> Log readiness </Button> </div> ) } ``` <Callout type="info"> Connected foundation components (device explorers, pool manager, settings dashboards) expect `<MdkProvider>` and often read multiple stores. Start with presentational imports while you wire your API; swap in connected components as your backend comes online. </Callout> </Step> <Step> ### Run your app From the workspace root `mdk/ui`: ```bash npm -w my-app run dev ``` Or from the app folder: ```bash cd apps/my-app npm run dev ``` You should see the operator dashboard with device and permission readouts plus a temperature card. The adapter hooks confirm `<MdkProvider>` is wired — without it, they would throw. </Step> </Steps> ## Next steps - [Quickstart](/quickstart/wire-react): install reference, store hooks, and theming - [Core](/reference/ui/react/core): primitives reference (`@tetherto/mdk-react-devkit/core`) - [Foundation](/reference/ui/react/foundation): mining-domain components (`@tetherto/mdk-react-devkit/foundation`) ### Run the demo app If you are already at the workspace root `mdk/ui`: ```bash npm run dev:catalog ``` If your shell is still in the app folder: ```bash cd ../.. # apps/my-app → apps → workspace root mdk/ui npm run dev:catalog ``` Open [http://localhost:5173/mdk](http://localhost:5173/mdk) to browse examples.