# MDK Docs (/v0-0-2)

## I'm building with MDK

<Cards>
  <Card
    icon={<BookOpen />}
    title={<span style={cardTitle}>Learn what MDK is</span>}
    href="/v0-0-2/concepts/about"
    description={
      <span style={cardProse}>
        Product overview, architecture, and the MDK packages
      </span>
    }
  />
  <Card
    icon={<Compass />}
    title={<span style={cardTitle}>Get started path picker</span>}
    href="/v0-0-2/get-started"
    description={
      <span style={cardProse}>
        Discover your path, including backend tools and the raw client
      </span>
    }
  />
  <Card
    icon={<Rocket />}
    title={<span style={cardTitle}>Ship a dashboard fast</span>}
    href="/v0-0-2/ui/react/quickstart"
    description={
      <span style={cardProse}>
        React Quickstart: <code>MdkProvider</code>, adapter hooks, foundation components
      </span>
    }
  />
  <Card
    icon={<Atom />}
    title={<span style={cardTitle}>Use UI Core without a dashboard</span>}
    href="/v0-0-2/how-to/ui/core/use-ui-core-headlessly"
    description={
      <span style={cardProse}>
        <code>@tetherto/mdk-ui-core</code> is headless: Zustand stores and a <code>QueryClient</code> factory you can wire into any runtime
      </span>
    }
  />
</Cards>

## I'm an AI agent (or building one)

<Cards>
  <Card
    icon={<FileText />}
    title={<span style={cardTitle}>Full docs in one file</span>}
    href="/v0-0-2/llms-full.txt"
    description={
      <span style={cardProse}>
        Every page of these docs concatenated for LLM ingestion
      </span>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>mdk-ui CLI</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          <code>@tetherto/mdk-ui-cli</code> &mdash; agent-first registry, scaffold, and docs
        </span>
        <span style={cardCta}>Coming soon &rarr;</span>
      </>
    }
  />
</Cards>

# Code of Conduct (/v0-0-2/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 (/v0-0-2/community/contributing)

Thank you for your interest in contributing to **MDK**!

This document outlines the contribution workflow for all MDK repositories, from setting up your development environment to submitting pull requests and participating in releases.

## Getting started

### Prerequisites

Before contributing, make sure you have the following installed:

- **Node.js** (version 20.0 or higher)
- **Git** (latest stable version)
- **npm** (included with Node.js)

### Licensing

MDK is released under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).

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

### Fork and clone

1. Fork the repository on GitHub.
2. Clone your fork locally and navigate into the project directory:

   ```bash
   git clone https://github.com/YOUR_USERNAME/REPOSITORY_NAME.git
   cd REPOSITORY_NAME
   ```

3. Add the upstream remote to keep your fork in sync with the main repository:

   ```bash
   git remote add upstream https://github.com/tetherto/REPOSITORY_NAME.git
   ```

> Replace `REPOSITORY_NAME` with the actual repository name.

## Pull request workflow

### Branch naming convention

Create branches using the following pattern:

```text
{type}/{short-description}
```

Supported types:

- `feature/`: new features or workers
- `fix/`: bug fixes
- `docs/`: documentation changes
- `refactor/`: code refactoring
- `test/`: test additions or changes

#### Examples

```bash
# New feature
git checkout -b feature/mdk-new-device

# Bug fix
git checkout -b fix/timeout-handling
```

### Keeping your fork updated

Regularly sync your fork with the upstream repository:

```bash
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
```

### Pull request steps

1. Create a branch from `main`
2. Make your code changes
3. Write or update tests
4. Run linting and tests locally
5. Commit changes with meaningful messages
6. Push your branch and open a Pull Request targeting `main`

### PR checklist

Before submitting your PR, ensure that:

- Code builds locally
- Tests pass (`npm test`)
- Linting passes (`npm run lint` or `npm run lint:fix`)
- New features include tests
- Documentation is updated if applicable

### PR title format

Use the following convention:

```text
{type}({scope}): {description}
```

Types:

- `feat`
- `fix`
- `docs`
- `refactor`
- `test`
- `chore`

Examples:

- `feat(miner): add Antminer S21 support`
- `fix(timeout): resolve action timeout handling`
- `docs(api): update stats documentation`

## Release process

### PR review

All pull requests go through the following review steps:

1. **Automated checks**: linting and tests must pass
2. **Code review**: at least one maintainer approval is required
3. **Feedback resolution**: all requested changes must be addressed
4. **Squash and merge**: maintainers squash commits to keep history clean

### Release workflow

Releases are created by merging approved branches into `main` and tagging a version when applicable.

**Workflow:**

1. Contributor creates a feature or fix branch from `main`
2. Contributor runs tests locally
3. If tests fail, fixes are applied and tests re-run
4. Contributor opens a PR targeting `main`
5. Reviewer performs code review
6. Contributor addresses feedback (if requested)
7. Reviewer approves or rejects the PR
8. Approved PRs are merged into `main`
9. Reviewer tags a release version (if applicable)
10. Reviewer deploys to production
11. On failure, rollback to the previous tag

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

## Versioning and tagging

### Version tagging

```bash
git checkout main
git pull origin main

git tag -a v1.2.0 -m "Release v1.2.0: Add RTD support"

git push origin main
git push origin v1.2.0
```

### Versioning scheme

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

---

## Code standards

### JavaScript style

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

## Quick reference

### Common Git commands

```bash
# Start a new feature
git checkout main && git pull && git checkout -b feature/my-feature

# Sync with upstream
git fetch upstream && git merge upstream/main

# Prepare for PR
npm run lint:fix && npm test

# Squash commits
git rebase -i HEAD~N

# Amend last commit
git commit --amend

# Force push after rebase (feature branches only)
git push --force-with-lease origin feature/my-feature
```

# Governance (/v0-0-2/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](/v0-0-2/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.

# About MDK (/v0-0-2/concepts/about)

<include>../../../_snippets/v0-0-2/monorepo/concepts/about.mdx</include>

## Next steps

- [Get started](/v0-0-2/get-started)

Learn more about:

- [Architecture](/v0-0-2/concepts/architecture)
- [MDK App Toolkit](/v0-0-2/concepts/architecture/app-toolkit)
- [Connecting intelligent agents](/v0-0-2/concepts/architecture#ai-agents-and-the-mcp-server)

# Architecture (/v0-0-2/concepts/architecture)

<include>../../../../_snippets/v0-0-2/monorepo/concepts/architecture/index.mdx</include>

## Next steps

Learn more about:

- [About MDK](../../index)
- [MDK App Toolkit](/v0-0-2/concepts/architecture/app-toolkit)
- [ORK](/v0-0-2/concepts/architecture/ork)
- [Get started](/v0-0-2/get-started)

# MDK App Toolkit (/v0-0-2/concepts/architecture/app-toolkit)

<Callout type="info">
Status: 🚧 The MDK App Toolkit is under active development. The v0.0.2 release ships the [React UI Kit](#react-ui-kit).
</Callout>

## Introducing the MDK App Toolkit

The MDK App Toolkit is an [open-source](/v0-0-2/community/contributing#licensing), reusable package for building applications on top of 
[`@tetherto/mdk-ork`](/v0-0-2/concepts/architecture/ork).

The App Toolkit ships in three parts:

1. [Frontend tools](#frontend-tools).
2. [Backend tools](#backend-tools).
3. [Plugins](#plugins).

While `@tetherto/mdk-ork` is entirely unopinionated, the App Toolkit provides a batteries-included application layer. It plugs into existing stacks
(leveraging the low-level `@tetherto/mdk-client` for `@tetherto/mdk-ork` connectivity) so teams can ship operator-ready dashboards and custom domain 
logic without rebuilding the App Node from scratch.

## The problem

Building an application on top of hardware infrastructure historically forces developers to face four friction points across the full stack:

1. **Frontend repeated logic**: every frontend developer integrating with backend APIs ends up reinventing solutions to the same plumbing challenges:

   - Throttling fast-moving telemetry streams
   - Managing optimistic UI state transitions
   - Detecting silent communication timeouts

2. **Backend repeated logic**: every backend developer ends up writing the same App Node plumbing (JWT auth, RBAC, command proxying, and fleet
aggregation) before they can ship any custom business logic.

3. **The UI rigidity trap**: platforms try to solve the repeated logic problem by shipping a UI component library. UI is inherently subjective; when external
developers are forced to use generic components, they get locked out of customizing the CSS to match their brand, leading to abandoned toolkits and identical-looking dashboards.

4. **The extension bottleneck**: when an external manufacturer builds a brand new miner or device, there is no clear path for injecting a custom dashboard
widget and custom aggregator into an existing deployment.

## The solution

The App Toolkit decouples logic from styling, separates frontend and backend concerns, and provides an explicit plug-and-play extension architecture:

1. It extracts complex API state and caching logic, such as handling server disconnects and buffering data from the App Node gateway, into a purely
headless frontend layer (`@tetherto/mdk-react-devkit/core`).

2. It ships a reusable App Node library that drops into Fastify or Express, handling JWT auth, RBAC, and `@tetherto/mdk-ork` proxying out of the box, while exposing
hooks for developers to plug in their own routes and aggregations.

3. It embraces the *shadcn/ui* pattern by providing reference UI components that developers copy and paste, giving them full control over CSS and layout
while still leveraging the underlying data hooks.

   <Callout type="info">
   🚧 Components will soon be available via npm.
   </Callout>

4. It provides the MDK-App plugin architecture: an out-of-the-box, extensible shell framework where third-party frontend widgets and backend routes can
be injected dynamically at runtime as a single drop-in package.

## The scope

While MDK targets Bitcoin mining, the App Toolkit's architecture is deliberately domain-agnostic. Anywhere there is a fleet of devices reporting telemetry,
with operators that need real-time visibility and control, the same patterns apply: IoT sensor networks, industrial telemetry, energy grid monitoring,
autonomous vehicle fleets, and AI-agent control planes are all natural fits.

The portable layers are everything above the protocol boundary: the headless state machine handles buffering, optimistic UI, and stale detection regardless
of what telemetry it receives; the framework adapters translate that state into reactive lifecycles for any React, Vue, or Svelte app; the reference UI
primitives and the plug-and-play shell are generic UI building blocks; the App Node middleware library is generic Fastify/Express; and the plugin pattern,
register a backend route alongside a widget that consumes it, works for any backend with the same shape.

The MDK-specific glue lives below: `@tetherto/mdk-client` speaks the MDK Protocol to `@tetherto/mdk-ork`, the App Node middleware proxies commands over Holepunch RPC, 
and `@tetherto/mdk-react-devkit/foundation` adds mining-domain components such as vendor container UIs and the operations centre. Swap that protocol layer 
and the App Toolkit pattern carries to any domain with the same shape.

## Frontend tools

Frontend tools are the building blocks for dashboards on top of `@tetherto/mdk-ork`. They decompose into three layers: 
**[UI Core](/v0-0-2/reference/app-toolkit/ui-core)** (headless state), **framework adapters** (e.g., React bindings), and **UI Kit** 
(styled React components), so business logic is shared while styling stays under developer control.

### UI Core

The UI Core ([`@tetherto/mdk-ui-core`](/v0-0-2/reference/app-toolkit/ui-core)) is the framework-agnostic headless layer. Headless: the same store 
logic can back React, Vue, Svelte, or plain JS utilities. Framework adapters bind `@tetherto/mdk-ui-core` into reactive lifecycles for each UI runtime.

<Callout type="info">
Headless primitives [will land in this package](/v0-0-2/reference/app-toolkit/ui-core#whats-not-here-yet).
</Callout>

### Framework adapters

`@tetherto/mdk-ui-core` stores do not trigger UI re-renders on their own. Framework adapters subscribe to those stores and expose reactive hooks.

For React, [`@tetherto/mdk-react-adapter`](/v0-0-2/ui/react/get-started) provides `<MdkProvider>`, store hooks (`useAuth`, `useDevices`, `useActions`, and others), and TanStack Query re-exports. Future adapters (`@tetherto/mdk-vue`, `@tetherto/mdk-svelte`, `@tetherto/wc`) will follow the same pattern.

### UI Kit

The toolkit optionally ships styled reference components (for example, `<DeviceTile />`). These follow the *shadcn/ui* pattern:
they are copy-pasted into the developer's source tree. Developers own the styling completely.

#### React UI Kit

For React, [`@tetherto/mdk-react-devkit`](/v0-0-2/ui/react/get-started) is a production-tested UI Kit available as a ready-made implementation 
of this layer. Highlights:

- 100+ production-tested components
- Built on React 19 and *shadcn/ui*
- Zero CSS-in-JS runtime overhead

<Callout type="info">
🚧 UI Kits for other frameworks (Vue, Svelte, and so on) will follow the same pattern and ship alongside their framework adapters.
</Callout>

### Developer entry points

The toolkit can be adopted at any of the following entry points, from most batteries-included to least.

| Entry point | Package | What ships | What you write | When to choose |
|---|---|---|---|---|
| UI Kit | `@tetherto/mdk-react-devkit` (`/core` + `/foundation` entrypoints) | Pre-built React components, shell layout, ready-made ops dashboard | Data wiring, optional theming | You want a dashboard up fast |
| Framework adapter | `@tetherto/mdk-react-adapter` (React today; Vue/Svelte/WC planned) | `<MdkProvider>`, store hooks, TanStack Query re-exports | Your own components and layout | You have a design system already |
| UI Core | [`@tetherto/mdk-ui-core`](/v0-0-2/reference/app-toolkit/ui-core) | Zustand vanilla stores, `QueryClient` factory | Framework bindings or headless utilities | You need store access outside React or are building a new adapter |
| Raw SDK | `@tetherto/mdk-client` | MDK Protocol client, connection management, reconnection | Everything above the wire: state, framework, UI | You are building a non-UI consumer (CLI, agent, backend service) |

## Backend tools

Backend tools are a library for implementing custom business logic on top of `@tetherto/mdk-ork`, loosely coupled to the App Node and completely plug-and-play.
Developers do not have to write the App Node gateway from scratch: the library drops directly into Fastify or Express, ships the boilerplate every operator
needs, and exposes hooks for the custom routes and aggregations that make each deployment unique.

### Drop-in App Node middleware

Pre-built middleware that wires up the standard App Node responsibilities so developers do not reinvent them:

- Exposing standard `/auth` endpoints
- Validating incoming user JWTs
- Proxying commands securely down to `@tetherto/mdk-ork` over Holepunch RPC (HRPC) using `@tetherto/mdk-client`

### Route extension API

Hooks allowing developers to bind new REST or WebSocket endpoints (for example, `POST /mining/stats`) that perform complex aggregations using `@tetherto/mdk-ork`
capabilities via `@tetherto/mdk-client`. Custom routes live in a developer-owned package and snap into the middleware without forking it.

## Plugins

A plugin pairs a frontend tools widget with a backend tools route as a single drop-in module. For developers looking for an out-of-the-box solution,
the toolkit pairs the frontend and backend halves into the MDK-App plugin architecture: an extensible, multi-tenant shell.

### The prebuilt shell

Instead of building a custom React layout and a custom Fastify server, developers spin up the MDK UI Shell and MDK Generic App Node. These are ready-to-use
binaries fully wired together.

### Writing a plugin

External developers write plugins consisting of two tightly coupled pieces of code that register dynamically into the shell at runtime:

1. **MDK-App server**: a package of business logic that registers custom backend routes (for example, `/mining/stats`) into the backend tools middleware hooks.
2. **MDK-App widget**: a custom frontend component that mounts into the MDK UI Shell's grid layout and natively queries `/mining/stats`.

**Plug-and-play reusability**: this explicit convention ensures that an external company can build a completely new dashboard widget and backend aggregator
for a new device type, publish it as a single npm package, and allow any user to drop it into their existing MDK deployment without modifying upstream source code.

## Architecture overview

```mermaid
flowchart TD
    subgraph frontend ["<b>frontend tools (browser)</b>"]
        direction TB
        UI_CORE["<code>@tetherto/mdk-ui-core</code><br/>Zustand stores · QueryClient factory"]
        FRAMEWORKS["Framework adapters<br/>(<code>@tetherto/mdk-react-adapter</code>, …)"]
        UI_COMPS["UI Kit<br/>(<code>@tetherto/mdk-react-devkit</code>)"]

        UI_COMPS -->|consumes adapter hooks| FRAMEWORKS
        FRAMEWORKS -->|binds headless stores| UI_CORE
    end

    subgraph backend ["<b>backend tools (App Node)</b>"]
        direction TB
        ROUTER["App Node middleware<br/>(Express / Fastify, JWT auth, route extension API)"]
        CLIENT["<code>@tetherto/mdk-client</code><br/>isolated native SDK"]

        ROUTER -->|translates REST to HRPC via| CLIENT
    end

    UI_CORE <-->|HTTP| ROUTER
    CLIENT -->|MDK Protocol| ORK["<code>@tetherto/mdk-ork</code>"]

    style frontend fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
    style backend fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
```

## Next steps

Learn more:

- [About MDK](../../../index)
- [Architecture: the orchestration kernel](..)
- [Connecting intelligent agents](../index#ai-agents-and-the-mcp-server)
- [See the license](/v0-0-2/community/contributing#licensing)

# ORK (/v0-0-2/concepts/architecture/ork)

`@tetherto/mdk-ork` is the trusted coordination layer of the stack. It splits internal responsibilities across single-purpose modules with
their own state machines, so domains can evolve independently without coupling to each other.

The design is inspired by Kubernetes: a pull-only model bounds the pace of execution so the kernel cannot be overwhelmed by
upstream pressure.

## Module overview

```mermaid
flowchart TD
    MCP["MCP Handler"] -->|Validates and routes| CD["Command Dispatcher"]
    CD -->|Enqueues| CSM["Command State Machine"]
    CSM <-->|HRPC req / res| W["Worker"]
    SCH["Scheduler"] -->|Triggers state pull| CSM
    CSM -->|state.pull| W
    WR["Worker Registry"] -->|Routing lookup| CD
    HM["Health Monitor"] -->|Updates status| WR
    SCH -->|Triggers interval| HM
    SCH -->|Triggers pull| TC["Telemetry Collector"]
    TC -->|Pulls metrics| W
```

## Module catalogue

`@tetherto/mdk-ork`'s coordination splits across single-purpose modules. Each owns its own state machine, persistence boundary,
and scaling characteristics. Six modules ship in v0.0.1; two more are deferred to a later release.

| Module | Role |
|---|---|
| [Command Dispatcher](/v0-0-2/reference/ork/modules#command-dispatcher) | Validates and resolves the destination Worker for incoming commands. |
| [Command State Machine](/v0-0-2/reference/ork/modules#command-state-machine) | Tracks command lifecycle from `QUEUED` to `SUCCESS` or `FAILED`. |
| [Worker Registry](/v0-0-2/reference/ork/modules#worker-registry) | Authoritative lookup of active Workers, their RPC keys, and managed devices. |
| [Telemetry Collector](/v0-0-2/reference/ork/modules#telemetry-collector) | Stateless proxy between callers and Worker-local telemetry stores. |
| [Scheduler](/v0-0-2/reference/ork/modules#scheduler) | System metronome; drives all interval-based pulls (telemetry, state, health). |
| [Health Monitor](/v0-0-2/reference/ork/modules#health-monitor) | Liveness probes against Workers; reports status to the Registry. |
| [Fault Supervisor](/v0-0-2/reference/ork/modules#fault-supervisor) (deferred) | Circuit-breaker patterns to contain cascading failures. |
| [Concurrency Manager](/v0-0-2/reference/ork/modules#concurrency-manager) (deferred) | Per-device locking and queue-depth limits. |

For the full state machines, transition rules, interface signatures, and recovery details, see the
[ORK modules reference](/v0-0-2/reference/ork/modules).

## System recovery

On a full system crash and restart, `@tetherto/mdk-ork` modules orchestrate recovery without user intervention:

1. **Worker Registry** loads last known Worker and device states from Hyperbee.
2. **Command State Machine** sweeps the WAL for stranded `EXECUTING` tasks and forces them to timeout or retry.
3. **Health Monitor** begins firing immediate pings to verify which Workers are still active.
4. **Connections**: the network layer awaits incoming HRPC reconnect storms from persistent Workers.

Recovery is local and predictable. Worker crashes do not bring down the runtime; supervisors (PM2, Docker, Kubernetes) handle
process restarts in multi-process deployments, and Workers rejoin the system after recovery.

## Next steps

- [Architecture](../index) — how ORK fits the broader MDK stack
- [ORK modules reference](/v0-0-2/reference/ork/modules) — per-module state machines, interfaces, and transition rules

# Deployment topologies (/v0-0-2/concepts/deployment-topologies)

<include>../../../_snippets/v0-0-2/monorepo/concepts/deployment-topologies.mdx</include>

# Terminology (/v0-0-2/concepts/terminology)

<include>../../../_snippets/v0-0-2/monorepo/concepts/terminology.mdx</include>

# Get started with MDK (/v0-0-2/get-started)

## 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="/v0-0-2/tutorials/backend-stack/run"
    description={
      <span style={cardProse}>
        <strong>Observe</strong> — one command brings up ORK 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="/v0-0-2/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="/v0-0-2/tutorials/full-stack/dashboard"
    description={
      <span style={cardProse}>
        <strong>Demo</strong> — run a React dashboard with live charts on the stack
      </span>
    }
  />
</Cards>

## Build with MDK

<Cards>
  <Card
    icon={<Layers />}
    title={<span style={cardTitle}>Add MDK data to an existing app</span>}
    href="#framework-quickstarts"
    description={
      <span style={cardProse}>
        Use the <strong>frontend tools</strong> to bring MDK telemetry and controls into a React, Vue, or Svelte app
      </span>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Build a full MDK app from scratch</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Coming soon: Adopt the App Toolkit shell. Frontend and backend wired together, extended via plugins
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Align the MDK backend with your business logic</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Coming soon: Use the <strong>backend tools</strong> to plug a library of custom routes and aggregations into the MDK App Node
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Connect directly to ORK from any client</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Coming soon: Use <code>@tetherto/mdk-client</code> to talk to <code>@tetherto/mdk-ork</code> from a CLI, agent, or backend service
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
</Cards>

## Framework quickstarts

<Cards>
  <Card
    icon={<Atom />}
    title={<span style={cardTitle}>React</span>}
    href="/v0-0-2/ui/react/get-started"
    description={
      <span style={cardProse}>
        Pick a path: lean Quickstart, full Tutorial, or browse the component packages
      </span>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Vue</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Reactive hooks for Vue
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Svelte</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Reactive hooks for Svelte
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Web Components</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Framework-agnostic Web Components
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
</Cards>

## Next steps

- Learn more about the high-level [architecture](/v0-0-2/concepts/architecture): runtime stack and deployment modes
- Access the [MDK repositories](/v0-0-2/resources/repositories)
- [Contribute](/v0-0-2/community/contributing)

# Use UI Core headlessly (/v0-0-2/how-to/ui/core/use-ui-core-headlessly)

<PackageBadge>@tetherto/mdk-ui-core</PackageBadge>

[`@tetherto/mdk-ui-core`](/v0-0-2/reference/app-toolkit/ui-core) is the framework-agnostic headless layer of the MDK App Toolkit. This how-to walks through installing it on its own and driving its Zustand stores from a non-React runtime &mdash; a Node script, a Vue or Svelte adapter you're authoring, a CLI tool, or a test helper.

## When to reach for this

Use headless UI Core when:

- You're authoring a framework adapter (Vue, Svelte, Web Components) and need raw access to the Zustand stores.
- You're building a Node CLI or backend service that has to read MDK telemetry and act on it.
- You're writing test helpers or fixtures that need to seed and inspect store state without a React renderer.
- You need to subscribe to store changes from non-UI code &mdash; logging, websocket bridges, metrics.

For a React app, the [React adapter](/v0-0-2/ui/react/get-started) wraps UI Core with `<MdkProvider>` and adapter hooks. Use that path instead so most React code never touches `@tetherto/mdk-ui-core` directly.

## Install

`@tetherto/mdk-ui-core` has no peer dependencies on React or any UI framework.

```bash
npm install @tetherto/mdk-ui-core
```

## Subpath imports

Pull only the pieces you need from the relevant subpath. Subpath imports give tree-shakers a smaller surface than the top-level barrel:

```ts
```

The [subpath exports table](/v0-0-2/reference/app-toolkit/ui-core#subpath-exports) on the reference lists every supported entry.

## Create a QueryClient

`createMdkQueryClient` returns a TanStack Query Core client wired to your App Node. Pass an explicit `baseUrl`, or let the factory resolve one from environment variables:

```ts

const queryClient = createMdkQueryClient({
  baseUrl: 'https://app-node.example.com',
})
```

Without an explicit `baseUrl`, the factory checks `VITE_MDK_API_URL` then `MDK_API_URL` before falling back to `http://localhost:3000`. The [resolution order](/v0-0-2/reference/app-toolkit/ui-core#queryclient-factory) on the reference covers every case.

## Read store state

Each store is a Zustand vanilla singleton. `getState()` returns the current snapshot:

```ts

const { token, permissions } = authStore.getState()
console.log('current token', token)
```

## Write store state

`setState()` accepts either a partial object or a function that receives the previous state:

```ts

devicesStore.setState({ selectedDeviceId: 'wm-002' })

devicesStore.setState((prev) => ({
  devices: [...prev.devices, newDevice],
}))
```

## Subscribe to changes

`subscribe()` runs a callback on every state change and returns an unsubscribe function:

```ts

const unsubscribe = notificationStore.subscribe((state) => {
  console.log('unread notifications:', state.count)
})

unsubscribe()
```

## A complete Node example

A small Node script that authenticates against the App Node, fetches the device list once, and then tails unread notification count changes:

```ts
  authStore,
  devicesStore,
  notificationStore,
} from '@tetherto/mdk-ui-core/store'

async function main() {
  const queryClient = createMdkQueryClient({
    baseUrl: process.env.MDK_API_URL ?? 'http://localhost:3000',
  })

  authStore.setState({ token: process.env.MDK_TOKEN ?? '' })

  const devices = await queryClient.fetchQuery({
    queryKey: ['devices', 'list'],
    queryFn: async () => {
      const res = await fetch(`${process.env.MDK_API_URL}/api/devices`, {
        headers: { Authorization: `Bearer ${authStore.getState().token}` },
      })
      return res.json()
    },
  })
  devicesStore.setState({ devices })

  console.log(`Found ${devices.length} devices`)

  const unsubscribe = notificationStore.subscribe((state) => {
    console.log(`unread notifications: ${state.count}`)
  })

  process.on('SIGINT', () => {
    unsubscribe()
    process.exit(0)
  })
}

main().catch((err) => {
  console.error(err)
  process.exit(1)
})
```

Run it with:

```bash
MDK_TOKEN=ey... MDK_API_URL=https://app-node.example.com node script.ts
```

For the prebuilt query and mutation factories (`authQuery`, `devicesQuery`, `deviceQuery`, `telemetryQuery`), check the [QueryClient factory section](/v0-0-2/reference/app-toolkit/ui-core#queryclient-factory) on the reference.

## Next steps

- [UI Core reference](/v0-0-2/reference/app-toolkit/ui-core): full store list, query helpers, and the `createMdkQueryClient` resolution order.
- [MDK App Toolkit architecture](/v0-0-2/concepts/architecture/app-toolkit): where UI Core fits in the frontend stack.
- [React adapter](/v0-0-2/ui/react/get-started): if you decide to layer React on top.

# Upgrade npm for the MDK UI monorepo (/v0-0-2/how-to/ui/react/upgrade-npm)

The MDK UI monorepo (`mdk-ui`) declares `engines.npm` `>=11.0.0` and pins `packageManager` to `npm@11.12.0`. **Node 22 LTS** often bundles **npm 10.9.x**, so `npm install` at the repo root can fail with an engine warning before you clone, build, or run the demo.

## Check your npm version

```bash
npm -v
```

If the major version is **10** (for example `10.9.4`), upgrade before running `npm install` at the monorepo root.

## Upgrade npm

Pick one approach.

### Option A — global npm 11 (simplest)

```bash
npm install -g npm@11
npm -v
```

### Option B — Corepack (match upstream `packageManager`)

```bash
corepack enable
corepack prepare npm@11.12.0 --activate
npm -v
```

You should see `11.x` (Option B targets `11.12.0`).

## Retry at the monorepo root

```bash
cd /path/to/mdk-ui
npm install
npm run build
```

## Next steps

- [Explore the demo](/v0-0-2/ui/react/explore-the-demo) (`npm run dev:demo`)
- Follow the [quickstart](/v0-0-2/ui/react/quickstart) for app integration
- Follow [Wire a React app](/v0-0-2/tutorials/ui/react/tutorial) (`npm -w my-app run dev`)

# Reference (/v0-0-2/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](/v0-0-2/concepts/architecture);
for step-by-step instructions, see [Get started](/v0-0-2/get-started).

## Browse by stack area

### App Toolkit

- **[UI Kit](/v0-0-2/reference/app-toolkit/ui-kit)**: constants, hooks, types, and utilities for the React UI Kit.
- *backend tools*: coming soon.

### ORK

- **[Modules](/v0-0-2/reference/ork/modules)**: kernel module specs, state machines, transition tables, and recovery behavior.

### MDK Protocol

- **[Messages](/v0-0-2/reference/protocol/messages)**: envelope schema, request/response examples, action catalogue, and base command set.
- *Capability contract*: coming soon.

# Hooks (/v0-0-2/reference/app-toolkit/hooks)

Reusable React hooks shipped by the MDK App Toolkit. Grouped by what each hook depends on, not by which package ships it. This matches the 
[Developer entry points](/v0-0-2/concepts/architecture/app-toolkit#developer-entry-points) model where UI Core, the React adapter, and the 
UI Kit are siblings — you should be able to find the hooks you need without adopting layers you do not use.

## At a glance

| Bucket | Page | What it covers | Needs |
|---|---|---|---|
| State | [State hooks](/v0-0-2/reference/app-toolkit/hooks/state) | React-bound views of the headless `@tetherto/mdk-ui-core` Zustand stores | `<MdkProvider>` from `@tetherto/mdk-react-adapter` |
| Components | [Component hooks](/v0-0-2/reference/app-toolkit/hooks/components) | Hooks coupled to MDK styled components or shell layout (notifications, forms, charts, dashboards, filters, widgets, tables) | `@tetherto/mdk-react-devkit` and (for some) `<MdkProvider>` |
| Utilities | [Utility hooks](/v0-0-2/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) `<MdkProvider>` |

## All hooks

### State

<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

| Hook | Summary |
|---|---|
| [`useAuth`](/v0-0-2/reference/app-toolkit/hooks/state#useauth) | React view of the headless `authStore` (token, permissions) |
| [`useDevices`](/v0-0-2/reference/app-toolkit/hooks/state#usedevices) | React view of the headless `devicesStore` (device list, selection) |
| [`useTimezone`](/v0-0-2/reference/app-toolkit/hooks/state#usetimezone) | React view of the headless `timezoneStore` (operator timezone) |
| [`useNotifications`](/v0-0-2/reference/app-toolkit/hooks/state#usenotifications) | React view of the headless `notificationStore` (unread counter) |
| [`useActions`](/v0-0-2/reference/app-toolkit/hooks/state#useactions) | React view of the headless `actionsStore` (pending submissions) |

### Components

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

| Sub-group | Hooks |
|---|---|
| Notifications | [`useNotification`](/v0-0-2/reference/app-toolkit/hooks/components#usenotification) |
| Shell | [`useHeaderControls`](/v0-0-2/reference/app-toolkit/hooks/components#useheadercontrols), [`useSidebarExpandedState`](/v0-0-2/reference/app-toolkit/hooks/components#usesidebarexpandedstate), [`useSidebarSectionState`](/v0-0-2/reference/app-toolkit/hooks/components#usesidebarsectionstate) |
| Forms | [`useFormField`](/v0-0-2/reference/app-toolkit/hooks/components#useformfield), [`useFormReset`](/v0-0-2/reference/app-toolkit/hooks/components#useformreset) |
| Filters | [`useReportTimeFrameSelectorState`](/v0-0-2/reference/app-toolkit/hooks/components#usereporttimeframeselectorstate), [`useTimeframeControls`](/v0-0-2/reference/app-toolkit/hooks/components#usetimeframecontrols) |
| Widgets | [`useFinancialDateRange`](/v0-0-2/reference/app-toolkit/hooks/components#usefinancialdaterange) |
| Tables | [`useGetAvailableDevices`](/v0-0-2/reference/app-toolkit/hooks/components#usegetavailabledevices) |
| Charts | [`useChartDataCheck`](/v0-0-2/reference/app-toolkit/hooks/components#usechartdatacheck), [`useEbitda`](/v0-0-2/reference/app-toolkit/hooks/components#useebitda), [`useEnergyBalanceViewModel`](/v0-0-2/reference/app-toolkit/hooks/components#useenergybalanceviewmodel) |
| Dashboards | [`usePoolConfigs`](/v0-0-2/reference/app-toolkit/hooks/components#usepoolconfigs), [`useSiteOverviewDetailsData`](/v0-0-2/reference/app-toolkit/hooks/components#usesiteoverviewdetailsdata) |

### Utilities

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

| Sub-group | Hooks |
|---|---|
| Permissions | [`useCheckPerm`](/v0-0-2/reference/app-toolkit/hooks/utilities#usecheckperm), [`useHasPerms`](/v0-0-2/reference/app-toolkit/hooks/utilities#usehasperms), [`useIsFeatureEditingEnabled`](/v0-0-2/reference/app-toolkit/hooks/utilities#useisfeatureeditingenabled) |
| Generic React | [`useLocalStorage`](/v0-0-2/reference/app-toolkit/hooks/utilities#uselocalstorage), [`useKeyDown`](/v0-0-2/reference/app-toolkit/hooks/utilities#usekeydown), [`useWindowSize`](/v0-0-2/reference/app-toolkit/hooks/utilities#usewindowsize), [`usePlatform`](/v0-0-2/reference/app-toolkit/hooks/utilities#useplatform), [`useDeviceResolution`](/v0-0-2/reference/app-toolkit/hooks/utilities#usedeviceresolution), [`useBeepSound`](/v0-0-2/reference/app-toolkit/hooks/utilities#usebeepsound), [`usePagination`](/v0-0-2/reference/app-toolkit/hooks/utilities#usepagination), [`useSubtractedTime`](/v0-0-2/reference/app-toolkit/hooks/utilities#usesubtractedtime), [`useTimezoneFormatter`](/v0-0-2/reference/app-toolkit/hooks/utilities#usetimezoneformatter) |
| Device and IP | [`usePduViewer`](/v0-0-2/reference/app-toolkit/hooks/utilities#usepduviewer) |
| Domain transforms | [`useCostSummary`](/v0-0-2/reference/app-toolkit/hooks/utilities#usecostsummary), [`useHashBalance`](/v0-0-2/reference/app-toolkit/hooks/utilities#usehashbalance), [`useSubsidyFees`](/v0-0-2/reference/app-toolkit/hooks/utilities#usesubsidyfees), [`useUpdateExistedActions`](/v0-0-2/reference/app-toolkit/hooks/utilities#useupdateexistedactions) |
| TanStack Query re-exports | [Re-exports table](/v0-0-2/reference/app-toolkit/hooks/utilities#tanstack-query-re-exports) |

## Imports

```tsx
```

# Component hooks (/v0-0-2/reference/app-toolkit/hooks/components)

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

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](/v0-0-2/reference/app-toolkit/hooks/state) or 
[Utility hooks](/v0-0-2/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` |

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/ui/react/foundation#prerequisites)
- For hooks that read from headless stores (`useNotification`, view-model hooks): 
[wrap your app in `<MdkProvider>`](/v0-0-2/ui/react/quickstart#wrap-your-app-in-mdkprovider)

## Import

```tsx
  useChartDataCheck,
  useEbitda,
  useEnergyBalanceViewModel,
  useFinancialDateRange,
  useGetAvailableDevices,
  useHeaderControls,
  useNotification,
  usePoolConfigs,
  useReportTimeFrameSelectorState,
  useSiteOverviewDetailsData,
  useTimeframeControls,
} from '@tetherto/mdk-react-devkit/foundation'

  useFormField,
  useFormReset,
  useSidebarExpandedState,
  useSidebarSectionState,
} from '@tetherto/mdk-react-devkit/core'
```

## Notifications

### `useNotification`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 <Button onClick={handleSave}>Save</Button>
}
```

## Shell

### `useHeaderControls`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 |

<Callout type="warn">
`handleToggle` and `handleReset` both call `notifySuccess` internally. Every invocation produces a toast notification; avoid calling them in response to fast-changing state.
</Callout>

#### Example

```tsx
function HeaderSettings() {
  const { preferences, handleToggle, handleReset } = useHeaderControls()

  return (
    <div>
      {Object.entries(preferences).map(([key, visible]) => (
        <Toggle
          key={key}
          label={key}
          checked={visible}
          onChange={(value) => handleToggle(key, value)}
        />
      ))}
      <Button onClick={handleReset}>Reset to Default</Button>
    </div>
  )
}
```

### `useSidebarExpandedState`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Persist sidebar expanded/collapsed state in `localStorage` so the layout survives reloads.

```tsx
```

#### Example

```tsx
function AppSidebar() {
  const [expanded, setExpanded] = useSidebarExpandedState(false)

  return (
    <aside className={expanded ? 'sidebar--expanded' : 'sidebar--collapsed'}>
      <Button onClick={() => setExpanded(!expanded)}>Toggle sidebar</Button>
    </aside>
  )
}
```

### `useSidebarSectionState`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Persist individual sidebar section open/closed states in `localStorage`.

```tsx
```

#### Example

```tsx
function SidebarSection({ id, title, children }) {
  const [open, setOpen] = useSidebarSectionState(id, true)

  return (
    <section>
      <button type="button" onClick={() => setOpen(!open)}>{title}</button>
      {open ? children : null}
    </section>
  )
}
```

## Forms

### `useFormField`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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 <FormField> / <FormItem>
function FieldStatusDot() {
  const { invalid, isDirty } = useFormField()
  return (
    <span className={invalid ? 'dot--error' : isDirty ? 'dot--dirty' : 'dot--clean'} />
  )
}
```

### `useFormReset`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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<MinerFields>({ defaultValues: { name: '', ip: '' } })
  const { resetForm, isDirty } = useFormReset({
    form,
    onAfterReset: () => console.log('Form reset'),
  })

  return (
    <Form form={form} onSubmit={form.handleSubmit(onSubmit)}>
      <FormInput control={form.control} name="name" label="Name" />
      <FormInput control={form.control} name="ip" label="IP address" />
      <Button type="submit">Save</Button>
      <Button type="button" onClick={resetForm} disabled={!isDirty}>
        Reset
      </Button>
    </Form>
  )
}
```

## Filters

### `useReportTimeFrameSelectorState`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <div>
      <p>{start.toLocaleDateString()} – {end.toLocaleDateString()}</p>
      <button onClick={() => setPresetTimeFrame(7)}  className={presetTimeFrame === 7  ? 'active' : ''}>Last 7 days</button>
      <button onClick={() => setPresetTimeFrame(30)} className={presetTimeFrame === 30 ? 'active' : ''}>Last 30 days</button>
      <button onClick={() => setPresetTimeFrame(null)}>Custom range</button>
    </div>
  )
}
```

### `useTimeframeControls`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <div>
      <select value={yearSelectValue} onChange={(e) => handleYearChange(e.target.value)}>
        <option value={String(selectedYear)}>{selectedYear}</option>
      </select>
      <select value={monthSelectValue} onChange={(e) => handleMonthTreeChange(e.target.value)}>
        <option value={monthSelectValue}>Month {selectedMonth + 1}</option>
      </select>
    </div>
  )
}
```

## Widgets

### `useFinancialDateRange`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <div>
      {datePicker}
      <Button onClick={onDateRangeReset}>Reset to current month</Button>
      {dateRange && (
        <p>
          {new Date(dateRange.start).toLocaleDateString()} –{' '}
          {new Date(dateRange.end).toLocaleDateString()}
        </p>
      )}
    </div>
  )
}
```

## Tables

### `useGetAvailableDevices`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <div>
      <select aria-label="Container type">
        <option value="">All containers</option>
        {availableContainerTypes.map((type) => <option key={type}>{type}</option>)}
      </select>
      <select aria-label="Miner type">
        <option value="">All miners</option>
        {availableMinerTypes.map((type) => <option key={type}>{type}</option>)}
      </select>
    </div>
  )
}
```

## Charts

### `useChartDataCheck`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 <EmptyState message="No hashrate data available" />
  }

  return <BarChart data={dataset} />
}
```

```tsx
function TemperatureChart({ data }) {
  const isEmpty = useChartDataCheck({ data })

  return isEmpty ? (
    <EmptyState message="No temperature data" />
  ) : (
    <LineChart data={data} />
  )
}
```

#### 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**](/v0-0-2/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 (
    <ChartContainer title="Revenue" empty={isEmpty}>
      <BarChart data={chartData} />
    </ChartContainer>
  )
}
```

For the full `BarChartInput` shape, per-dataset `datalabels` merge, and all-zero empty rules, see
[Hook-shaped bar data (`buildBarChartData`)](/v0-0-2/ui/react/core/components/charts/composition#hook-shaped-bar-data).

### `useEbitda`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <div>
      {datePicker}
      {errors.length > 0 && <p role="alert">{errors.join(', ')}</p>}
    </div>
  )
}
```

### `useEnergyBalanceViewModel`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <div>
      <div>
        <Button onClick={() => onTabChange('revenue')} disabled={viewModel.activeTab === 'revenue'}>Revenue</Button>
        <Button onClick={() => onTabChange('cost')}    disabled={viewModel.activeTab === 'cost'}>Cost</Button>
      </div>
      {viewModel.isLoading && <p>Loading…</p>}
      {viewModel.errors.length > 0 && <p role="alert">{viewModel.errors.join(', ')}</p>}
    </div>
  )
}
```

## Dashboards

### `usePoolConfigs`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`](/v0-0-2/ui/react/foundation/pool-manager/pools) and [`Miner explorer`](/v0-0-2/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<string, PoolSummary>` | 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 <Loader />
  if (error) return <CoreAlert variant="error">Failed to load pools</CoreAlert>

  return (
    <ul>
      {pools.map((pool) => (
        <li key={pool.id}>{pool.name}</li>
      ))}
    </ul>
  )
}
```

### `useSiteOverviewDetailsData`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <div>
      <p>Hashrate: {containerHashRate}</p>
      <p>Status: {isContainerRunning ? 'Running' : 'Offline'}</p>
      <p>Miners mapped: {Object.keys(minersHashmap).length}</p>
      <p>PDU sections: {Object.keys(segregatedPduSections).join(', ')}</p>
    </div>
  )
}
```

# State hooks (/v0-0-2/reference/app-toolkit/hooks/state)

<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

State hooks bind the framework-agnostic [`@tetherto/mdk-ui-core`](/v0-0-2/reference/app-toolkit/ui-core) 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](/v0-0-2/concepts/architecture/app-toolkit#developer-entry-points) table compares adoption layers.

## Prerequisites

- [Wrap your app in `<MdkProvider>`](/v0-0-2/ui/react/quickstart#wrap-your-app-in-mdkprovider)
- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/ui/react/foundation#prerequisites)

## Import

```tsx
  useActions,
  useAuth,
  useDevices,
  useNotifications,
  useTimezone,
} from '@tetherto/mdk-react-adapter'
```

## `useAuth`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

React-bound view of the headless [`authStore`](/v0-0-2/reference/app-toolkit/ui-core). Exposes `token` and `permissions`; equivalent to `useStore(authStore)` with React subscription semantics.

```tsx
```

### Example

```tsx
function SessionStatus() {
  const { token } = useAuth()

  if (!token) return <p>Sign in to continue</p>
  return <p>Active session</p>
}
```

## `useDevices`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

React-bound view of the headless [`devicesStore`](/v0-0-2/reference/app-toolkit/ui-core). Exposes the device list, the currently selected devices, and helpers to mutate selection.

```tsx
```

### Example

```tsx
function DeviceToolbar() {
  const { selectedDevices, setSelectedDevices } = useDevices()

  return (
    <div>
      <p>Selected: {selectedDevices.length}</p>
      <Button onClick={() => setSelectedDevices([])}>Clear selection</Button>
    </div>
  )
}
```

## `useTimezone`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

React-bound view of the headless [`timezoneStore`](/v0-0-2/reference/app-toolkit/ui-core). Read or update the operator's timezone preference (IANA identifier). Use [`useTimezoneFormatter`](/v0-0-2/reference/app-toolkit/hooks/utilities#usetimezoneformatter) when you also need date-formatting helpers.

```tsx
```

### Example

```tsx
function TimezonePicker() {
  const { timezone, setTimezone } = useTimezone()
  return (
    <select value={timezone} onChange={(e) => setTimezone(e.target.value)}>
      <option value="UTC">UTC</option>
      <option value="America/New_York">America/New_York</option>
      <option value="Europe/London">Europe/London</option>
    </select>
  )
}
```

## `useNotifications`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

React-bound view of the headless [`notificationStore`](/v0-0-2/reference/app-toolkit/ui-core). Exposes the unread counter (`count`) plus `increment`, `decrement`, and `reset`. For the user-facing toast surface use [`useNotification`](/v0-0-2/reference/app-toolkit/hooks/components#usenotification) from foundation.

```tsx
```

### Example

```tsx

function UnreadBadge() {
  const { count } = useNotifications()
  return <Badge count={count} />
}
```

## `useActions`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

React-bound view of the headless [`actionsStore`](/v0-0-2/reference/app-toolkit/ui-core). Exposes the pending operator submission queue plus helpers like `setAddPendingSubmissionAction` and `removePendingSubmissionAction`.

```tsx
```

### Example

```tsx
function SubmissionTracker() {
  const { pendingSubmissions, setAddPendingSubmissionAction } = useActions()

  return (
    <div>
      <p>{pendingSubmissions.length} pending submissions</p>
      <Button onClick={() => setAddPendingSubmissionAction({ id: 'demo', kind: 'restart' })}>
        Queue restart
      </Button>
    </div>
  )
}
```

# Utility hooks (/v0-0-2/reference/app-toolkit/hooks/utilities)

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

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](/v0-0-2/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 `<MdkProvider>`](/v0-0-2/ui/react/quickstart#wrap-your-app-in-mdkprovider)
- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

Check if the current user has a specific permission. Reads `permissions` from the adapter [`authStore`](/v0-0-2/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 ? <Button>Edit devices</Button> : null
}
```

### `useHasPerms`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

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`](/v0-0-2/reference/app-toolkit/hooks/state#useauth).

```tsx
```

#### Example

```tsx
function ContextMenu({ device }) {
  const hasPerms = useHasPerms()
  return (
    <Menu>
      {hasPerms(['devices:edit', 'devices:admin']) && <MenuItem>Edit</MenuItem>}
      {hasPerms('devices:delete') && <MenuItem>Delete</MenuItem>}
    </Menu>
  )
}
```

### `useIsFeatureEditingEnabled`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

Returns whether the current user has the `features` capability to edit feature flags.

```tsx
```

#### Example

```tsx
function FeatureFlagRow({ flag }) {
  const canEdit = useIsFeatureEditingEnabled()
  return <Switch disabled={!canEdit} checked={flag.enabled} />
}
```

## Generic React

### `useLocalStorage`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

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 <Button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>Toggle</Button>
}
```

### `useKeyDown`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

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) => (
    <MinerCard key={m.id} miner={m} onClick={() => select(m, { range: shiftHeld })} />
  ))
}
```

### `useWindowSize`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

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 <LineChart width={Math.min(windowWidth - 32, 960)} />
}
```

### `usePlatform`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

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 <span>Running on {platform}</span>
}
```

### `useDeviceResolution`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

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' ? <Stack>{children}</Stack> : <SidebarLayout>{children}</SidebarLayout>
}
```

### `useBeepSound`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

Manage pagination state and produce `{ limit, offset }` query arguments for API calls. Returns state shaped for the devkit `<Pagination>` 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 `<Pagination>` |
| `queryArgs` | `{ limit, offset }` | Query arguments for API calls |
| `handleChange` | `function` | `(page, pageSize) => void` — pass to `<Pagination onChange={…}>` |
| `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 (
    <>
      <Table rows={data?.rows ?? []} />
      <Pagination {...pagination} onChange={handleChange} />
    </>
  )
}
```

### `useSubtractedTime`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

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 <small>Synced {formatDistanceToNow(now)} ago</small>
}
```

### `useTimezoneFormatter`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

Read the app timezone from the adapter [`timezoneStore`](/v0-0-2/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 <time>{getFormattedDate(raisedAt)}</time>
}
```

## Device and IP

### `usePduViewer`
<PackageBadge>@tetherto/mdk-react-adapter</PackageBadge>

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 (
    <>
      <TransformWrapper onInit={onViewerInit}>
        <TransformComponent>{/* …diagram… */}</TransformComponent>
      </TransformWrapper>
      {showBackToContent && <Button onClick={handleBackToContent}>Back to content</Button>}
    </>
  )
}
```

## Domain transforms

### `useCostSummary`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <div>
      {datePicker}
      {isLoading && <p>Loading…</p>}
      {error  && <p role="alert">Failed to load cost data</p>}
    </div>
  )
}
```

### `useHashBalance`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <div>
      {/* Pass chart datasets to your BarChart components */}
      <pre>{JSON.stringify(siteHashRevenueChartData?.labels, null, 2)}</pre>
      <pre>{JSON.stringify(networkHashpriceChartData?.labels, null, 2)}</pre>
      <pre>{JSON.stringify(combinedCostChartData?.labels, null, 2)}</pre>
    </div>
  )
}
```

### `useSubsidyFees`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 <p>No subsidy fee data for this period.</p>

  return (
    <div>
      <p>Total fees: {(summary as any)?.total ?? '—'}</p>
      {/* Pass chart datasets to your BarChart components */}
      <pre>{JSON.stringify(subsidyFeesChartData?.labels, null, 2)}</pre>
      <pre>{JSON.stringify(averageFeesChartData?.labels, null, 2)}</pre>
    </div>
  )
}
```

### `useUpdateExistedActions`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (
    <Button onClick={handleApply} disabled={selectedDevices.length === 0}>
      Apply to selected ({selectedDevices.length})
    </Button>
  )
}
```

## 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 Core (/v0-0-2/reference/app-toolkit/ui-core)

<PackageBadge>@tetherto/mdk-ui-core</PackageBadge>

<Callout type="info">
If you are building a React app with the MDK kit, start with the [React adapter](/v0-0-2/ui/react/get-started) instead. `<MdkProvider>` and 
adapter hooks such as `useAuth` and `useDevices` wrap this package so most React code never imports `@tetherto/mdk-ui-core` directly.

Use this reference when you need headless store access outside React (logging, websocket setup, test helpers) or when authoring a future framework adapter.
</Callout>

`@tetherto/mdk-ui-core` is the framework-agnostic headless layer of the [MDK App Toolkit](/v0-0-2/concepts/architecture/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`](/v0-0-2/reference/app-toolkit/hooks/state#useauth) |
| `devicesStore` | Fleet device list and current selection | [`useDevices`](/v0-0-2/reference/app-toolkit/hooks/state#usedevices) |
| `timezoneStore` | Active operator timezone | [`useTimezone`](/v0-0-2/reference/app-toolkit/hooks/state#usetimezone) |
| `notificationStore` | Unread notification counter (`count`, `increment`, `decrement`, `reset`) | [`useNotifications`](/v0-0-2/reference/app-toolkit/hooks/state#usenotifications) |
| `actionsStore` | Pending device and pool action submissions | [`useActions`](/v0-0-2/reference/app-toolkit/hooks/state#useactions) |

Import from `@tetherto/mdk-ui-core/store` (or the top-level barrel).

## QueryClient factory

`createMdkQueryClient` builds a TanStack Query Core client with environment-aware App Node base URL resolution:

1. Explicit override (typically from `<MdkProvider>`)
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()
```

`<MdkProvider>` wires these singleton stores into React and creates the shared `QueryClient` for adapter hooks.

## What's not here yet

Headless primitives will include throttled telemetry subscriptions, stale detection, history ring buffers, and an optimistic command state machine. 
They ship alongside the consuming code that needs them.

## Next steps

- [React get started](/v0-0-2/ui/react/get-started): three-package install and `<MdkProvider>`
- [Wire a React app](/v0-0-2/tutorials/ui/react/tutorial): full adapter wiring walkthrough
- [MDK App Toolkit architecture](/v0-0-2/concepts/architecture/app-toolkit): where UI Core fits in the frontend stack

# UI Kit (/v0-0-2/reference/app-toolkit/ui-kit)

The UI Kit is the frontend tools half of the [MDK App Toolkit](/v0-0-2/concepts/architecture/app-toolkit). This reference documents
its constants, React hooks, TypeScript types, and helper utilities.

## Browse by topic

| Topic | What's there |
|-------|--------------|
| [Constants](/v0-0-2/reference/app-toolkit/ui-kit/constants) | Colors, units, currency, chart configs and permissions, roles, header preferences|
| [Hooks](/v0-0-2/reference/app-toolkit/ui-kit/hooks) | Discover hooks for monitoring and UI patterns; full reference at [Hooks](/v0-0-2/reference/app-toolkit/hooks) |
| [Types](/v0-0-2/reference/app-toolkit/ui-kit/types) | TypeScript type exports. UI primitives and domain models like `Device`, `Alert` |
| [Utilities](/v0-0-2/reference/app-toolkit/ui-kit/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](/v0-0-2/reference/app-toolkit/ui-kit/constants#core-constants)
- [Types](/v0-0-2/reference/app-toolkit/ui-kit/types#core-types)
- [Utilities](/v0-0-2/reference/app-toolkit/ui-kit/utilities#core-utilities)

### `@tetherto/mdk-react-devkit/foundation`

- [Constants](/v0-0-2/reference/app-toolkit/ui-kit/constants#foundation-constants)
- [Types](/v0-0-2/reference/app-toolkit/ui-kit/types#foundation-types)
- [Utilities](/v0-0-2/reference/app-toolkit/ui-kit/utilities#foundation-utilities)
- [Hooks](/v0-0-2/reference/app-toolkit/hooks) — every App Toolkit hook (state, components, utilities) lives on a single overview page now.

# Constants (/v0-0-2/reference/app-toolkit/ui-kit/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](/v0-0-2/ui/react/core#prerequisites)

### Import
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

```tsx
  COLOR,
  UNITS,
  CURRENCY,
  CHART_COLORS,
  TABLE_COLORS,
  HASHRATE_LABEL_DIVISOR,
} from '@tetherto/mdk-react-devkit/core'
```

### Color constants

#### `COLOR`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Colors for table styling.

```tsx

TABLE_COLORS.HEADER_BG
TABLE_COLORS.ROW_HOVER
```

#### `HEATMAP`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

`HEATMAP` color scale for temperature and intensity displays.

```tsx
```

#### `CHART_COLORS`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Default chart color palette.

```tsx
```

#### `PIE_CHART_COLORS`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Color palette for pie and doughnut charts.

```tsx
```

#### `CATEGORICAL_COLORS`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

25-color categorical palette for multi-series charts.

```tsx

CATEGORICAL_COLORS[0]  // First color
CATEGORICAL_COLORS[24] // Last color
```

#### `TEMPERATURE_COLORS`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Color scale for temperature displays.

```tsx
```

#### `SOCKET_BORDER_COLOR`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Colors for socket status indicators.

```tsx
```

### Unit constants

#### `UNITS`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Maximum values for certain units.

```tsx

MAX_UNIT_VALUE.HUMIDITY_PERCENT     // 100
MAX_UNIT_VALUE.TEMPERATURE_PERCENT  // 100
```

#### `HASHRATE_LABEL_DIVISOR`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Default color array for chart datasets.

```tsx
```

#### `defaultChartOptions`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Default [Chart.js](https://www.chartjs.org/) options.

```tsx
```

#### `CHART_LEGEND_OPACITY`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Opacity values for chart legends.

```tsx
```

#### `CHART_PERFORMANCE`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Performance threshold constants for charts.

```tsx
```

#### `getChartAnimationConfig`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Get animation configuration based on data count.

```tsx

const animConfig = getChartAnimationConfig(dataPointCount)
```

#### `getDataDecimationConfig`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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](/v0-0-2/ui/react/foundation#prerequisites)

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

```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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Inline name used in confirmations and the `parseSettingsFile` import-error message.

```tsx

WEBAPP_NAME  // 'Appl.'
```

#### `WEBAPP_SHORT_NAME`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Flow keys consumed by [`PositionChangeDialog`](/v0-0-2/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
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

```tsx

type PositionChangeDialogFlowKey = keyof typeof POSITION_CHANGE_DIALOG_FLOWS
```

#### `PositionChangeDialogFlowValue` type
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

```tsx

type PositionChangeDialogFlowValue =
  (typeof POSITION_CHANGE_DIALOG_FLOWS)[PositionChangeDialogFlowKey]
```

### Header controls

#### `HEADER_ITEMS`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Array of header metric options for the [`HeaderControlsSettings`](/v0-0-2/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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Default visibility state for all header items (all `true`).

```tsx

DEFAULT_HEADER_PREFERENCES.poolMiners    // true
DEFAULT_HEADER_PREFERENCES.consumption   // true
```

#### `HeaderPreferences` type
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

```tsx

type HeaderPreferences = {
  poolMiners: boolean
  miners: boolean
  poolHashrate: boolean
  hashrate: boolean
  consumption: boolean
  efficiency: boolean
}
```

### Permissions

#### `AUTH_PERMISSIONS`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Permission access levels.

```tsx

AUTH_LEVELS.READ   // 'r'
AUTH_LEVELS.WRITE  // 'w'
```

#### `USER_ROLE`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Array of role options for select dropdowns.

```tsx

// [{ label: 'Admin', value: 'admin' }, ...]
```

#### `PERM_LEVEL_LABELS`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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 (/v0-0-2/reference/app-toolkit/ui-kit/hooks)

React hooks from `@tetherto/mdk-react-devkit`. The [Hooks reference](/v0-0-2/reference/app-toolkit/hooks) has the full catalog (including state and adapter hooks). Use the groups below to browse hooks by **Monitoring** and **UI** concern; each hook name links to its entry in that reference.

## Available hooks

| Group | Hooks |
|---|---|
| [Monitoring](/v0-0-2/reference/app-toolkit/hooks) | [`useChartDataCheck`](/v0-0-2/reference/app-toolkit/hooks/components#usechartdatacheck), [`useBeepSound`](/v0-0-2/reference/app-toolkit/hooks/utilities#usebeepsound) |
| [UI](/v0-0-2/reference/app-toolkit/hooks) | [`useNotification`](/v0-0-2/reference/app-toolkit/hooks/components#usenotification), [`useHeaderControls`](/v0-0-2/reference/app-toolkit/hooks/components#useheadercontrols), [`useSidebarExpandedState`](/v0-0-2/reference/app-toolkit/hooks/components#usesidebarexpandedstate), [`useSidebarSectionState`](/v0-0-2/reference/app-toolkit/hooks/components#usesidebarsectionstate), [`useHasPerms`](/v0-0-2/reference/app-toolkit/hooks/utilities#usehasperms), [`useCheckPerm`](/v0-0-2/reference/app-toolkit/hooks/utilities#usecheckperm), [`useLocalStorage`](/v0-0-2/reference/app-toolkit/hooks/utilities#uselocalstorage), [`usePagination`](/v0-0-2/reference/app-toolkit/hooks/utilities#usepagination), [`useIsFeatureEditingEnabled`](/v0-0-2/reference/app-toolkit/hooks/utilities#useisfeatureeditingenabled) |

# Types (/v0-0-2/reference/app-toolkit/ui-kit/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](/v0-0-2/ui/react/core#prerequisites)

### Import
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

```tsx
  ComponentSize,
  ButtonVariant,
  ColorVariant,
  Status,
  ApiResponse,
} from '@tetherto/mdk-react-devkit/core'
```

### Common types

#### `ComponentSize`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Extends `ComponentSize` with an icon-only variant.

```tsx
type ButtonSize = ComponentSize | 'icon'
```

#### `BorderRadius`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Border radius variants for form components.

```tsx
type BorderRadius = 'none' | 'small' | 'medium' | 'large' | 'full'
```

Used by: `Checkbox`, `Switch`, `Radio`.

#### `ColorVariant`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Comprehensive color variants for components.

```tsx
type ColorVariant =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

#### `StatusVariant`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Status variants for state indication.

```tsx
type StatusVariant = 'success' | 'processing' | 'error' | 'warning' | 'default' | 'idle'
```

Used by: badges, notifications, status indicators.

#### `ComponentColor`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Color options for form components.

```tsx
type ComponentColor = 'default' | 'primary' | 'success' | 'warning' | 'error'
```

Used by: `Checkbox`, `Switch`, `Radio`, `Typography`.

#### `Position`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Position/side options for UI elements.

```tsx
type Position = 'top' | 'right' | 'bottom' | 'left'
```

Used by: `Tooltip`, `Popover`, chart legends.

#### `TextAlign`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Text alignment options.

```tsx
type TextAlign = 'left' | 'center' | 'right' | 'justify'
```

#### `FlexAlign`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Flex/grid alignment options.

```tsx
type FlexAlign = 'start' | 'center' | 'end'
```

### Component types

#### `ButtonVariant`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Button visual variants.

```tsx
type ButtonVariant =
  | 'primary'
  | 'secondary'
  | 'danger'
  | 'tertiary'
  | 'link'
  | 'icon'
  | 'outline'
  | 'ghost'
```

#### `ButtonIconPosition`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Where icons appear in buttons.

```tsx
type ButtonIconPosition = 'left' | 'right'
```

#### `NotificationVariant`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Toast/notification variants.

```tsx
type NotificationVariant = 'success' | 'error' | 'warning' | 'info'
```

#### `BadgeStatus`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Badge status options.

```tsx
type BadgeStatus = 'success' | 'processing' | 'error' | 'warning' | 'default'
```

#### `TypographyColor`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Typography color options including muted.

```tsx
type TypographyColor = 'default' | 'primary' | 'success' | 'warning' | 'error' | 'muted'
```

### Utility types

#### `UnknownRecord`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Generic type for objects with unknown structure.

```tsx
type UnknownRecord = Record<string, unknown>
```

#### `Nullable` / `Optional` / `Maybe`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Null/undefined wrapper types.

```tsx
type Nullable<T> = T | null
type Optional<T> = T | undefined
type Maybe<T> = T | null | undefined
```

#### `Status`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Async operation status.

```tsx
type Status = 'idle' | 'loading' | 'success' | 'error'
```

### API types

#### `PaginationParams`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Pagination request parameters.

```tsx
type PaginationParams = {
  limit?: number
  offset?: number
  page?: number
}
```

#### `PaginatedResponse`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Paginated response wrapper.

```tsx
type PaginatedResponse<T> = {
  data: T[]
  page: number
  total: number
  totalPages: number
}
```

#### `ApiResponse`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

API response wrapper.

```tsx
type ApiResponse<T> = {
  data: T
  message?: string
  status: number
}
```

#### `ApiError`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

API error response structure.

```tsx
type ApiError = {
  error: string
  message: string
  status: number
  data?: {
    message?: string
  }
}
```

### Data table types
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Re-exported from TanStack Table for convenience.

```tsx
  DataTableColumnDef,
  DataTableExpandedState,
  DataTablePaginationState,
  DataTableRow,
  DataTableRowSelectionState,
  DataTableSortingState,
} from '@tetherto/mdk-react-devkit/core'
```

### Value types

#### `ValueUnit`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

A value paired with a unit, used for display formatting.

```tsx
type ValueUnit = {
  value: number | string | null
  unit: string
  realValue: number
}
```

#### `HashrateUnit` / `CurrencyUnit`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Specialized value-unit aliases.

```tsx
type HashrateUnit = ValueUnit
type CurrencyUnit = ValueUnit
```

#### `UnitLabel`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

SI-prefix unit labels.

```tsx
type UnitLabel = 'decimal' | 'k' | 'M' | 'G' | 'T' | 'P'
```

### Time types

#### `TimeRangeFormatted`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

A formatted time range.

```tsx
type TimeRangeFormatted = {
  start: string
  end: string
  formatted: string
}
```

#### `TimeInterval`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

A time interval with start/end timestamps.

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

### Chart types

#### `ChartLegendPosition`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Chart legend position options.

```tsx
type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'center' | 'chartArea'
```

#### `WeightedAverageResult`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Result from weighted average calculation.

```tsx
type WeightedAverageResult = {
  avg: number
  totalWeight: number
  weightedValue: number
}
```

#### `ErrorWithTimestamp`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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](/v0-0-2/ui/react/foundation#prerequisites)

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

```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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

The root device record. Used pervasively in the [operations centre](/v0-0-2/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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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<PosHistoryEntry[]>
  [key: string]: unknown
}
```

#### `PosHistoryEntry`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

A single past placement of a miner.

```tsx
type PosHistoryEntry = {
  container: string
  pos: string
  removedAt: number
}
```

#### `DeviceData`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

A `Device` specialized for containers, with container-specific `info` and `last` shapes.

```tsx
type Container = {
  info?: Partial<ContainerInfo>
  last?: Partial<ContainerLast>
} & Device
```

#### `ContainerInfo`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Cooling, supply, and pressure metadata for a container.

```tsx
type ContainerInfo = {
  container: string
  cooling_system: Record<string, unknown>
  cdu: Record<string, unknown>
  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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Last-snapshot wrapper for a container.

```tsx
type ContainerLast = {
  snap: {
    stats?: Partial<ContainerStats>
  }
  alerts: unknown[] | null
  err: string | null
}
```

#### `ContainerSnap`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

The `snap` payload found on `DeviceLast.snap` for both miners and containers. `stats` is what most components read.

```tsx
type ContainerSnap = {
  stats?: Partial<ContainerStats>
  config?: Record<string, unknown>
}
```

#### `ContainerStats`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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<ContainerSpecific>
  distribution_box1_power_w: number
  distribution_box2_power_w: number
  stats: Record<string, unknown>
  temperature_c: Partial<StatsTemperatureC>
  frequency_mhz: Partial<StatsFrequencyMhz>
  miner_specific: Partial<MinerSpecificStats>
  [key: string]: unknown
}
```

`status` is one of `running`, `offline`, `stopped` (see `CONTAINER_STATUS` in [Constants](/v0-0-2/reference/app-toolkit/ui-kit/constants#foundation-constants)).

#### `ContainerSpecific`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Container-specific stats (currently the PDU array).

```tsx
type ContainerSpecific = {
  pdu_data: Partial<ContainerPduData>[]
  [key: string]: unknown
}
```

#### `ContainerPduData`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Per-PDU power and status reading.

```tsx
type ContainerPduData = {
  power_w: number
  status: number
}
```

#### `StatsTemperatureC`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Temperature stats with per-chip detail.

```tsx
type StatsTemperatureC = {
  avg: number
  min: number
  max: number
  chips: TempChipData[]
  [key: string]: unknown
}
```

#### `StatsFrequencyMhz`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Frequency stats with per-chip detail.

```tsx
type StatsFrequencyMhz = {
  avg: number
  chips: ChipData[]
  [key: string]: unknown
}
```

#### `ChipData` / `TempChipData`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Per-chip readings.

```tsx
type ChipData = {
  index: number
  current: number
}

type TempChipData = {
  index: number
  max?: number
  min?: number
  avg?: number
}
```

#### `MinerSpecificStats`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Miner-specific stats blob.

```tsx
type MinerSpecificStats = {
  upfreq_speed: number
  [key: string]: unknown
}
```

### Miner types

#### `MinerStats`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Hashrate readings, currently just the rolling 5-minute window.

```tsx
type MinerHashrateMhs = {
  t_5m?: number
}
```

#### `MinerInfo`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Identifying info for a miner (used by miner record cards).

```tsx
type MinerInfo = {
  container?: string
  pos?: string
  macAddress?: string
  serialNum?: string
}
```

#### `MinerConfig`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Lightweight snapshot wrapper holding only `MinerConfig`.

```tsx
type MinerDeviceSnapshot = {
  last?: { snap?: { config?: MinerConfig } }
}
```

#### `MinerRecord`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Minimal power meter reading shape.

```tsx
type PowerMeter = {
  last?: {
    snap?: {
      stats?: {
        power_w?: number
      }
    }
  }
}
```

#### `LvCabinetRecord`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

LV cabinet record carrying its associated power meters.

```tsx
type LvCabinetRecord = {
  id: string
  powerMeters?: PowerMeter[]
}
```

### Config types

#### `GlobalConfig`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`](/v0-0-2/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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

A named group of segments (legend entry).

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

#### `TimelineChartData`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Visible time window for the `range` prop.

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

#### `AxisTitleText`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`](/v0-0-2/ui/react/foundation/reporting/operations-efficiency).

#### `MetricsEfficiencyLogEntry`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Summary block returned with the efficiency metrics response.

```tsx
type MetricsEfficiencySummary = {
  avgEfficiencyWThs: number | null
}
```

#### `MetricsEfficiencyResponse`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Wrapper for the efficiency metrics endpoint (`log` entries plus summary), using the shared `MetricsResponse` shape from `@tetherto/mdk-react-devkit/foundation`.

### Settings types

#### `SettingsUser`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Role option for select dropdowns. Also exported as the array `USER_ROLES` in [Constants](/v0-0-2/reference/app-toolkit/ui-kit/constants#foundation-constants).

```tsx
type RoleOption = {
  label: string
  value: string
}
```

#### `PermLevel`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Permission level values.

```tsx
type PermLevel = 'rw' | 'r' | false
```

#### `RolesPermissionsData`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

The shape consumed by [`RBACControlSettings`](/v0-0-2/ui/react/foundation/settings/access-control).

```tsx
type RolesPermissionsData = {
  permissions: Record<string, Record<string, PermLevel>>
  labels: Record<string, string>
}
```

#### `SettingsExportData`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

The export envelope produced and consumed by [`ImportExportSettings`](/v0-0-2/ui/react/foundation/settings/import-export). 
Generic `TExtra` lets you attach app-specific extras.

```tsx
type SettingsExportData<TExtra extends Record<string, unknown> = Record<string, unknown>> = {
  headerControls?: Record<string, boolean>
  featureFlags?: Record<string, boolean>
  timestamp?: string
  version?: string
} & TExtra
```

#### `ImportResult`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Result returned from settings import operations.

```tsx
type ImportResult = {
  success: boolean
  applied?: string[]
  errors?: string[]
  message?: string
}
```

# Utilities (/v0-0-2/reference/app-toolkit/ui-kit/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

## 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](/v0-0-2/ui/react/core#prerequisites)

### Import
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

```tsx
  formatNumber,
  formatHashrate,
  formatDate,
  formatRelativeTime,
  cn,
  isEmpty,
  isValidEmail,
} from '@tetherto/mdk-react-devkit/core'
```

### Formatting utilities

#### `formatNumber`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Format hashrate values with rounding.

```tsx

formatHashrate(150.456)  // "150.46"
formatHashrate(null)     // "-"
```

#### `formatCurrency`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Format currency values.

```tsx

formatCurrency(1234.56, 'USD')      // "$1,234.56"
formatCurrency(0.00012345, 'BTC')   // "₿0.00012345"
```

#### `getPercentFormattedNumber`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Format numbers as percentages.

```tsx

getPercentFormattedNumber(0.75)      // "75%"
getPercentFormattedNumber(0.1234, 1) // "12.3%"
```

#### `formatValueUnit`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Format value-unit objects.

```tsx

formatValueUnit(150, 'TH/s')  // "150 TH/s"
```

### Date utilities

#### `formatDate`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Format dates with customizable patterns.

```tsx

formatDate(new Date())                              // "Jan 15, 2025"
formatDate(1705334400000, { format: 'yyyy-MM-dd' }) // "2025-01-15"
```

#### `formatRelativeTime`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Format dates as relative time strings.

```tsx

formatRelativeTime(new Date(Date.now() - 3600000))  // "1h ago"
formatRelativeTime(new Date(Date.now() - 86400000)) // "1d ago"
```

#### `formatChartDate`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Format timestamps for chart display.

```tsx

formatChartDate(1705334400)        // "Jan 15"
formatChartDate(1705334400, true)  // "Jan 15, 2025"
```

#### `isValidTimestamp`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Check if a timestamp is valid.

```tsx

isValidTimestamp(1705334400000)  // true
isValidTimestamp('invalid')      // false
```

#### `parseMonthLabelToDate`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Parse month labels to `Date` objects.

```tsx

parseMonthLabelToDate('01-26')    // Date(2026, 0, 1)
parseMonthLabelToDate('03-2025')  // Date(2025, 2, 1)
```

#### `getPastDateFromDate`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Get a date in the past.

```tsx

getPastDateFromDate({ dateTs: Date.now(), days: 7 })  // 7 days ago
```

### Validation utilities

#### `isEmpty`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Validate email addresses.

```tsx

isValidEmail('user@example.com')  // true
isValidEmail('invalid')           // false
```

#### `isValidUrl`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Validate URLs.

```tsx

isValidUrl('https://example.com')  // true
isValidUrl('not-a-url')            // false
```

#### `isNil`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Check if value is `null` or `undefined`.

```tsx

isNil(null)       // true
isNil(undefined)  // true
isNil(0)          // false
isNil('')         // false
```

#### `isPlainObject`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Check if value is a plain object.

```tsx

isPlainObject({})           // true
isPlainObject({ a: 1 })     // true
isPlainObject([])           // false
isPlainObject(new Date())   // false
```

### Class name utilities

#### `cn`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Convert watts to megawatts.

```tsx

toMW(1000000)   // 1
toMWh(1000000)  // 1
```

#### `toPHS`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Convert raw hashrate to `PH/s`.

```tsx

toPHS(1000000000000000)  // 1
```

#### `convertMpaToBar`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Convert pressure units.

```tsx

convertMpaToBar(0.1)  // 1
```

#### `unitToKilo`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Convert to kilo units.

```tsx

unitToKilo(1000)  // 1
```

### Number utilities

#### `percentage`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Calculate percentage.

```tsx

percentage(25, 100)  // 25
percentage(1, 4)     // 25
```

#### `getPercentChange`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Calculate percentage change.

```tsx

getPercentChange(110, 100)  // 10
getPercentChange(90, 100)   // -10
```

#### `convertUnits`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Convert between SI-prefix units.

```tsx

convertUnits(1, 'k', 'M')           // 0.001
convertUnits(1000, 'decimal', 'k')  // 1
```

#### `safeNumber`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Safely convert to number.

```tsx

safeNumber('123')      // 123
safeNumber('invalid')  // 0
safeNumber(null)       // 0
```

### String utilities

#### `toTitleCase`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Convert string to Title Case.

```tsx

toTitleCase('hello world')  // "Hello World"
```

#### `formatMacAddress`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Format MAC addresses.

```tsx

formatMacAddress('aa:bb:cc:dd:ee:ff')  // "AA:BB:CC:DD:EE:FF"
```

#### `safeString`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Safely convert to string.

```tsx

safeString(123)    // "123"
safeString(null)   // ""
```

### Time utilities

#### `secondsToMs`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Convert seconds to milliseconds.

```tsx

secondsToMs(60)  // 60000
```

#### `breakTimeIntoIntervals`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Split time range into intervals.

```tsx

breakTimeIntoIntervals(start, end, 3600000)  // Array of 1-hour intervals
```

#### `timeRangeWalker`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Generator for iterating through time ranges.

```tsx

for (const interval of timeRangeWalker(start, end, duration)) {
  // Process each interval
}
```

### Color utilities

#### `hexToRgba`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Convert hex color to rgba.

```tsx

hexToRgba('#72F59E', 0.5)  // "rgba(114, 245, 158, 0.5)"
```

### Array utilities

#### `getNestedValue`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Get nested value by dot-path.

```tsx

getNestedValue({ a: { b: 1 } }, 'a.b')  // 1
```

#### `getWeightedAverage`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

Calculate weighted average.

```tsx

getWeightedAverage(items, 'value', 'weight')
```

#### `circularArrayAccess`
<PackageBadge>@tetherto/mdk-react-devkit/core</PackageBadge>

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](/v0-0-2/ui/react/foundation#prerequisites)

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

```tsx
  filterUsers,
  formatRoleLabel,
  formatLastActive,
  validateSettingsJson,
  parseSettingsFile,
  exportSettingsToFile,
} from '@tetherto/mdk-react-devkit/foundation'
```

### Settings utilities

#### `filterUsers`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`](/v0-0-2/reference/app-toolkit/ui-kit/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`
<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

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`](/v0-0-2/reference/app-toolkit/ui-kit/constants#webapp_name).

```tsx

const filename = exportSettingsToFile({
  headerControls: { poolMiners: true, consumption: false },
  featureFlags: { betaCharts: true },
  timestamp: new Date().toISOString(),
  version: '1.0.0',
})
```

# ORK reference (/v0-0-2/reference/ork)

`@tetherto/mdk-ork` is the orchestration kernel of the MDK stack. This subsection holds the canonical specs for its internal
modules. For the architectural narrative explaining how these modules fit together, see
[Architecture](/v0-0-2/concepts/architecture/ork).

## What's documented

- **[Modules](/v0-0-2/reference/ork/modules)**: per-module responsibility, interfaces, state machines, transition rules,
  crash-recovery procedures, and scaling characteristics.

# ORK modules (/v0-0-2/reference/ork/modules)

`@tetherto/mdk-ork`'s coordination splits across single-purpose modules. Each owns its own state machine, persistence boundary,
and scaling characteristics. Six modules ship in v0.0.1; two more (Fault Supervisor, Concurrency Manager) are deferred
to a later release.

For the architectural overview that explains how these modules connect, see
[Architecture](/v0-0-2/concepts/architecture/ork). 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

<Accordions>

<Accordion title="Command Dispatcher" id="command-dispatcher">

**Responsibility**: validates incoming commands against the generic MDK schema, checks permissions, and resolves the correct
worker based on the `deviceId`.

*Example*: when an App Node 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 App Node 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.

</Accordion>

<Accordion title="Command State Machine" id="command-state-machine">

**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).

</Accordion>

<Accordion title="Worker Registry" id="worker-registry">

**Responsibility**: the phonebook for the entire `@tetherto/mdk-ork` ecosystem. Maps which physical device IDs belong to which connected
worker channels and stores their declared capabilities.

*Example*: a `whatsminer-worker` connects and declares it manages `wm001` and `wm002`. The Registry saves this topology so the
Dispatcher knows exactly where to route a command for `wm001`.

**Interfaces**:

- *Input*: `identity.register` requests from workers.
- *Output*: internal events triggering full state lifecycle binding.
- *Functions*: `resolveWorkerState(target)`

**State machine**:

```mermaid
stateDiagram-v2
    [*] --> Unregistered
    Unregistered --> Discovered : DHT peer detected
    Discovered --> IdentitySaved : identity pulled
    IdentitySaved --> Ready : capabilities pulled
    Ready --> Terminated : eviction
    Terminated --> [*]
```

**Crash recovery**: rebuilt from state, which serves as a baseline to detect workers that were registered but failed to reconnect.

**Scalability**: read-heavy by nature; can be extracted into a read-replica architecture or partitioned by region or rack.

</Accordion>

<Accordion title="Telemetry Collector" id="telemetry-collector">

**Responsibility**: a lightweight proxy and routing layer between the upper system (UI / AI) and the downstream workers. Rather
than `@tetherto/mdk-ork` performing heavy time-series aggregations, the *worker* is responsible for storing and aggregating data for the
specific devices it controls. The Collector simply provides an interface to query this data and proxies the response up to the
UI (via App Node) or the AI Agent.

**Worker data handling (telemetry context)**:

- *Compaction*: the worker handles compaction of metrics over large time frames.
- *Local storage*: workers should save telemetry data in a local Hyper DB.
- *As-requested serving*: the worker serves data strictly when `@tetherto/mdk-ork` asks for it, precisely as dictated by the telemetry
schemas in `mdk-contract.json`.
- *Internal scheduling*: to achieve this without blocking `@tetherto/mdk-ork`, the worker may run its own internal scheduler for device
polling.

**Interfaces**:

- *Input*: client or AI telemetry queries (for example, "fetch metrics for device wm001").
- *Output*: normalized telemetry payloads passed straight through from the Worker to the requesting layer.
- *Functions*: `proxyTelemetryFetch(deviceId, queryArgs)`

**State machine**:

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Proxying : Request received
    Proxying --> RoutingToClient : Worker returns data
    Proxying --> Timeout : Worker unresponsive
    RoutingToClient --> Idle
```

**Scalability**: because the heavy lifting of data storage and aggregation is pushed down into the isolated worker processes,
the Collector remains stateless and highly scalable as a pure asynchronous router.

</Accordion>

<Accordion title="Scheduler" id="scheduler">

**Responsibility**: the system metronome. Triggers repetitive tasks without holding any domain-specific logic itself.

*Example*: emits an internal `tick` event every 5 seconds that the Health Monitor listens to, prompting it to ping all workers.

**Interfaces**:

- *Input*: system clock and configured task intervals.
- *Output*: injects intents (for example, `telemetry.pull`, `health.ping`) into the Dispatcher or Collector.
- *Functions*: `addJob(interval, intent)`, `removeJob(jobId)`

**State machine**:

```mermaid
stateDiagram-v2
    [*] --> Waiting
    Waiting --> Triggered : Interval elapsed
    Triggered --> Waiting
```

**Crash recovery**: timers re-initialize from zero on startup. Tasks are strictly idempotent.

**Scalability**: scales trivially. Requires basic distributed locking to avoid duplicate ticks in multi-process `@tetherto/mdk-ork`
deployments.

</Accordion>

<Accordion title="Health Monitor" id="health-monitor">

**Responsibility**: continuously evaluates the liveness and readiness of every registered worker to prevent routing messages to
dead nodes.

*Example*: if `health.ping` to a worker fails three times in a row, the Health Monitor marks the worker's status as `SICK` and
tells the Registry to halt routing new commands there.

**Interfaces**:

- *Input*: executes `health.ping` sequentially based on Scheduler ticks.
- *Output*: pushes status updates to the Registry.
- *Functions*: `pingWorker(workerId)`, `getHealth(workerId)`

**State machine**:

```mermaid
stateDiagram-v2
    [*] --> UNKNOWN
    UNKNOWN --> HEALTHY : Ping success
    HEALTHY --> SICK : Ping failed (1)
    SICK --> DEAD : Ping failed (threshold)
    SICK --> HEALTHY : Ping success
    DEAD --> HEALTHY : Reconnected
```

**Crash recovery**: blank slate on startup; re-evaluates all known workers immediately via ping.

**Scalability**: operates locally per `@tetherto/mdk-ork` kernel, or via independent lightweight ping agents.

</Accordion>

<Accordion title="Fault Supervisor (> v0.0.1)" id="fault-supervisor">

**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.

</Accordion>

<Accordion title="Concurrency Manager (> v0.0.1)" id="concurrency-manager">

**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.

</Accordion>

</Accordions>

# Protocol reference (/v0-0-2/reference/protocol)

The MDK Protocol is the contract that crosses every layer of the stack: Workers, `@tetherto/mdk-ork`, and the App Node all
exchange the same envelope. This subsection holds the canonical specs. For the architectural narrative explaining
how the protocol fits together, see [Architecture](/v0-0-2/concepts/architecture#the-mdk-protocol).

## What's documented

- **[Messages](/v0-0-2/reference/protocol/messages)**: envelope schema, request/response examples, the full action
  catalogue, and the base command set.

# Protocol messages (/v0-0-2/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](/v0-0-2/concepts/architecture#the-mdk-protocol).

## Envelope

```json
{
  "id":            "uuid-v4",
  "version":       "0.1.0",
  "type":          "request | response | event",
  "action":        "<protocol action>",
  "sender":        "<component:type:instance>",
  "target":        "<component:type:instance> | null",
  "deviceId":      "string | null",
  "timestamp":     1711640000000,
  "payload":       {}
}
```

External consumers (UI or AI agents) only provide `deviceId`; the `target` worker identity is internally resolved by `@tetherto/mdk-ork`.

A concrete request and response pair, end to end:

```json
// request: App Node asks @tetherto/mdk-ork to reboot device wm001
{
  "id": "8d1c-e3a4",
  "version": "0.1.0",
  "type": "request",
  "action": "command.request",
  "sender": "appNode:fleet-api:1",
  "target": null,
  "deviceId": "wm001",
  "timestamp": 1711640000000,
  "payload": { "command": "reboot" }
}

// response: @tetherto/mdk-ork relays the worker's terminal result
{
  "id": "1f9b-77c2",
  "version": "0.1.0",
  "type": "response",
  "action": "command.result",
  "sender": "ork:kernel:tx-1",
  "target": "appNode:fleet-api:1",
  "deviceId": "wm001",
  "timestamp": 1711640002145,
  "payload": { "status": "SUCCESS", "elapsedMs": 2145 }
}
```

## Actions

| Action | Type | Direction | Purpose |
|---|---|---|---|
| *(DHT presence)* | passive | Worker to DHT topic | Worker joins a known Hyperswarm topic; `@tetherto/mdk-ork` detects its peer connection automatically |
| `identity.request` | request | `@tetherto/mdk-ork` to Worker | Requests the worker's identity and managed devices |
| `capability.request` | request | `@tetherto/mdk-ork` to Worker | Asks the worker to declare its full capability schema |
| `state.pull` | request | `@tetherto/mdk-ork` to Worker | Worker returns a snapshot of state-machine status (low cadence tick, e.g., 60s) |
| `telemetry.pull` | request | `@tetherto/mdk-ork` to Worker | Worker returns device metrics plus history (medium cadence tick, e.g., 10s) |
| `command.request` | request | `@tetherto/mdk-ork` to Worker | Resolves the worker by `deviceId` and dispatches the command for execution |
| `health.ping` | request | `@tetherto/mdk-ork` to Worker | Liveness probe (high cadence tick, e.g., 5s) |

## Base command set

The protocol standardizes a Base Command Set supported by every worker:

- `getConfig`: retrieve current device configuration
- `setConfig`: update device configuration parameters
- `health`: fetch detailed diagnostic health status from the device

# Supported hardware (/v0-0-2/reference/supported-hardware)

<include>../../../_snippets/v0-0-2/monorepo/reference/supported-hardware.mdx</include>

# MDK Repositories (/v0-0-2/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](/v0-0-2/community/contributing#licensing).*

# Roadmap (/v0-0-2/resources/roadmap)

MDK follows a **monthly release cadence** to keep progress visible, collect feedback early, and progressively harden the platform from documentation and
developer tooling to production readiness.

## Roadmap principles

- **Release every month** to keep momentum and feedback loops short
- **Use milestone releases** to mark clear maturity jumps
- **Start with architecture and developer experience**, then harden through alpha and beta
- **Reach production readiness progressively**, not by a single large release

## 2026

2026 includes **four milestone releases**:

- **May — v0.1:** [Public foundation release](#v01-foundation-release)
- **August — v1.0:** [Developer preview](#v10-developer-preview)
- **October — v2.0:** [Pilot release](#v20-pilot-release)
- **December — v3.0:** [Stable production release](#v30-stable-production-release)

```mermaid
graph TB
    subgraph foundation [Foundation phase]
        v0_1([May 2026<br/><b>v0.1 Foundation release</b><br/>Docs + initial React components])
        iter_jun_jul[[June–July 2026<br/>Monthly iterations<br/>Architecture feedback, DX improvements]]
    end

    subgraph alpha [Developer preview]
        v1_0([August 2026<br/><b>v1.0 Developer preview</b><br/>First testable developer version])
        iter_sep[[September 2026<br/>Monthly iterations<br/>Integration hardening, bug fixing]]
    end

    subgraph beta [Pilot release]
        v2_0([October 2026<br/><b>v2.0 Pilot release</b><br/>First production pilot version])
        iter_nov[[November 2026<br/>Monthly iterations<br/>Stability, security, observability]]
    end

    subgraph stable [Stable phase]
        v3_0([December 2026<br/><b>v3.0 Stable release</b><br/>Production-ready baseline])
    end

    v0_1 --> iter_jun_jul
    iter_jun_jul --> v1_0
    v1_0 --> iter_sep
    iter_sep --> v2_0
    v2_0 --> iter_nov
    iter_nov --> v3_0

    style foundation fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
    style alpha fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
    style beta fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
    style stable fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
```

## Release plan

### v0.1 Foundation release

The first public release is mainly about **visibility, alignment, and feedback**.
It introduces the initial MDK documentation, core architecture concepts, and a set of React components for the frontend. The goal is to clearly show the direction of
MDK, explain the design choices, and invite feedback from developers, partners, and early contributors.

### June–July iterations

For June and July, the releases focus on incorporating community and internal feedback.
During this phase, the priority is to refine the architecture, improve documentation clarity, clean up developer experience, and validate whether the
abstractions are understandable and extensible before opening a wider alpha.

### v1.0 Developer preview

August's v1.0 release is the first **real developer alpha**.
At this stage, MDK should be testable end-to-end by external developers, even if still incomplete. The focus is on enabling experimentation, validating
the developer workflow, and surfacing integration gaps early. Stability is improving, but this release is still meant for controlled testing rather than
live production deployment.

### September iterations

After alpha feedback, September will be used for a platform hardening cycle. This month is dedicated to fixing critical issues, improving integration
reliability, expanding the most useful features, and preparing the system for real-world pilots.

### v2.0 Pilot release

October sees the release of v2.0, the first **beta release intended for production testing**.
The aim is that MDK should be stable enough to run in pilot environments with real operational pressure, while still being monitored closely. The objective is
to validate performance, robustness, deployment workflows, and operational fit in real scenarios before declaring the platform stable.

### November iterations

The month after the beta release is focused on closing the remaining production gaps. Priorities include bug fixing, security review, observability
improvements, documentation completion, and polishing the parts of the platform that are essential for broader production use.

### v3.0 Stable production release

The team aims to release v3.0, the first **stable release for production use** in December 2026.
By this point, MDK should offer a solid baseline for deployment in production environments, with stable core interfaces, validated workflows, and
documentation that supports adoption by operators, integrators, and developers building on top of the platform.

# Backend stack tutorials (/v0-0-2/tutorials/backend-stack)

<include>../../../../_snippets/v0-0-2/monorepo/tutorials/backend-stack.mdx</include>

# 2. Control from CLI (/v0-0-2/tutorials/backend-stack/cli)

<include>../../../../_snippets/v0-0-2/monorepo/tutorials/backend-stack/cli.mdx</include>

# 1. Run the stack (/v0-0-2/tutorials/backend-stack/run)

<include>../../../../_snippets/v0-0-2/monorepo/tutorials/backend-stack/run.mdx</include>

# Run a demo from stack to dashboard (/v0-0-2/tutorials/full-stack/dashboard)

<include>../../../../_snippets/v0-0-2/monorepo/tutorials/full-stack/dashboard.mdx</include>

# Your first component (/v0-0-2/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](/v0-0-2/tutorials/ui/react/tutorial).
</Callout>

## Prerequisites

<include>../../../../../_snippets/v0-0-2/ui-prerequisites.mdx</include>

<Steps>

<Step>

### Clone and build

<Callout type="info">
The MDK UI monorepo (`mdk-ui`) is an npm workspace. Clone the repository, install at the repo 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
```

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

  </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 monorepo 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 monorepo root
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 monorepo root, 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](/v0-0-2/ui/react/explore-the-demo)
- [Wire a React app](/v0-0-2/tutorials/ui/react/tutorial): add `<MdkProvider>` and adapter hooks for connected foundation components
- [Quickstart](/v0-0-2/ui/react/quickstart): minimum integration reference (install, provider, stores, theming)
- [Core](/v0-0-2/ui/react/core): primitives reference (`@tetherto/mdk-react-devkit/core`)
- [Foundation](/v0-0-2/ui/react/foundation): mining-domain components (`@tetherto/mdk-react-devkit/foundation`)

# Wire a React app (/v0-0-2/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](/v0-0-2/tutorials/ui/react/first-component). 
</Callout>

## Prerequisites

<include>../../../../../_snippets/v0-0-2/ui-prerequisites.mdx</include>

<Steps>

<Step>

### Clone and build

<Callout type="info">
The MDK UI monorepo (`mdk-ui`) is an npm workspace. Clone the repository, install at the repo 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
```

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

  </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 monorepo 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-core": "*",
```

  </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-core": "*", // [!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 monorepo root
npm install
```

</Step>

<Step>

### Wrap your app in MdkProvider

`<MdkProvider>` wires the headless stores from [`@tetherto/mdk-ui-core`](/v0-0-2/reference/app-toolkit/ui-core) 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](/v0-0-2/ui/react/quickstart#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"> {/* [!code ++] */}
      <App />
    </MdkProvider> {/* [!code ++] */}
  </StrictMode>,
)
```

  </Tab>
</Tabs>

</Step>

<Step>

### Use adapter hooks and render a component

Adapter hooks subscribe to Zustand stores and re-render when the selected slice changes. This example uses `useAuth` and `useDevices` from the adapter, then renders a presentational `SingleStatCard` from foundation.

#### 4.1 Replace `App.tsx`

```tsx

function App() {
  const { permissions } = useAuth()
  const { selectedDevices } = useDevices()

  return (
    <div style={{ padding: '2rem', display: 'grid', gap: '1rem', maxWidth: 360 }}>
      <h1>Operator dashboard</h1>
      <p>Selected devices: {selectedDevices?.length ?? 0}</p>
      <p>Permissions loaded: {permissions ? 'yes' : 'no'}</p>
      <SingleStatCard
        name="Inlet temperature"
        value={28}
        unit="°C"
        variant="primary"
      />
      <Button onClick={() => console.log('Ready for connected components')}>
        Log readiness
      </Button>
    </div>
  )
}

```

<Callout type="info">
Connected foundation components (device explorers, pool manager, settings dashboards) expect `<MdkProvider>` and often read multiple stores. Start with presentational imports while you wire your API; swap in connected components as your backend comes online.
</Callout>

</Step>

<Step>

### Run your app

From the monorepo root:

```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](/v0-0-2/ui/react/quickstart): install reference, store hooks, and theming
- [Core](/v0-0-2/ui/react/core): primitives reference (`@tetherto/mdk-react-devkit/core`)
- [Foundation](/v0-0-2/ui/react/foundation): mining-domain components (`@tetherto/mdk-react-devkit/foundation`)

### Run the demo app

If you are already at the monorepo root:

```bash
npm run dev:demo
```

If your shell is still in the app folder:

```bash
cd ../..    # apps/my-app → apps → monorepo root
npm run dev:demo
```

Open [http://localhost:5173/mdk](http://localhost:5173/mdk) to browse examples.

# UI Kit (/v0-0-2/ui)

## TL;Dr

<Callout type="info">
Today the published React path is complete; other frameworks are on the [roadmap](/v0-0-2/resources/roadmap) and will reuse the same headless core.
</Callout>

The MDK React UI Kit is a [three-layer stack](#how-the-layers-fit-together):

- [`@tetherto/mdk-ui-core`](/v0-0-2/reference/app-toolkit/ui-core): headless Zustand stores and TanStack Query client factory (framework-agnostic)
- [`@tetherto/mdk-react-adapter`](/v0-0-2/ui/react/quickstart#wrap-your-app-in-mdkprovider): `<MdkProvider>` and store hooks; binds the core into your UI runtime (React today)
- [`@tetherto/mdk-react-devkit`](/v0-0-2/ui/react/get-started): [`/core`](/v0-0-2/ui/react/core) primitives and [`/foundation`](/v0-0-2/ui/react/foundation) mining-domain components

## Framework quickstarts

<Cards>
  <Card
    icon={<Atom />}
    title={<span style={cardTitle}>React</span>}
    href="/v0-0-2/ui/react/get-started"
    description={
      <span style={cardProse}>
        Get started with the React MDK UI Kit
      </span>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Vue</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Reactive hooks for Vue via <code>@tetherto/mdk-vue</code>
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Svelte</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Reactive hooks for Svelte via <code>@tetherto/mdk-svelte</code>
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Web Components</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Framework-agnostic Web Components via <code>@tetherto/wc</code>
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
</Cards>

## How the layers fit together

The MDK React UI Kit and subsequent frameworks will share a similar architecture:

```mermaid
graph TB
    subgraph headless [Layer 1: Headless]
        uiCore([<b>mdk-ui-core</b><br/>Zustand stores · Query client factory<br/>Framework-agnostic])
    end

    subgraph adapter [Layer 2: Framework adapter]
        reactAdapter([<b>mdk-react-adapter</b><br/>MdkProvider · store hooks<br/>React today])
    end

    subgraph uiLib [Layer 3: Framework UI library]
        reactDevkit([<b>mdk-react-devkit</b><br/>/core + /foundation<br/>Primitives and mining-domain UI])
    end

    uiCore --> reactAdapter
    reactAdapter --> reactDevkit

    style headless fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
    style adapter fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
    style uiLib fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
```

## Next steps

- [Quickstart](/v0-0-2/ui/react/quickstart): integrate the three packages into your React app
- [Explore the demo](/v0-0-2/ui/react/explore-the-demo): run the demo app in your browser

# @tetherto/mdk-react-devkit (/v0-0-2/ui/react/core)

[The core entrypoint](/v0-0-2/resources/repositories) (`@tetherto/mdk-react-devkit/core`) provides the foundational **React** UI components, utilities, and theme system for the MDK React UI Kit. This is the `/core` subpath of the devkit package, not the framework-agnostic [`@tetherto/mdk-ui-core`](/v0-0-2/reference/app-toolkit/ui-core) headless package.

<Callout type="info">
Mining-domain components, hooks, and settings live on the [`/foundation`](/v0-0-2/ui/react/foundation) entrypoint. Both subpaths are exported from `@tetherto/mdk-react-devkit`.
</Callout>

## Prerequisites

<include>../../../../../_snippets/v0-0-2/package-prerequisites-install.mdx</include>

## What's included

### Components

Production-ready React components organized by category:

| Category | Description |
|----------|-------------|
| [Forms](/v0-0-2/ui/react/core/components/forms) | Input and form control components |
| [Overlays](/v0-0-2/ui/react/core/components/overlays) | Dialogs, popovers, tooltips, and toasts |
| [Data display](/v0-0-2/ui/react/core/components/data-display) | Cards, tables, tags, and data presentation |
| [Charts](/v0-0-2/ui/react/core/components/charts) | Data visualization components |
| [Navigation](/v0-0-2/ui/react/core/components/navigation) | Sidebar, tabs, and breadcrumbs |
| [Loading](/v0-0-2/ui/react/core/components/loading) | Spinners, loaders, and progress indicators |
| [Errors](/v0-0-2/ui/react/core/components/errors) | Error boundaries, error cards, and alerts |
| [Logs](/v0-0-2/ui/react/core/components/logs) | Log display components |

See the [Components reference](/v0-0-2/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`](/v0-0-2/reference/app-toolkit/ui-kit/utilities#formatnumber), [`formatHashrate`](/v0-0-2/reference/app-toolkit/ui-kit/utilities#formathashrate), [`formatCurrency`](/v0-0-2/reference/app-toolkit/ui-kit/utilities#formatcurrency): Number formatting
- [`formatDate`](/v0-0-2/reference/app-toolkit/ui-kit/utilities#formatdate), [`formatRelativeTime`](/v0-0-2/reference/app-toolkit/ui-kit/utilities#formatrelativetime): Date formatting
- [`cn`](/v0-0-2/reference/app-toolkit/ui-kit/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`](/v0-0-2/reference/app-toolkit/ui-kit/types#componentsize), [`ButtonVariant`](/v0-0-2/reference/app-toolkit/ui-kit/types#buttonvariant), [`ColorVariant`](/v0-0-2/reference/app-toolkit/ui-kit/types#colorvariant)
- [`Status`](/v0-0-2/reference/app-toolkit/ui-kit/types#status), [`PaginationParams`](/v0-0-2/reference/app-toolkit/ui-kit/types#paginationparams), [`ApiResponse`](/v0-0-2/reference/app-toolkit/ui-kit/types#apiresponse)
- Chart types, table types, and utility types

## Reference

Detailed reference material lives in the unified [Reference section](/v0-0-2/reference). Core (`/core`) slices are:

- [Constants](/v0-0-2/reference/app-toolkit/ui-kit/constants#core-constants): colors, units, currency, chart configs
- [Types](/v0-0-2/reference/app-toolkit/ui-kit/types#core-types): UI primitives, API shapes, value-unit types
- [Utilities](/v0-0-2/reference/app-toolkit/ui-kit/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)
```

## Troubleshooting

- **`npm install` warns about `engines.npm`, or `npm -v` is 10.x on Node 22** — [Upgrade npm](/v0-0-2/how-to/ui/react/upgrade-npm), then rerun `npm install` and `npm run build` from the monorepo root.

# Components (/v0-0-2/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](/v0-0-2/ui/react/quickstart)

<Accordions>
  <Accordion title="Show steps">
    <include>../../../../../../_snippets/v0-0-2/clone-build.mdx</include>
  </Accordion>
</Accordions>

- Import the core styles in your app's entry point:

```tsx
```
### Import named components

Declare the components you require:

```tsx
```

## Supported components

<ComponentTablesByCategory />

## Styling

Components use BEM-style CSS classes (e.g., `.mdk-button`, `.mdk-card__header`) for styling consistency and easy customization.

## 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 (/v0-0-2/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`)
- [Composition elements](/v0-0-2/ui/react/core/components/charts/composition): layout chrome, legends, stats rows, and chart utilities (`ChartContainer`, `ChartStatsFooter`, 
`DetailLegend`, helpers)

## Prerequisites

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

## All chart type components

<ComponentTable category="Charts" subcategory={null} pkg="core" />

## `AreaChart`

<ComponentDescription name="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',
    },
  ],
}

<AreaChart data={data} />
```

## `BarChart`

<ComponentDescription name="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',
    },
  ],
}

<BarChart data={data} height={300} />
```

### Data from hooks

Hand-built Chart.js `data` (above) is valid. When app hooks return `{ labels, series }` declarative input, convert with 
[`buildBarChartData`](/v0-0-2/ui/react/core/components/charts/composition#hook-shaped-bar-data) in [chart utilities](/v0-0-2/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' },
  ],
}

<BarChart data={data} isStacked />
```

### Horizontal bar chart

```tsx
<BarChart
  data={data}
  isHorizontal
  formatYLabel={(value) => `${value} TH/s`}
/>
```

### With data labels

```tsx
<BarChart
  data={data}
  showDataLabels
  formatDataLabel={(value) => `${value.toFixed(1)}%`}
/>
```

## `DoughnutChart`

<ComponentDescription name="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 |
| `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' },
]

<DoughnutChart data={data} />
```

## `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.

<ComponentDescription name="GaugeChart" />

<Callout type="info">
  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`](/v0-0-2/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](/v0-0-2/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.
</Callout>

### 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`](/v0-0-2/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
<GaugeChart percent={0.75} />
```

### In a chart card (same shell as other charts)

[`ChartContainer`](/v0-0-2/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

<ChartContainer title="Utilization" loading={false} empty={false}>
  <div style={{ overflow: 'hidden' }}>
    <GaugeChart percent={0.75} />
  </div>
</ChartContainer>
```

### Custom colors and arc

```tsx
<GaugeChart
  percent={0.6}
  colors={['#72F59E', '#FFD700', '#FF6B6B']}
  arcWidth={0.25}
  nrOfLevels={3}
  hideText={false}
  height={220}
/>
```

## `LineChart`

<ComponentDescription name="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 },
      ],
    },
  ],
}

<LineChart data={data} height={300} unit="TH/s" />
```

### 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,
    },
  ],
}

<LineChart data={data} showPointMarkers beginAtZero />
```

# Chart composition (/v0-0-2/ui/react/core/components/charts/composition)

Compose chart types from [Chart components](/v0-0-2/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`](/v0-0-2/ui/react/foundation/dashboard/charts#linechartcard)).

## Prerequisites

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

## Components

<ComponentTable category="Charts" subcategory="Composition" pkg="core" />

## `ChartContainer`

<ComponentDescription name="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 |
| `header` | Optional | `ReactNode` | none | Custom header node |
| `legendData` | Optional | `LegendItem[]` | none | Legend entries rendered in the container chrome |
| `highlightedValue` | Optional | `object` | none | Highlighted metric (`value`, optional `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`, optional `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
<ChartContainer loading={isLoading} empty={data.length === 0}>
  <BarChart data={data} />
</ChartContainer>
```

## `ChartStatsFooter`

<ComponentDescription name="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
<ChartStatsFooter
  stats={[
    { label: 'Min', value: '120 TH/s' },
    { label: 'Max', value: '180 TH/s' },
    { label: 'Avg', value: '150 TH/s' },
  ]}
/>
```

## `DetailLegend`

<ComponentDescription name="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
<DetailLegend
  items={[
    { label: 'Online', color: '#72F59E', currentValue: { value: 85, unit: '%' } },
    { label: 'Offline', color: '#FF6B6B', currentValue: { value: 15, unit: '%' } },
  ]}
/>
```

## 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`](/v0-0-2/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** (`<BarChart data={...} />`): pass the built object to the component; pair with `buildBarChartOptions` when you need stacking, axes, or formatters.

`BarChartInput` shape

| Field | Type | Description |
|-------|------|-------------|
| `labels` | `string[]` | Optional category labels; omitted labels are derived from series `values` keys or indices |
| `series` | `BarChartSeries[]` | Bar datasets (`label`, `values`, optional `color`, `stack`, `gradient`, bar layout props) |
| `lines` | `BarChartLine[]` | Optional line overlays on the same chart |
| `constants` | `BarChartConstant[]` | Optional horizontal reference lines |

Each `BarChartSeries` uses `values` as either `number[]` (positional) or `Record<string, number>` (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)
  })

<ChartContainer title="Quarterly" empty={isEmpty}>
  <BarChart data={chartData} />
</ChartContainer>
```

#### 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`](/v0-0-2/reference/app-toolkit/hooks/components#usechartdatacheck) from `@tetherto/mdk-react-devkit/foundation` 
with `{ data: chartData }`.

# Data display (/v0-0-2/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](/v0-0-2/ui/react/core#prerequisites)

## `DataTable`

<ComponentDescription name="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<Miner>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
  },
  {
    accessorKey: 'hashrate',
    header: 'Hashrate',
    cell: ({ row }) => `${row.original.hashrate} TH/s`,
  },
  {
    accessorKey: 'status',
    header: 'Status',
  },
]

function MinersTable() {
  return <DataTable columns={columns} data={miners} />
}
```

### With sorting and pagination

```tsx
const [sorting, setSorting] = useState<DataTableSortingState>([])
const [pagination, setPagination] = useState<DataTablePaginationState>({
  pageIndex: 0,
  pageSize: 10,
})

<DataTable
  columns={columns}
  data={miners}
  sorting={sorting}
  onSortingChange={setSorting}
  pagination={pagination}
  onPaginationChange={setPagination}
/>
```

### With row selection

```tsx
const [rowSelection, setRowSelection] = useState<DataTableRowSelectionState>({})

<DataTable
  columns={columns}
  data={miners}
  rowSelection={rowSelection}
  onRowSelectionChange={setRowSelection}
  enableRowSelection
/>
```

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

<ComponentDescription name="Card" />

### Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | none | Additional CSS class |
| `onClick` | `function` | none | Click handler (adds clickable styling) |
| `children` | `ReactNode` | none | Card content |

### Basic usage

```tsx
<Card>
  <Card.Header>Title</Card.Header>
  <Card.Body>Content goes here</Card.Body>
  <Card.Footer>Actions</Card.Footer>
</Card>
```

Default children are automatically wrapped in the body slot:

```tsx
<Card>
  <Card.Header>Title</Card.Header>
  This content goes to the body automatically
</Card>
```

### Clickable card

```tsx
<Card onClick={() => navigate('/details')}>
  <Card.Header>Click me</Card.Header>
  <Card.Body>Navigates on click</Card.Body>
</Card>
```

### 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

## `Accordion`

<ComponentDescription name="Accordion" />

### Import

```tsx
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from '@tetherto/mdk-react-devkit/core'
```

### `Accordion` props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | `''` | Accordion header title |
| `isOpened` | `boolean` | `false` | Initially expanded |
| `isRow` | `boolean` | `false` | Row layout for content |
| `unpadded` | `boolean` | `false` | Remove content padding |
| `noBorder` | `boolean` | `false` | Remove trigger border |
| `solidBackground` | `boolean` | `false` | Solid background color |
| `showToggleIcon` | `boolean` | `true` | Show expand/collapse icon |
| `toggleIconPosition` | `'left' \| 'right'` | `'left'` | Icon position |
| `customLabel` | `ReactNode` | none | Custom label next to title |
| `onValueChange` | `function` | none | Callback when state changes |

### Basic usage

```tsx
<Accordion title="FAQ Section">
  <p>This content can be expanded or collapsed.</p>
</Accordion>
```

### With custom label

```tsx
<Accordion
  title="System Status"
  customLabel={<Badge variant="success">Active</Badge>}
  showToggleIcon={false}
>
  <p>All systems operational.</p>
</Accordion>
```

### Multiple items

```tsx
<AccordionRoot type="multiple">
  <AccordionItem value="item-1">
    <AccordionTrigger>Section 1</AccordionTrigger>
    <AccordionContent>Content 1</AccordionContent>
  </AccordionItem>
  <AccordionItem value="item-2">
    <AccordionTrigger>Section 2</AccordionTrigger>
    <AccordionContent>Content 2</AccordionContent>
  </AccordionItem>
</AccordionRoot>
```

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

<ComponentDescription name="Badge" />

### Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `count` | `number` | `0` | Number to display |
| `overflowCount` | `number` | `99` | Max count before showing "99+" |
| `showZero` | `boolean` | `false` | Show badge when count is 0 |
| `dot` | `boolean` | `false` | Show as dot instead of number |
| `text` | `string` | none | Custom text content |
| `color` | [`ColorVariant`](/v0-0-2/reference/app-toolkit/ui-kit/types#colorvariant) | `'primary'` | Badge color |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Badge size |
| `status` | `'success' \| 'processing' \| 'error' \| 'warning' \| 'default'` | none | Status variant |
| `square` | `boolean` | `false` | Square badge (no border-radius) |
| `offset` | `[number, number]` | `[0, 0]` | Position offset [x, y] |

### Basic usage

```tsx
// Number badge on content
<Badge count={5}>
  <Button>Messages</Button>
</Badge>

// Overflow
<Badge count={100} overflowCount={99}>
  <BellIcon />
</Badge>
// Shows "99+"
```

### Dot badge

```tsx
<Badge dot>
  <NotificationIcon />
</Badge>
```

### Status badge

```tsx
<Badge status="success" text="Online" />
<Badge status="error" text="Offline" />
<Badge status="processing" text="Syncing" />
<Badge status="warning" text="Warning" />
```

### Standalone badge

```tsx
<Badge count={25} />
<Badge text="NEW" color="primary" square />
```

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

<ComponentDescription name="Pagination" />

### Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `current` | `number` | `1` | Current page number |
| `total` | `number` | `0` | Total number of items |
| `pageSize` | `number` | `20` | Items per page |
| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Page size options |
| `showSizeChanger` | `boolean` | `true` | Show page size dropdown |
| `showTotal` | `boolean` | `false` | Show total count text |
| `disabled` | `boolean` | `false` | Disable pagination |
| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Size variant |
| `onChange` | `function` | none | Page/size change callback |

### Basic usage

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

<Pagination
  current={page}
  total={500}
  pageSize={pageSize}
  onChange={(newPage, newSize) => {
    setPage(newPage)
    setPageSize(newSize)
  }}
/>
```

### With total display

```tsx
<Pagination
  current={1}
  total={100}
  pageSize={20}
  showTotal
/>
// 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`

<ComponentDescription name="Tag" />

### Import

```tsx
```

### Basic usage

```tsx
<Tag>Default Tag</Tag>
<Tag color="primary">Primary</Tag>
<Tag color="success">Success</Tag>
<Tag onClose={() => handleRemove()}>Removable</Tag>
```

## `Avatar`

<ComponentDescription name="Avatar" />

### Import

```tsx
```

### Basic usage

```tsx
<Avatar src="/user.jpg" alt="User" />
<Avatar>JD</Avatar>
<Avatar src="/user.jpg" size="lg" />
```

## `SkeletonBlock`

<ComponentDescription name="SkeletonBlock" />

### Import

```tsx
```

### Basic usage

```tsx
// Text skeleton
<SkeletonBlock className="h-4 w-48" />

// Circle skeleton
<SkeletonBlock className="h-12 w-12 rounded-full" />

// Card skeleton
<Card>
  <Card.Body>
    <SkeletonBlock className="h-4 w-full mb-2" />
    <SkeletonBlock className="h-4 w-3/4" />
  </Card.Body>
</Card>
```

## `EmptyState`

<ComponentDescription name="EmptyState" />

### Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `description` | `ReactNode` | none | **Required.** Description text |
| `image` | `'default' \| 'simple' \| ReactNode` | `'default'` | Image/icon to display |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |

### Basic usage

```tsx
<EmptyState description="No data available" />

<EmptyState
  description="No miners found matching your search"
  image="simple"
  size="sm"
/>
```

### Custom image

```tsx
<EmptyState
  description="No alerts at this time"
  image={<BellOffIcon size={48} />}
/>
```

### Styling

- `.mdk-empty-state`: Root container
- `.mdk-empty-state--{size}`: Size variant
- `.mdk-empty-state__image`: Image container
- `.mdk-empty-state__description`: Description text

## `Typography`

<ComponentDescription name="Typography" />

### Import

```tsx
```

### Basic usage

```tsx
<Typography variant="h1">Dashboard</Typography>
<Typography variant="h2">Miner status</Typography>
<Typography variant="body">
  Primary site operations are running within expected parameters.
</Typography>
<Typography variant="caption">Updated 2 minutes ago</Typography>
```

## `Indicator`

<ComponentDescription name="Indicator" />

### Import

```tsx
```

### Basic usage

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

<span className="flex items-center gap-2">
  <Indicator status="online" />
  Miner online
</span>
```

## `CurrencyToggler`

<ComponentDescription name="CurrencyToggler" />

### Import

```tsx
```

### Basic usage

```tsx
<CurrencyToggler
  value={currency}
  onChange={setCurrency}
  options={['USD', 'BTC', 'SAT']}
/>
```

## `ListViewFilter`

<ComponentDescription name="ListViewFilter" />

### Import

```tsx
```

### Basic usage

```tsx
<ListViewFilter
  search={search}
  onSearchChange={setSearch}
  filters={[
    { key: 'status', label: 'Status', options: ['online', 'offline'] },
    { key: 'site', label: 'Site', options: ['A', 'B', 'C'] },
  ]}
  activeFilters={activeFilters}
  onFilterChange={setActiveFilters}
/>
```

## `Mosaic`

<ComponentDescription name="Mosaic" />

### Import

```tsx
```

### Basic usage

```tsx
<Mosaic columns={3} gap={16}>
  <MosaicItem>
    <Card>Hashrate</Card>
  </MosaicItem>
  <MosaicItem span={2}>
    <Card>Active miners</Card>
  </MosaicItem>
  <MosaicItem>
    <Card>Power usage</Card>
  </MosaicItem>
</Mosaic>
```

# Errors (/v0-0-2/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](/v0-0-2/ui/react/core#prerequisites)

## `CoreAlert`

<ComponentDescription name="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 | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `'success' \| 'info' \| 'warning' \| 'error'` | `'info'` | Alert type |
| `title` | `ReactNode` | none | Main message |
| `description` | `ReactNode` | none | Additional description |
| `showIcon` | `boolean` | `false` | Show type icon |
| `icon` | `ReactNode` | none | Custom icon |
| `closable` | `boolean` | `false` | Show close button |
| `onClose` | `function` | none | Close callback |
| `banner` | `boolean` | `false` | Full-width banner style |
| `action` | `ReactNode` | none | Action element |

### Basic usage

```tsx
<CoreAlert type="info" title="System maintenance scheduled" showIcon />

<CoreAlert
  type="success"
  title="Configuration saved"
  description="Your settings have been updated successfully."
  showIcon
  closable
/>
```

### With action

```tsx
<CoreAlert
  type="warning"
  title="Low hashrate detected"
  description="Some miners are performing below expected levels."
  showIcon
  action={<Button size="sm">View Details</Button>}
/>
```

### Banner style

```tsx
<CoreAlert
  type="error"
  title="Connection lost"
  description="Unable to connect to the pool server."
  banner
  showIcon
/>
```

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

<ComponentDescription name="ErrorBoundary" />

### Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `fallback` | `ReactNode` | none | Custom fallback UI |
| `componentName` | `string` | none | Component name for error display |
| `onError` | `function` | none | Error callback |
| `children` | `ReactNode` | none | Children to wrap |

### Basic usage

```tsx
<ErrorBoundary fallback={<div>Something went wrong</div>}>
  <MyComponent />
</ErrorBoundary>
```

### With component name

```tsx
<ErrorBoundary
  componentName="HashrateChart"
  onError={(error, info) => console.error(error)}
>
  <HashrateChart data={data} />
</ErrorBoundary>
```

### Higher-order component

```tsx

const SafeChart = withErrorBoundary(
  Chart,
  'Chart',
  (error) => logError(error)
)

<SafeChart data={data} />
```

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

<ComponentDescription name="ErrorCard" />

### Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | none | Error title |
| `message` | `string` | none | Error message |
| `retry` | `function` | none | Retry callback (shows retry button) |

### Basic usage

```tsx
<ErrorCard
  title="Failed to load data"
  message="Unable to fetch miner statistics. Please try again."
  retry={() => refetch()}
/>
```

### Styling

- `.mdk-error-card`: Root container
- `.mdk-error-card__title`: Title text
- `.mdk-error-card__message`: Message text
- `.mdk-error-card__retry`: Retry button

## `NotFoundPage`

<ComponentDescription name="NotFoundPage" />

### Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | `'Page not found'` | Page title |
| `message` | `string` | none | Custom message |
| `backUrl` | `string` | `'/'` | Back button URL |

### Basic usage

```tsx
<NotFoundPage />

<NotFoundPage
  title="Miner not found"
  message="The miner you're looking for doesn't exist or has been removed."
  backUrl="/miners"
/>
```
### Styling

- `.mdk-not-found`: Root container
- `.mdk-not-found__title`: Title text
- `.mdk-not-found__message`: Message text
- `.mdk-not-found__back`: Back button

# Form components (/v0-0-2/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 `<Form>`
- [Composition](/v0-0-2/ui/react/core/components/forms/composition): the `<Form>` provider and the low-level building blocks 
(`FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`)
- [Prebuilt fields](/v0-0-2/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](/v0-0-2/ui/react/core#prerequisites).

## Controls

Standalone form controls. Manage `value` and `onChange`, or compose them inside [`<Form>`](/v0-0-2/ui/react/core/components/forms/composition#form) with 
[`FormField`](/v0-0-2/ui/react/core/components/forms/composition#formfield).

<ComponentTable category="Forms" subcategory={null} pkg="core" />

### `ActionButton`

<ComponentDescription name="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`](/v0-0-2/ui/react/core/components/overlays#toast) and **`Toaster`** 
from the same Toast setup as in [`overlays`](/v0-0-2/ui/react/core/components/overlays). This is the pattern the [demo app(../quickstart) applies.

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | none | Trigger button label |
| `variant` | `'primary' \| 'secondary' \| 'danger'` | `'secondary'` | Visual variant of the trigger [`Button`](#button) |
| `loading` | `boolean` | `false` | Loading state on the trigger |
| `disabled` | `boolean` | `false` | Disable the trigger |
| `className` | `string` | none | Class on the trigger |
| `mode` | `'popover' \| 'dialog'` | `'popover'` | **`popover`**: confirmation UI in an anchored popover. **`dialog`**: confirmation UI in a modal [`Dialog`](/v0-0-2/ui/react/core/components/overlays#dialog). |
| `confirmation` | `ActionButtonConfirmation` | none | **Required:** 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
<ActionButton
  label="Restart service"
  variant="danger"
  confirmation={{
    title: 'Restart service',
    description: 'The service will be unavailable briefly.',
    onConfirm: () => {
      void restartService()
    },
  }}
/>
```

#### Dialog mode

Set **`mode="dialog"`** when you want a full modal confirmation (for example irreversible or high-impact actions).

```tsx
<ActionButton
  label="Factory reset"
  variant="danger"
  mode="dialog"
  confirmation={{
    title: 'Confirm factory reset',
    description: 'This cannot be undone.',
    onConfirm: () => {
      void factoryReset()
    },
  }}
/>
```

### `Button`

<ComponentDescription name="Button" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'danger' \| 'tertiary' \| 'link' \| 'icon' \| 'outline' \| 'ghost'` | `'secondary'` | Visual variant |
| `size` | `'sm' \| 'md' \| 'lg'` | none | Button size |
| `loading` | `boolean` | `false` | Show loading spinner |
| `fullWidth` | `boolean` | `false` | Expand to container width |
| `icon` | `ReactNode` | none | Icon element |
| `iconPosition` | `'left' \| 'right'` | `'left'` | Icon placement |
| `disabled` | `boolean` | `false` | Disable interaction |

#### Basic usage

```tsx
<Button>Default Button</Button>
<Button variant="primary">Primary</Button>
<Button variant="danger">Delete</Button>
<Button variant="outline">Outline</Button>
```

#### With icon

```tsx
<Button icon={<PlusIcon />}>Add Item</Button>
<Button icon={<ArrowRightIcon />} iconPosition="right">
  Continue
</Button>
```

#### Loading state

```tsx
<Button loading>Saving...</Button>
<Button variant="primary" loading disabled>
  Processing
</Button>
```

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

<ComponentDescription name="Cascader" />

#### Import

```tsx
```

#### Basic usage

```tsx
<Cascader
  options={[
    {
      value: 'na',
      label: 'North America',
      children: [
        { value: 'us-east', label: 'US East' },
        { value: 'us-west', label: 'US West' },
      ],
    },
  ]}
  value={value}
  onChange={setValue}
/>
```

### `Checkbox`

<ComponentDescription name="Checkbox" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Checkbox size |
| `color` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error'` | `'primary'` | Color when checked |
| `radius` | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'` | `'none'` | Border radius |
| `checked` | `boolean \| 'indeterminate'` | none | Checked state (controlled) |
| `onCheckedChange` | `function` | none | Change callback |

#### Basic usage

```tsx
<Checkbox checked={checked} onCheckedChange={setChecked} />

<label className="flex items-center gap-2">
  <Checkbox checked={terms} onCheckedChange={setTerms} />
  I agree to the terms
</label>
```

#### Sizes and colors

```tsx
<Checkbox size="xs" />
<Checkbox size="sm" />
<Checkbox size="md" />
<Checkbox size="lg" color="success" />
```

#### Styling

- `.mdk-checkbox`: Root element
- `.mdk-checkbox--{size}`: Size modifier
- `.mdk-checkbox--{color}`: Color modifier
- `.mdk-checkbox__indicator`: Check mark container

### `DatePicker`

<ComponentDescription name="DatePicker" />

#### Import

```tsx
```

#### Basic usage

```tsx
<DatePicker
  value={date}
  onChange={setDate}
  placeholder="Select date"
/>
```

### `DateRangePicker`

<ComponentDescription name="DateRangePicker" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `selected` | `DateRange` | none | Selected `{ from, to }` range (controlled) |
| `onSelect` | `(range: DateRange \| undefined) => void` | none | Called when the user applies a range |
| `placeholder` | `string` | `'Pick a date range'` | Trigger text when no range is selected |
| `dateFormat` | `string` | `'MM/dd/yyyy'` | `date-fns` format used in the trigger label |
| `disabled` | `boolean` | `false` | Disable interaction |
| `showPresets` | `boolean` | `true` | Show the default preset buttons for the last 7, 14, 30, and 90 days |
| `presets` | `PresetItem[]` | none | Override the default preset list |
| `allowFutureDates` | `boolean` | `false` | When `false`, dates after today are disabled |
| `triggerClassName` | `string` | none | Extra classes for the trigger button |
| `calendarClassName` | `string` | none | Extra classes for the calendar |
| `modalClassName` | `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<DateRange>()

<DateRangePicker
  selected={range}
  onSelect={setRange}
/>
```

#### 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() } },
]

<DateRangePicker
  selected={range}
  onSelect={setRange}
  presets={presets}
/>
```

#### Allowing future dates

```tsx
<DateRangePicker
  selected={range}
  onSelect={setRange}
  allowFutureDates
  showPresets={false}
/>
```

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

<ComponentDescription name="Input" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | none | Visible label for the field |
| `variant` | `'default' \| 'search'` | `'default'` | Input variant |
| `size` | `'default' \| 'medium'` | `'default'` | Input size |
| `error` | `string` | none | Error message (shows red border) |
| `prefix` | `ReactNode` | none | Element before input |
| `suffix` | `ReactNode` | none | Element after input |
| `wrapperClassName` | `string` | none | Wrapper element class |

#### Basic usage

```tsx
<Input label="Email" placeholder="Enter email" id="email" />
<Input variant="search" placeholder="Search miners..." />
```

#### With prefix/suffix

```tsx
<Input prefix="$" suffix="USD" placeholder="0.00" />
<Input suffix="°C" placeholder="Temperature" />
<Input prefix={<UserIcon />} placeholder="Username" />
```

#### Error state

```tsx
<Input
  label="MAC Address"
  error="Invalid MAC address format"
  value={mac}
  onChange={(e) => 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`

<ComponentDescription name="Label" />

#### Import

```tsx
```

#### Basic usage

```tsx
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" />

<Label htmlFor="password" required>Password</Label>
<Input id="password" type="password" />
```

### `Radio`

<ComponentDescription name="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
```

#### Basic usage

```tsx
<RadioGroup value={value} onValueChange={setValue}>
  <Radio value="small">Small</Radio>
  <Radio value="medium">Medium</Radio>
  <Radio value="large">Large</Radio>
</RadioGroup>
```

**RadioCard** suits card-style, horizontal groups:

```tsx
<RadioGroup value={value} orientation="horizontal" onValueChange={setValue}>
  <RadioCard value="a" label="Option A" />
  <RadioCard value="b" label="Option B" />
</RadioGroup>
```

### `Select`

<ComponentDescription name="Select" />

#### Import

```tsx
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectItem,
  SelectGroup,
  SelectLabel,
} from '@tetherto/mdk-react-devkit/core'
```

#### `SelectTrigger` props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'sm' \| 'md' \| 'lg'` | `'lg'` | Trigger size |
| `variant` | `'default' \| 'colored'` | `'default'` | Visual variant |
| `color` | `string` | none | Custom color for colored variant (hex) |

#### Basic usage

```tsx
<Select value={value} onValueChange={setValue}>
  <SelectTrigger>
    <SelectValue placeholder="Select option" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">Option 1</SelectItem>
    <SelectItem value="option2">Option 2</SelectItem>
    <SelectItem value="option3">Option 3</SelectItem>
  </SelectContent>
</Select>
```

#### With groups

```tsx
<Select>
  <SelectTrigger size="md">
    <SelectValue placeholder="Select pool" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>North America</SelectLabel>
      <SelectItem value="us-east">US East</SelectItem>
      <SelectItem value="us-west">US West</SelectItem>
    </SelectGroup>
    <SelectGroup>
      <SelectLabel>Europe</SelectLabel>
      <SelectItem value="eu-west">EU West</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>
```

#### Colored variant

```tsx
<Select>
  <SelectTrigger variant="colored" color="#72F59E">
    <SelectValue placeholder="Status" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="active">Active</SelectItem>
    <SelectItem value="inactive">Inactive</SelectItem>
  </SelectContent>
</Select>
```

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

<ComponentDescription name="Switch" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Switch size |
| `color` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error'` | `'default'` | Color when checked |
| `radius` | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'` | `'none'` | Border radius |
| `checked` | `boolean` | none | Checked state (controlled) |
| `onCheckedChange` | `function` | none | Change callback |

#### Basic usage

```tsx
<Switch checked={enabled} onCheckedChange={setEnabled} />

<label className="flex items-center gap-2">
  <Switch checked={darkMode} onCheckedChange={setDarkMode} />
  Dark Mode
</label>
```

#### Sizes and colors

```tsx
<Switch size="sm" />
<Switch size="md" color="primary" />
<Switch size="lg" color="success" />
```

#### Styling

- `.mdk-switch`: Root element
- `.mdk-switch--{size}`: Size modifier
- `.mdk-switch--{color}`: Color modifier
- `.mdk-switch__thumb`: Toggle thumb

### `TagInput`

<ComponentDescription name="TagInput" />

#### Import

```tsx
```

#### Basic usage

```tsx
<TagInput
  value={tags}
  onChange={setTags}
  placeholder="Add tags..."
/>
```

### `TextArea`

<ComponentDescription name="TextArea" />

#### Import

```tsx
```

#### Basic usage

```tsx
<TextArea
  label="Description"
  placeholder="Enter description"
  rows={4}
  value={value}
  onChange={(e) => 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](/v0-0-2/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](/v0-0-2/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](/v0-0-2/ui/react/core/components/forms/fields) for the full prop reference and component-specific examples.

# Form composition (/v0-0-2/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](/v0-0-2/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](/v0-0-2/ui/react/core/components/forms#controls).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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](/v0-0-2/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 | Type | Default | Description |
|------|------|---------|-------------|
| `form` | `UseFormReturn` | required | The instance returned by `useForm()` |
| `children` | `ReactNode` | required | Form content |
| `onSubmit` | `FormEventHandler` | 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 | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | none | Fallback content shown when the field has no validation error |
| `className` | `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 (/v0-0-2/ui/react/core/components/forms/fields)

Form-bound fields pre-wired to React hook form. Each combines [`FormField`](/v0-0-2/ui/react/core/components/forms/composition#formfield), [`FormItem`](/v0-0-2/ui/react/core/components/forms/composition#formitem), [`FormLabel`](/v0-0-2/ui/react/core/components/forms/composition#formlabel), [`FormControl`](/v0-0-2/ui/react/core/components/forms/composition#formcontrol), [`FormDescription`](/v0-0-2/ui/react/core/components/forms/composition#formdescription), and [`FormMessage`](/v0-0-2/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](/v0-0-2/ui/react/core/components/forms#controls). To assemble a custom field from the building blocks, see [Composition](/v0-0-2/ui/react/core/components/forms/composition).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/ui/react/core#prerequisites)
- Wrap your form in [`<Form>`](/v0-0-2/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 | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | none | Label displayed above the field |
| `description` | `string` | none | Helper text below the field |
| `placeholder` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `CascaderOption[]` | required | Hierarchical options tree |
| `multiple` | `boolean` | `false` | Allow multiple selection |
| `cascaderProps` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `layout` | `'row' \| 'column'` | `'row'` | Whether the label sits inline with the checkbox or above it |
| `checkboxProps` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `datePickerProps` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `'text' \| 'email' \| 'password' \| 'number' \| ...` | `'text'` | HTML input type |
| `variant` | `'default' \| 'search'` | `'default'` | Input variant |
| `inputProps` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `FormRadioOption[]` | required | Array of `{ value, label, disabled? }` items |
| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Radio layout direction |
| `radioGroupProps` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `FormSelectOption[]` | required | Array of `{ value, label, disabled? }` items |
| `selectProps` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `layout` | `'row' \| 'column'` | `'row'` | Whether the label sits inline with the switch or above it |
| `switchProps` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `TagInputOption[]` | none | Suggested tags offered as autocomplete options |
| `allowCustomTags` | `boolean` | `true` | Let users type tags not present in `options` |
| `variant` | `'default' \| 'search'` | `'search'` | Visual variant |
| `tagInputProps` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `textAreaProps` | `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 (/v0-0-2/ui/react/core/components/loading)

Components for indicating loading and progress states.

## Prerequisites

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

## `Spinner`

<ComponentDescription name="Spinner" />

### Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Spinner size |
| `className` | `string` | none | Additional CSS class |

### Basic usage

```tsx
<Spinner />
<Spinner size="sm" />
<Spinner size="lg" />
```

### 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 | Type | Default | Description |
|------|------|---------|-------------|
| `fullscreen` | `boolean` | `false` | Cover entire viewport |
| `message` | `string` | none | Loading message |
| `className` | `string` | none | Additional CSS class |

### Basic usage

```tsx
<Loader />
<Loader message="Loading data..." />
<Loader fullscreen message="Please wait..." />
```

### In a container

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

### Styling

- `.mdk-loader`: Root container
- `.mdk-loader--fullscreen`: Fullscreen variant
- `.mdk-loader__spinner`: Spinner element
- `.mdk-loader__message`: Message text

# Log components (/v0-0-2/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](/v0-0-2/ui/react/core#prerequisites)

## `LogsCard`

<ComponentDescription name="LogsCard" />

### Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `logsData` | `LogData[]` | `[]` | Array of log entries |
| `type` | `string` | none | Log type identifier |
| `label` | `string` | none | Card label |
| `isLoading` | `boolean` | `false` | Show loading skeleton |
| `isDark` | `boolean` | `false` | Dark theme variant |
| `emptyMessage` | `string` | `'No incidents'` | Empty state message |
| `skeletonRows` | `number` | `5` | Number of skeleton rows |
| `pagination` | `LogPagination` | none | Pagination configuration |
| `onLogClicked` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `log` | `LogData` | none | **Required:** Log entry data |
| `type` | `string` | none | **Required:** Log type identifier |
| `style` | `CSSProperties` | none | Custom styles |
| `onLogClicked` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `LogData` | none | **Required:** Log entry data |
| `onLogClicked` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `string` | none | Log type identifier |
| `status` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `status` | `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 (/v0-0-2/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](/v0-0-2/ui/react/core#prerequisites)

## `Sidebar`

<ComponentDescription name="Sidebar" />

### Import

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

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `SidebarMenuItem[]` | none | **Required.** Menu items array |
| `activeId` | `string` | none | Currently active item ID |
| `expanded` | `boolean` | none | Controlled expanded state |
| `defaultExpanded` | `boolean` | `false` | Initial expanded state |
| `visible` | `boolean` | `true` | Sidebar visibility |
| `overlay` | `boolean` | `false` | Overlay mode (mobile) |
| `header` | `ReactNode` | none | Header content |
| `onItemClick` | `function` | none | Item click callback |
| `onExpandedChange` | `function` | none | Expand state callback |
| `onClose` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `defaultValue` | `string` | none | Initially active tab |
| `value` | `string` | none | Controlled active tab |
| `onValueChange` | `function` | none | Tab change callback |
| `variant` | `'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
```

### Basic usage

```tsx
<Breadcrumbs>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/miners">Miners</BreadcrumbItem>
  <BreadcrumbItem>Details</BreadcrumbItem>
</Breadcrumbs>
```

### Styling

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

# Overlays (/v0-0-2/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](/v0-0-2/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 | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | none | Dialog title |
| `description` | `string` | none | Dialog description |
| `closable` | `boolean` | `false` | Show close button |
| `onClose` | `function` | none | Close callback |
| `closeOnClickOutside` | `boolean` | `true` | Close when clicking outside |
| `closeOnEscape` | `boolean` | `true` | Close on Escape key |
| `bare` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | none | **Required.** Toast title |
| `description` | `string` | none | Additional description |
| `variant` | `'success' \| 'error' \| 'warning' \| 'info'` | `'info'` | Toast variant |
| `icon` | `ReactElement` | none | Custom icon |

### `ToastViewport` props

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

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

### Setup

```tsx

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

### Basic usage

```tsx

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

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

### Styling

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

## `Tooltip`

<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 (/v0-0-2/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](/v0-0-2/ui/react/core#prerequisites)

## Import

```tsx
// Import individual icons

// Import the factory function

// Import types
```

### Icon props

All icons accept the `IconProps` interface:

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

### Basic usage

```tsx

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

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

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

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

## Available icons

### Navigation icons

Icons for sidebar and navigation menus:

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

### Status icons

Icons for displaying operational status:

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

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

### Alarm icons

Icons for alerts and alarms:

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

### Weather icons

Icons for environmental conditions:

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

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

### Mining/stats icons

Icons for mining metrics and statistics:

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

### Measurement icons

Icons for measurements and readings:

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

### UI icons

General UI icons:

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

## Create custom icons

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

```tsx

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

### `CreateIconOptions`

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

### Dynamic color icons

For icons that need dynamic colors:

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

# Theme (/v0-0-2/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](/v0-0-2/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%);
}
```

# Explore the demo (/v0-0-2/ui/react/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

<include>../../../../_snippets/v0-0-2/ui-prerequisites.mdx</include>

## 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
npm install && npm run build
npm run dev:demo
```

  </Tab>
  <Tab value="https" label="HTTPS">

```bash
git clone https://github.com/tetherto/mdk.git
cd mdk
npm install && npm run build
npm run dev:demo
```

  </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-core`](/v0-0-2/reference/app-toolkit/ui-core), `@tetherto/mdk-react-adapter`, and `@tetherto/mdk-react-devkit` with `<MdkProvider>`.

## Next steps

- [Quickstart](/v0-0-2/ui/react/quickstart): install all three packages and wrap your app in `MdkProvider`
- [Wire a React app](/v0-0-2/tutorials/ui/react/tutorial): scaffold an app with `MdkProvider` and adapter hooks
- [Learn more about the React MDK UI Kit](/v0-0-2/ui/react/get-started)

# @tetherto/mdk-react-devkit (/v0-0-2/ui/react/foundation)

The [foundation entrypoint](/v0-0-2/resources/repositories) (`@tetherto/mdk-react-devkit/foundation`) provides **domain-specific React components, hooks, and constants**
assembled from [`@tetherto/mdk-react-devkit/core`](/v0-0-2/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`](/v0-0-2/ui/react/core). Both subpaths ship from `@tetherto/mdk-react-devkit`. Connected foundation components expect `<MdkProvider>` from [`@tetherto/mdk-react-adapter`](/v0-0-2/ui/react/get-started) and adapter store hooks.
</Callout>

## Prerequisites

<include>../../../../../_snippets/v0-0-2/package-prerequisites-install.mdx</include>

## What's included

| Feature | Description |
|---------|-------------|
| [Operations centre](/v0-0-2/ui/react/foundation/operations) | Bitcoin mining operations monitoring and management components |
| [Reporting tool](/v0-0-2/ui/react/foundation/reporting) | Operational reporting surfaces |
| [Settings](/v0-0-2/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](/v0-0-2/ui/react/foundation/operations) for the full component list with demo links.

### Settings

Pre-built settings UI for common administrative tasks:

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

### Hooks

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

### Constants

Shared [constants](/v0-0-2/reference/app-toolkit/ui-kit/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
```

## Troubleshooting

- **`npm install` warns about `engines.npm`, or `npm -v` is 10.x on Node 22** — [Upgrade npm](/v0-0-2/how-to/ui/react/upgrade-npm), then rerun `npm install` and `npm run build` from the monorepo root.

## Next steps

Consider the detailed [reference material](/v0-0-2/reference) for the foundation entrypoint:

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

# Alerts (/v0-0-2/ui/react/foundation/alerts)

Views for inspecting past alerts and incident history. Pair this page with the [dashboard](/v0-0-2/ui/react/foundation/dashboard) for live context.

## Prerequisites

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

### `HistoricalAlerts`

<ComponentDescription name="HistoricalAlerts" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `alerts` | `Alert[]` | `[]` | Pre-fetched historical alert entries |
| `isLoading` | `boolean` | `false` | Show table loading state |
| `localFilters` | `AlertLocalFilters` | required | Filters and search state shared with `CurrentAlerts` |
| `filterTags` | `string[]` | required | Active filter tags |
| `dateRange` | `HistoricalAlertsRange` | required | Controlled start/end timestamps (ms) |
| `onDateRangeChange` | `(range: HistoricalAlertsRange) => void` | required | Fires when the user picks a new range |
| `onAlertClick` | `(id?: string, uuid?: string) => void` | none | Row click handler |
| `className` | `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}
/>
```

#### Behaviour 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`.

## Next steps

- For live incident context, see [`ActiveIncidentsCard`](/v0-0-2/ui/react/foundation/dashboard/feeds#activeincidentscard) on the dashboard Feeds page

{/* TODO: The following additional alerts surfaces may be documented here in follow-up passes:

- `Alerts` — the feature wrapper that composes current and historical alerts into a single view
- `CurrentAlerts` — the active/in-progress alerts domain component
- `AlertsTableTitle` — reusable title row with optional subtitle slot
- `AlertConfirmationModal` — confirmation dialog for alert actions
- `TagFilterBar` — filter chip bar shared across alerts views */}

# Dashboard (/v0-0-2/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](/v0-0-2/ui/react/foundation/dashboard/feeds): active incidents and activity logs
- [Stats](/v0-0-2/ui/react/foundation/dashboard/stats): at-a-glance summary cards for containers, pool details, and export controls
- [Charts](/v0-0-2/ui/react/foundation/dashboard/charts): line, timeline, and multi-series chart cards

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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 (/v0-0-2/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](/v0-0-2/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

### `ConsumptionLineChart`

<ComponentDescription name="ConsumptionLineChart" />

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `TailLogEntry[]` | `[]` | Consumption log entries for the line series |
| `tag` | Optional | `string` | `'t-miner'` | Data tag that selects which aggregated power field to read |
| `timelineOptions` | Optional | `TimelineOption[]` | none | Range buttons shown above the chart; omit to hide the selector |
| `timeline` | Optional | `string` | none | Controlled active range; pair with `onTimelineChange` |
| `defaultTimeline` | Optional | `string` | none | Initial range when uncontrolled; falls back to `5m` (or `1m` when `isOneMinEnabled`) |
| `onTimelineChange` | Optional | `function` | none | Called with the new range value when the user changes timeline |
| `powerAttribute` | Optional | `string` | none | Overrides the derived power field name on each log entry |
| `label` | Optional | `string` | none | Legend label (default: total miner consumption text) |
| `rawConsumptionW` | Optional | `number \| string` | none | Raw consumption value for the detail legend |
| `isOneMinEnabled` | Optional | `boolean` | none | When `true`, adds a `1m` timeline option |
| `totalTransformerConsumption` | Optional | `boolean` | none | When `true`, uses transformer total consumption semantics |
| `isDetailed` | Optional | `boolean` | none | When `true`, shows the detail legend with the current value |
| `skipMinMaxAvg` | Optional | `boolean` | `false` | When `true`, hides the min/max/avg footer row |

#### Basic usage

```tsx
<ConsumptionLineChart
  data={consumptionLogs}
  timelineOptions={timelineOptions}
  defaultTimeline="5m"
/>
```

#### Controlled timeline

```tsx
const [timeline, setTimeline] = useState('5m')

const handleTimelineChange = (value: string) => setTimeline(value)

<ConsumptionLineChart
  data={consumptionLogs}
  timelineOptions={timelineOptions}
  timeline={timeline}
  onTimelineChange={handleTimelineChange}
/>
```

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

### `HashRateLineChartSelector`

<ComponentDescription name="HashRateLineChartSelector" />

All props are optional.

#### Import

```tsx
```

#### Behaviour

`HashRateLineChartSelector` renders one of two layouts based on `hasPoolLine`:

- `hasPoolLine={false}` (default) — a single hashrate line driven by `data` and `realtimeHashrateData`, with timeline range selector and a 
highlighted current-value readout.
- `hasPoolLine={true}` — a multi-series chart that overlays the miner's hashrate against per-pool breakdowns, driven by `minerTailLogData` 
and `minerPoolDataRaw`.

Pass the props for the layout you want; props for the other layout have no effect.

#### Layout

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `hasPoolLine` | Optional | `boolean` | `false` | When `true`, renders `HashRateLineChartWithPool`; when `false`, plain hashrate line |

#### Plain-layout props

Used when `hasPoolLine` is `false`.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `HashRateLogEntry[]` | `[]` | Historical hashrate log entries for the primary line |
| `realtimeHashrateData` | Optional | `HashRateLogEntry` | none | Latest sample merged into the series for the current-value readout |
| `fixedTimezone` | Optional | `string` | none | IANA timezone for axis tick formatting |
| `height` | Optional | `number` | none | Chart height in pixels |
| `loading` | Optional | `boolean` | none | When `true`, shows loading state and hides the footer readout |

#### Pool overlay layout props

Used when `hasPoolLine` is `true`.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `minerTailLogData` | Optional | `HashRateLogEntry[]` | `[]` | Miner hashrate samples (flat array or array of arrays) |
| `minerPoolDataRaw` | Optional | `MinerPoolDataItem[]` | `[]` | Per-pool hashrate samples overlaid on the miner line |
| `isMinerTailLogLoading` | Optional | `boolean` | `false` | When `true`, initial-load state for the miner series |
| `isMinerTailLogFetching` | Optional | `boolean` | `false` | When `true`, background refresh indicator for the miner series |
| `isMinerpoolInitialLoading` | Optional | `boolean` | `false` | When `true`, initial-load state for the pool overlay series |

#### Shared props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `isOneMinEnabled` | Optional | `boolean` | none | When `true`, adds a `1m` option to the timeline range selector in both layouts |

#### `HashRateLogEntry` type

```tsx
type HashRateLogEntry = {
  ts: number
  hashrate_mhs_1m_sum_aggr?: number
  [key: string]: unknown
}
```

#### `MinerPoolDataItem` type

```tsx
type PoolStat = {
  poolType: string
  hashrate: number
}

type MinerPoolDataItem = {
  stats: PoolStat[]
  ts: number | string
}
```

#### Basic usage

```tsx
<HashRateLineChartSelector
  data={hashrateHistory}
  realtimeHashrateData={currentHashrate}
  isOneMinEnabled
  height={400}
  loading={isLoading}
/>
```

#### With fixed timezone

```tsx
<HashRateLineChartSelector
  data={hashrateHistory}
  fixedTimezone="America/New_York"
  height={400}
  loading={false}
/>
```

#### With pool overlay

```tsx
<HashRateLineChartSelector
  hasPoolLine
  minerTailLogData={tailLog}
  isMinerTailLogLoading={isInitialLoading}
  isMinerTailLogFetching={isRefetching}
  minerPoolDataRaw={poolSamples}
  isMinerpoolInitialLoading={isPoolInitialLoading}
  isOneMinEnabled
/>
```

#### Features

- Timeline range selector: `5m`, `15m`, `1h`, `6h`, `24h`, `7d` (plus `1m` when `isOneMinEnabled`)
- Legend toggle: show/hide individual datasets
- Min/Max/Avg readout derived from the visible series
- Highlighted current-value readout (plain layout)
- Pool type breakdown overlay (pool overlay layout)

#### Styling

Built on `ChartContainer` and `LineChart` from `@tetherto/mdk-react-devkit/core`. The pool-overlay layout adds a `.mdk-hash-rate-line-chart-with-pool` root wrapper. See core chart styling for customization options.

### `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 |
| `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](/v0-0-2/reference/app-toolkit/ui-kit/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`](/v0-0-2/reference/app-toolkit/ui-kit/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`](/v0-0-2/reference/app-toolkit/ui-kit/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`](/v0-0-2/reference/app-toolkit/ui-kit/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`](/v0-0-2/reference/app-toolkit/ui-kit/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

# Feeds (/v0-0-2/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](/v0-0-2/ui/react/foundation#prerequisites)

### `ActiveIncidentsCard`

<ComponentDescription name="ActiveIncidentsCard" />

#### Import

```tsx
```

#### Props

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

#### `TIncidentRowProps`

Each incident item requires these properties:

| Prop | Type | Description |
|------|------|-------------|
| `id` | `string` | Unique incident identifier |
| `title` | `string` | Incident title |
| `subtitle` | `string` | Secondary text (e.g., timestamp or source) |
| `body` | `string` | Incident description |
| `severity` | `'critical' \| '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`](/v0-0-2/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
```

## Next steps

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

# Stats (/v0-0-2/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.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/ui/react/foundation#prerequisites)
- Most widgets expect a container [`Device`](/v0-0-2/reference/app-toolkit/ui-kit/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

Both provider-specific and general widgets are supported:

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

## Generic widgets

Widgets that work with any container vendor and pool configuration.

### `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" />

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

#### Import

```tsx
```

#### Props

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

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

#### Basic usage

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

#### More examples

<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`](/v0-0-2/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`](/v0-0-2/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`](/v0-0-2/ui/react/foundation/operations/containers#tankrow) internally for each tank display

## Vendor-specific widgets

Summary widgets that read vendor-shaped fields off a `Device` record. One component per vendor today.

### Bitmain Immersion

### `BitMainImmersionSummaryBox`

<ComponentDescription name="BitMainImmersionSummaryBox" />

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

#### Import

```tsx
```

#### Props

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

#### `BitMainImmersionSummaryBoxContainerSettings` type

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

```tsx

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

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

#### Basic usage

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

#### More examples

<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

### MicroBT

### `MicroBTWidgetBox`

<ComponentDescription name="MicroBTWidgetBox" />

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

#### Import

```tsx
```

#### Props

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

```tsx

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

#### Basic usage

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

#### Indicators rendered

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

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

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

#### Styling

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

# Operations centre (/v0-0-2/ui/react/foundation/operations)

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

<FoundationComponentTablesByCategory />

## Next steps

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

# Container components (/v0-0-2/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](/v0-0-2/ui/react/foundation#prerequisites)

## Container subpages

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

- [Socket](/v0-0-2/ui/react/foundation/operations/containers/socket) — PDU socket tile primitive
- [Bitdeer](/v0-0-2/ui/react/foundation/operations/containers/bitdeer)
- [Bitmain](/v0-0-2/ui/react/foundation/operations/containers/bitmain)
- [Bitmain Immersion](/v0-0-2/ui/react/foundation/operations/containers/bitmain-immersion)
- [MicroBT](/v0-0-2/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](/v0-0-2/ui/react/foundation/operations/containers/socket) page.

### `EnabledDisableToggle`

<ComponentDescription name="EnabledDisableToggle" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `unknown` | required | Current toggle value; boolean enables switch display |
| `tankNumber` | `number \| string` | required | Tank identifier; empty falls back to "Air Exhaust System" |
| `isButtonDisabled` | `boolean` | required | Disables both Enable and Disable buttons |
| `isOffline` | `boolean` | required | Marks container offline and disables controls |
| `onToggle` | `(params: { tankNumber, isOn: boolean }) => void` | required | 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 | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `DataItem[]` | `[]` | Rows to render as label, value, and units |
| `fallbackValue` | `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`](/v0-0-2/ui/react/foundation/dashboard/stats#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 | Type | Default | Description |
|------|------|---------|-------------|
| `index` | `number \| null` | none | Fan number shown in the badge |
| `enabled` | `boolean` | `false` | Renders on/off styling and icon color |
| `className` | `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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `fansData` | `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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `pumpTitle` | `string` | required | Pump label prefix (e.g. `"Oil"`, `"Water"`) |
| `pumpItem` | `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](/v0-0-2/ui/react/foundation/operations/device-explorer).
- For container-level controls, see [`ContainerControlsBox`](/v0-0-2/ui/react/foundation/operations/details-view/controls#containercontrolsbox) 
on the Controls page.
- For container summary widgets that surface on the dashboard, see [`TanksBox`](/v0-0-2/ui/react/foundation/dashboard/stats#tanksbox), 
[`SupplyLiquidBox`](/v0-0-2/ui/react/foundation/dashboard/stats#supplyliquidbox), and 
[`MinersSummaryBox`](/v0-0-2/ui/react/foundation/dashboard/stats#minerssummarybox).

# Bitdeer container components (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations). The PDU socket tile has its own [Socket](/v0-0-2/ui/react/foundation/operations/containers/socket) page.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | [`UnknownRecord`](/v0-0-2/reference/app-toolkit/ui-kit/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 | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `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" />

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

#### Import

```tsx
```

#### Props

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

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `tag` | `string` | none | Container tag used to scope chart data |
| `tankNumber` | `number \| string` | `1` | Tank index used to build backend attributes |
| `data` | `UnknownRecord[]` | none | Time-series entries to plot |
| `timeline` | `string` | `'24h'` | Initial time range |
| `dateRange` | `{ start?: number; end?: number }` | none | Explicit start/end window in ms |
| `fixedTimezone` | `string` | none | Forces a timezone for axis labels |
| `height` | `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 (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations). The PDU socket tile has its own [Socket](/v0-0-2/ui/react/foundation/operations/containers/socket) page.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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 | Type | Default | Description |
|------|------|---------|-------------|
| `data` | [`Device`](/v0-0-2/reference/app-toolkit/ui-kit/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 | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `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" />

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

#### Import

```tsx
```

#### Props

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

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `tag` | `string` | none | Container tag used to scope chart data |
| `chartTitle` | `string` | `'Liquid Pressure'` | Chart header title |
| `data` | `UnknownRecord[]` | none | Time-series entries to plot |
| `timeline` | `string` | `'24h'` | Initial time range |
| `dateRange` | `{ start?: number; end?: number }` | none | Explicit start/end window in ms |
| `fixedTimezone` | `string` | none | Forces a timezone for axis labels |
| `height` | `number` | none | Chart height in pixels |
| `showLegend` | `boolean` | `true` | Shows the series legend |
| `showRangeSelector` | `boolean` | `true` | Shows the timeline range selector |
| `footer` | `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`](/v0-0-2/reference/app-toolkit/ui-kit/utilities#convertmpatobar).

### `BitMainLiquidTempCharts`

<ComponentDescription name="BitMainLiquidTempCharts" />

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

#### Import

```tsx
```

#### Props

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

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

#### Import

```tsx
```

#### Props

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

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

#### Import

```tsx
```

#### Props

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

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | none | Label text shown next to the indicator |
| `status` | `'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 (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations). The PDU socket tile has its own [Socket](/v0-0-2/ui/react/foundation/operations/containers/socket) page.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | [`Device`](/v0-0-2/reference/app-toolkit/ui-kit/types#device) | required | 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 | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | none | Box title shown above the left column |
| `leftContent` | `ReactNode` | none | Content for the left column |
| `rightContent` | `ReactNode` | none | Content for the right column |
| `bottomContent` | `ReactNode` | none | Optional content for the bottom row |
| `secondary` | `boolean` | `false` | Borderless variant |
| `className` | `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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | none | Box title |
| `alarmStatus` | `boolean` | `false` | Shows `Fault` tag when true, `Normal` otherwise |
| `ready` | `boolean` | none | Ready state; row hidden when omitted |
| `operation` | `boolean` | none | Operating state; row hidden when omitted |
| `start` | `boolean` | none | Started state; row hidden when omitted |
| `className` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `Device` | none | Bitmain immersion container device record |
| `containerSettings` | `{ thresholds?: Record<string, unknown> } \| null` | `null` | Optional custom oil temperature thresholds |

#### 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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | none | Box title shown above the left column |
| `alarmStatus` | `boolean` | `false` | Shows `Fault` tag when true, `Normal` otherwise |
| `frequency` | `number` | none | Frequency value in Hz; row hidden when omitted |
| `isDryCooler` | `boolean` | `false` | Forces status label to `"Dry Cooler"` |
| `running` | `boolean` | `false` | Shows a running or off indicator |
| `showFrequencyInLeftColumn` | `boolean` | `false` | Renders the frequency row in the left column instead of the right |
| `secondary` | `boolean` | `false` | Borderless variant |
| `className` | `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 (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations). The PDU socket tile has its own [Socket](/v0-0-2/ui/react/foundation/operations/containers/socket) page.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `max` | `number` | required | Maximum value for the gauge |
| `value` | `number` | required | Current value |
| `unit` | `string` | required | Unit of measurement |
| `label` | `string` | `''` | Title shown above the gauge |
| `chartStyle` | `React.CSSProperties` | `{}` | Inline style on the chart wrapper |
| `colors` | `string[]` | `[COLOR.EMERALD, COLOR.SOFT_TEAL]` | Arc colors in HEX |
| `hideText` | `boolean` | `true` | Hides the built-in percentage text |
| `height` | `number` | `200` | Chart height in pixels |
| `className` | `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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | [`Device`](/v0-0-2/reference/app-toolkit/ui-kit/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 | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `Device` | none | MicroBT container device record |
| `containerSettings` | `{ thresholds?: Record<string, unknown> } \| null` | `null` | Optional custom inlet temperature thresholds |

#### 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" />

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

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `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 (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations).

## Prerequisites

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

### `Socket`

<ComponentDescription name="Socket" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `socket` | `number \| null` | `null` | Socket index shown in the cell |
| `enabled` | `boolean` | `false` | Whether the socket is powered |
| `selected` | `boolean` | `false` | Applies selected visual state |
| `current_a` | `number \| null` | `null` | Current draw in amperes |
| `power_w` | `number \| null` | `null` | Power draw in watts |
| `miner` | `Miner \| null` | `null` | Miner mounted in the socket |
| `heatmap` | `Heatmap \| null` | `null` | Heatmap configuration; see type below |
| `cooling` | `boolean \| undefined` | `undefined` | Shows cooling fan state when set |
| `isEditFlow` | `boolean` | `false` | Renders the add-miner flow UI |
| `clickDisabled` | `boolean` | `false` | Disables socket click interactions |
| `isEmptyPowerDashed` | `boolean` | `false` | Shows zero power with dashed border |
| `isContainerControlSupported` | `boolean` | `false` | Affects tooltip copy for controls |
| `pdu` | `{ pdu?: string \| number }` | none | PDU metadata used for `data-pdu-index` |
| `innerRef` | `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 (/v0-0-2/ui/react/foundation/operations/details-view)

UI for the details view opened from the [device explorer](/v0-0-2/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](/v0-0-2/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`](/v0-0-2/reference/app-toolkit/ui-kit/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](/v0-0-2/ui/react/foundation/operations/details-view/charts): fleet-level activity visualizations
- [Chips](/v0-0-2/ui/react/foundation/operations/details-view/chips): per-hashboard ASIC chip telemetry
- [Controls](/v0-0-2/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](/v0-0-2/ui/react/foundation/operations/details-view/fleet-management): dialogs for adding, replacing, moving, and removing miners across containers
- [Stats](/v0-0-2/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 | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | `'Miner info'` | Card header label, rendered uppercase |
| `data` | `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`](/v0-0-2/reference/app-toolkit/ui-kit/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 (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations/details-view/stats). For miner identity (`MinerInfoCard`), see the [details view overview](/v0-0-2/ui/react/foundation/operations).

## Prerequisites

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

## Components

<ComponentTable category="Details view" subcategory="Charts" pkg="foundation" />

### `MinersActivityChart`

<ComponentDescription name="MinersActivityChart" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `MinersActivityData` | `{}` | Counts keyed by status name |
| `large` | `boolean` | `false` | Switch to large indicator and label sizing |
| `isLoading` | `boolean` | `false` | Render a spinner instead of the chart |
| `isError` | `boolean` | `false` | Render `CoreAlert` instead of the chart (unless `isDemoMode`) |
| `error` | `{ data?: { message?: string } } \| null` | `null` | Message surfaced inside the error alert |
| `showLabel` | `boolean` | `true` | Show the per-status text label under each indicator |
| `isDemoMode` | `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' } }}
/>

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

#### Styling

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

# Chips (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations). For aggregated stats, see [Stats](/v0-0-2/ui/react/foundation/operations/details-view/stats). For fleet activity, see [Charts](/v0-0-2/ui/react/foundation/operations/details-view/charts).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/ui/react/foundation#prerequisites)
- A [`ContainerStats`](/v0-0-2/reference/app-toolkit/ui-kit/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 | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `ContainerStats` | required | 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 | Type | Default | Description |
|------|------|---------|-------------|
| `index` | `number` | required | Chip index, displayed as the tile title (`Chip {index}`) |
| `frequency` | `{ current: number }` | required | Current frequency in MHz |
| `temperature` | `{ avg: number; min: number; max: number }` | required | 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 (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations). For aggregated stats, see [Stats](/v0-0-2/ui/react/foundation/operations/details-view/stats). For fleet activity, see [Charts](/v0-0-2/ui/react/foundation/operations/details-view/charts).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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`](/v0-0-2/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 | Type | Default | Description |
|------|------|---------|-------------|
| `buttonsStates` | `Record<string, boolean \| undefined>` | required | Per-action disable flags. Currently consumed: `isSetUpFrequencyButtonDisabled` |
| `isLoading` | `boolean` | required | Renders the loading spinner and disables every action |
| `showPowerModeSelector` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `selectedDevices` | [`Device`](/v0-0-2/reference/app-toolkit/ui-kit/types#device)`[]` | `[]` | Miners targeted by the dropdown; used to derive the model groups |
| `setPowerMode` | `(devices: Device[], mode: string) => void` | none | Callback fired with the matching device subset when a mode is chosen |
| `connectedMiners` | `Device[]` | none | Used to compute the current power mode summary when `powerModesLog` is not provided |
| `powerModesLog` | [`UnknownRecord`](/v0-0-2/reference/app-toolkit/ui-kit/types#unknownrecord) | none | Pre-computed per-model current power modes (overrides the derived value) |
| `disabled` | `boolean` | none | Disable every dropdown |
| `hasMargin` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `isBatch` | `boolean` | `true` | Toggle the title between `Batch Container Controls` and `Container Controls` |
| `isCompact` | `boolean` | none | Forwarded to `ContainerControlsBox` for the compact layout |
| `connectedMiners` | `unknown` | none | Forwarded to `ContainerControlsBox` when exactly one container is selected |
| `alarmsDataItems` | `TimelineItemData[]` | none | Forwarded alarm timeline data |
| `onNavigate` | `(path: string) => void` | 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 | Type | Default | Description |
|------|------|---------|-------------|
| `data` | [`Device`](/v0-0-2/reference/app-toolkit/ui-kit/types#device) | none | Container device data |
| `isBatch` | `boolean` | `false` | Enable batch operations mode |
| `selectedDevices` | `Device[]` | `[]` | Selected devices for batch operations |
| `pendingSubmissions` | `PendingSubmission[]` | `[]` | Pending action submissions |
| `alarmsDataItems` | `TimelineItemData[]` | `[]` | Active alarms to display |
| `tailLogData` | [`UnknownRecord`](/v0-0-2/reference/app-toolkit/ui-kit/types#unknownrecord)`[]` | none | Tail log data for power modes |
| `onNavigate` | `(path: string) => void` | required | 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 (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations). For the buttons that open most of these dialogs, see [Controls](/v0-0-2/ui/react/foundation/operations/details-view/controls).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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`](/v0-0-2/reference/app-toolkit/ui-kit/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 | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | required | Controls dialog visibility |
| `onClose` | `(currentDialogFlow: string, isDontReset?: boolean) => void` | required | Called when the dialog closes; receives the active flow key so callers can decide whether to reset selection state |
| `selectedSocketToReplace` | [`UnknownRecord`](/v0-0-2/reference/app-toolkit/ui-kit/types#unknownrecord) | none | Socket payload for the destination socket in a position-change or replace flow |
| `selectedEditSocket` | [`UnknownRecord`](/v0-0-2/reference/app-toolkit/ui-kit/types#unknownrecord) | none | Socket payload for the miner being edited, replaced, or moved |
| `onChangePositionClicked` | `() => void` | none | Fired when the user picks "Change position" in the default flow |
| `onPositionChangedSuccess` | `() => void` | none | Fired after a successful confirm-change-position submission |
| `isContainerEmpty` | `boolean` | `false` | Hint for the container-selection step that the destination container has no occupied sockets |
| `dialogFlow` | `string` | `''` | Initial flow key from [`POSITION_CHANGE_DIALOG_FLOWS`](/v0-0-2/reference/app-toolkit/ui-kit/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 | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | required | Controls dialog visibility |
| `onClose` | `() => void` | required | Called when the dialog closes |
| `selectedSocketToReplace` | [`UnknownRecord`](/v0-0-2/reference/app-toolkit/ui-kit/types#unknownrecord) | none | Socket payload for the empty socket receiving a new miner |
| `selectedEditSocket` | [`UnknownRecord`](/v0-0-2/reference/app-toolkit/ui-kit/types#unknownrecord) | none | Socket payload for an existing miner when running the change-info flow |
| `currentDialogFlow` | `string` | none | Flow key from [`POSITION_CHANGE_DIALOG_FLOWS`](/v0-0-2/reference/app-toolkit/ui-kit/constants#position_change_dialog_flows); typically `replaceMiner` or `changeInfo` |
| `isDirectToMaintenanceMode` | `boolean` | `false` | Register the new miner straight into the maintenance container instead of the selected socket |
| `minersType` | `string` | none | Restricts the form to a specific miner type (used to gate model-specific validation) |
| `isContainerEmpty` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | required | Controls dialog visibility |
| `onClose` | `(value?: boolean) => void` | required | Called when the dialog closes |
| `miner` | [`Device`](/v0-0-2/reference/app-toolkit/ui-kit/types#device) | none | The miner being moved out of maintenance |
| `containers` | [`Device[]`](/v0-0-2/reference/app-toolkit/ui-kit/types#device) | `[]` | Candidate destination containers shown in the picker |
| `isLoading` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `selectedEditSocket` | `Partial<{ miner: Device, containerInfo: { container?: string } }>` | none | Socket payload for the miner being moved to maintenance |
| `onCancel` | `() => void` | 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 | Type | Default | Description |
|------|------|---------|-------------|
| `headDevice` | [`Device`](/v0-0-2/reference/app-toolkit/ui-kit/types#device) | `{}` | The miner being removed; the dialog reads `info.pos` for the confirmation copy |
| `isRemoveMinerFlow` | `boolean` | required | Controls dialog visibility |
| `onCancel` | `() => void` | required | 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 (/v0-0-2/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](/v0-0-2/ui/react/foundation/operations). For fleet activity visualizations, see [Charts](/v0-0-2/ui/react/foundation/operations/details-view/charts). For per-chip thermal data, see [Chips](/v0-0-2/ui/react/foundation/operations/details-view/chips).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/ui/react/foundation#prerequisites)
- Components on this page read live metrics from `device.last.snap.stats` on a [`Device`](/v0-0-2/reference/app-toolkit/ui-kit/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`](/v0-0-2/reference/app-toolkit/ui-kit/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 (/v0-0-2/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](/v0-0-2/ui/react/foundation#prerequisites)

### `DeviceExplorer`

<ComponentDescription name="DeviceExplorer" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `deviceType` | `'container' \| 'miner' \| 'cabinet'` | required | Current view type |
| `data` | `Device[]` | required | Array of devices to display |
| `filterOptions` | `DeviceExplorerFilterOption[]` | required | `Cascader` filter options |
| `searchOptions` | `DeviceExplorerSearchOption[]` | required | Search autocomplete options |
| `searchTags` | `string[]` | required | Current search tags |
| `onSearchTagsChange` | `(tags: string[]) => void` | required | Search tags change handler |
| `onDeviceTypeChange` | `(type: DeviceExplorerDeviceType) => void` | required | Device type tab change handler |
| `onFiltersChange` | `(value: LocalFilters) => void` | required | Filter change handler |
| `selectedDevices` | `DataTableRowSelectionState` | `{}` | Selected row state |
| `onSelectedDevicesChange` | `(selections: DataTableRowSelectionState) => void` | none | Selection change handler |
| `renderAction` | `(device: Device) => ReactNode` | none | Custom action column renderer |
| `getFormattedDate` | `(date: Date) => string` | required | Date formatter function |
| `className` | `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

## Next steps

- For selecting and acting on an individual device, see the [details view](/v0-0-2/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 (/v0-0-2/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](/v0-0-2/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 three subpages plus this index:

- [Dashboard](/v0-0-2/ui/react/foundation/pool-manager/dashboard): landing page composing stats, navigation blocks, and a recent alerts feed
- [Miner explorer](/v0-0-2/ui/react/foundation/pool-manager/miner-explorer): cross-pool miner browser with filter, search, and selection; used to assign miners to pool configurations
- [Pools](/v0-0-2/ui/react/foundation/pool-manager/pools): pools page with the collapsible pool list and the **Add Pool** dialog for authoring new pool configurations

## All Pool Manager components

<ComponentTable category="Pool Manager" pkg="foundation" />

# Dashboard (/v0-0-2/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](/v0-0-2/ui/react/foundation/pool-manager/miner-explorer). For pool and endpoint management, see [Pools](/v0-0-2/ui/react/foundation/pool-manager/pools).

## Prerequisites

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

## Components

<ComponentTable category="Pool Manager" subcategory="Dashboard" pkg="foundation" />

### `PoolManagerDashboard`

<ComponentDescription name="PoolManagerDashboard" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `stats` | `DashboardStats` | none | Dashboard statistics |
| `isStatsLoading` | `boolean` | `false` | Stats loading state |
| `alerts` | `Alert[]` | `[]` | Recent alerts list |
| `onNavigationClick` | `(url: string) => void` | required | Navigation handler |
| `onViewAllAlerts` | `() => void` | required | 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

## Next steps

- For pool summary widgets that surface on the top-level operations dashboard, see
[`PoolDetailsCard`](/v0-0-2/ui/react/foundation/dashboard/stats#pooldetailscard) and [`PoolDetailsPopover`](/v0-0-2/ui/react/foundation/dashboard/stats#pooldetailspopover).

# Miner explorer (/v0-0-2/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](/v0-0-2/ui/react/foundation/pool-manager/pools). For the Pool Manager landing surface, see [Dashboard](/v0-0-2/ui/react/foundation/pool-manager/dashboard).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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](/v0-0-2/reference/app-toolkit/ui-kit/types)

## Components

<ComponentTable category="Pool Manager" subcategory="Miner explorer" pkg="foundation" />

### `PoolManagerMinerExplorer`

<ComponentDescription name="PoolManagerMinerExplorer" />

#### Import

```tsx
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `miners` | `Device[]` | required | Fleet miners to browse |
| `poolConfig` | `PoolConfigData[]` | required | Pool configurations used for the pool filter and assign flow |
| `backButtonClick` | `() => void` | required | 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 (/v0-0-2/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](/v0-0-2/ui/react/foundation/pool-manager/miner-explorer). For the landing surface, see [Dashboard](/v0-0-2/ui/react/foundation/pool-manager/dashboard).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/v0-0-2/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 | Type | Default | Description |
|------|------|---------|-------------|
| `poolConfig` | `PoolConfigData[]` | required | Pool configuration source; hydrated by `usePoolConfigs` |
| `backButtonClick` | `() => void` | required | 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

# Reporting tool (/v0-0-2/ui/react/foundation/reporting)

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

Reporting-tool components cover operational analytics (efficiency, consumption, and related views). 
Host apps supply API or tail-log data; components handle layout, charts, and tab navigation.

## Prerequisites

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

## Component groups

- [Operational efficiency](./operations-efficiency): three-tab efficiency dashboard (`OperationsEfficiency`)

## Reporting components

<FoundationComponentTablesByCategory categories={["Reporting tool"]} />

# Operational efficiency (/v0-0-2/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](/v0-0-2/ui/react/foundation#prerequisites)
- [`@tetherto/mdk-react-devkit/core`](/v0-0-2/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`](/v0-0-2/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`](/v0-0-2/reference/app-toolkit/ui-kit/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`](/v0-0-2/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 |

### 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](/v0-0-2/reference/app-toolkit/ui-kit/types#metrics-efficiency-types): `MetricsEfficiencyLogEntry` and 
response wrapper for the site tab
- [Chart composition](/v0-0-2/ui/react/core/components/charts/composition): `buildBarChartData` for bar chart `data` shapes

# Settings components (/v0-0-2/ui/react/foundation/settings)

The [`@tetherto/mdk-react-devkit/foundation`](/v0-0-2/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`](/v0-0-2/ui/react/foundation/settings/feature-flags),
   [`HeaderControlsSettings`](/v0-0-2/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 | Type | Default | Description |
|------|------|---------|-------------|
| `showFeatureFlags` | `boolean` | `false` | Show the feature flags section (requires `featureFlagsProps`) |
| `headerControlsProps` | [`HeaderControlsSettingsProps`](/v0-0-2/ui/react/foundation/settings/header-controls) | none | Props for header controls section |
| `rbacControlProps` | [`RBACControlSettingsProps`](/v0-0-2/ui/react/foundation/settings/access-control) | none | Props for RBAC/user management section |
| `importExportProps` | [`ImportExportSettingsProps`](/v0-0-2/ui/react/foundation/settings/import-export) | none | Props for import/export section |
| `featureFlagsProps` | [`FeatureFlagsSettingsProps`](/v0-0-2/ui/react/foundation/settings/feature-flags) | none | Props for feature flags section |
| `dangerActions` | `ActionButtonProps[]` | none | Entries forwarded to [`ActionButton`](/v0-0-2/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` | `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`](/v0-0-2/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](/v0-0-2/ui/react/core/components/forms#actionbutton)**.

## Accordion sections

The dashboard renders each settings section inside an [`Accordion`](/v0-0-2/ui/react/core/components/data-display#accordion) component
from [`@tetherto/mdk-react-devkit/core`](/v0-0-2/ui/react/core):

- **[Header Controls](/v0-0-2/ui/react/foundation/settings/header-controls)**: toggle visibility of header metrics
- **[Access control](/v0-0-2/ui/react/foundation/settings/access-control)**: manage users and role-based permissions
- **[Import / Export](/v0-0-2/ui/react/foundation/settings/import-export)**: backup and restore configuration
- **[Feature Flags](/v0-0-2/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 (/v0-0-2/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](/v0-0-2/ui/react/foundation#prerequisites)

## Import

```tsx
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `canWrite` | `boolean` | none | **Required:** If `false`, hides edit/delete actions |
| `users` | `SettingsUser[]` | none | **Required:** Array of users to display |
| `roles` | `RoleOption[]` | none | **Required:** Available roles for assignment |
| `rolePermissions` | `Record<string, Record<string, PermLevel>>` | none | **Required:** Permissions matrix by role |
| `permissionLabels` | `Record<string, string>` | none | **Required:** Human-readable permission names |
| `onCreateUser` | `function` | none | **Required:** Create user callback |
| `onUpdateUser` | `function` | none | **Required:** Update user callback |
| `onDeleteUser` | `function` | none | **Required:** Delete user callback |
| `isLoading` | `boolean` | `false` | Loading state |
| `className` | `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()`](/v0-0-2/reference/app-toolkit/ui-kit/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 (/v0-0-2/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](/v0-0-2/ui/react/foundation#prerequisites)

## Import

```tsx
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isEditingEnabled` | `boolean` | none | **Required:** If `false`, shows empty state and other props have no effect |
| `featureFlags` | `Record<string, boolean>` | none | **Required:** Object mapping flag names to enabled/disabled state |
| `onSave` | function | none | **Required:** Callback when save is clicked |
| `isLoading` | `boolean` | `false` | Loading state |
| `isSaving` | `boolean` | `false` | Saving state |
| `className` | `string` | none | Additional CSS class |

## Data structure

The `featureFlags` prop accepts an object where:
- **Keys** are flag names (arbitrary strings defined by your application)
- **Values** are booleans (`true` = enabled, `false` = disabled)

```tsx
{
  darkMode: true,
  betaFeatures: false,
  advancedMetrics: true,
}
```

This component renders toggles for whatever flags you pass in. Your application or backend determines the available flags.

## Basic usage

Changes are held locally until the user clicks Save. The `onSave` callback receives the updated flags object:

```tsx
const handleSave = async (updatedFlags: Record<string, boolean>) => {
  await api.saveFeatureFlags(updatedFlags)  // persist to backend
  setFlags(updatedFlags)                     // update local state
}
```

<Callout type="warning">
The component does not persist data, you must implement the save logic.
</Callout>

### Example

```tsx

function FeatureFlagsPage() {
  // Flags reflecting your API or app config
  const [flags, setFlags] = useState<Record<string, boolean>>({
    darkMode: true,
    betaFeatures: false,
    advancedMetrics: true,
  })
  const [isSaving, setIsSaving] = useState(false)

  const handleSave = async (updatedFlags: Record<string, boolean>) => {
    setIsSaving(true)
    await api.saveFeatureFlags(updatedFlags)
    setFlags(updatedFlags)
    setIsSaving(false)
  }

  return (
    <FeatureFlagsSettings
      featureFlags={flags}
      isEditingEnabled={true}
      isSaving={isSaving}
      onSave={handleSave}
    />
  )
}
```

## Features

### Add flags

Developers add new feature flags through the UI by entering comma-separated names. Flag names are arbitrary strings; the component does not validate
against a predefined list.

### Toggle flags

Each flag displays a toggle switch to enable/disable it. Changes are held locally until the end user clicks **Save**.

### Delete flags

End user can click the trash icon next to any flag to remove it from the list.

## Permission check

When `isEditingEnabled` is `false`, the component renders an empty state:

```tsx
<FeatureFlagsSettings
  featureFlags={flags}
  isEditingEnabled={false}  // Shows "Update feature flags not enabled"
  onSave={handleSave}
/>
```

## Integration

Feature flags are typically fetched from your backend API. This component provides the UI for viewing and editing them, it does not manage persistence.
Use the `onSave` callback to sync changes back to your server.

## Styling

The component uses the `.mdk-settings-feature-flags` CSS class. Key selectors:

{/*todo: add link back: https://github.com/tetherto/mdk/blob/main/ui-client/packages/foundation/src/components/domain/settings/feature-flags/feature-flags-settings.scss*/}

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

# Header controls settings (/v0-0-2/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](/v0-0-2/ui/react/foundation#prerequisites)

## Import

```tsx
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `preferences` | [`HeaderPreferences`](/v0-0-2/reference/app-toolkit/ui-kit/constants#headerpreferences-type) | none | **Required:** Current header visibility preferences |
| `onToggle` | function | none | **Required:** Callback when a toggle changes |
| `onReset` | function | none | **Required:** Callback to reset to defaults |
| `isLoading` | `boolean` | `false` | Loading state |
| `className` | `string` | none | Additional CSS class |

## Data structure

The `HeaderPreferences` type maps header item keys to visibility booleans. See [constants](/v0-0-2/reference/app-toolkit/ui-kit/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`](/v0-0-2/reference/app-toolkit/ui-kit/constants#header_items). Labels for the in-app rows (`miners`, `hashrate`) are composed from [`WEBAPP_SHORT_NAME`](/v0-0-2/reference/app-toolkit/ui-kit/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

# Import/export settings (/v0-0-2/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](/v0-0-2/ui/react/foundation#prerequisites)

## Import

```tsx
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onExport` | `function` | none | **Required:** Callback to trigger settings export |
| `onImport` | `function` | none | **Required:** Callback when import is confirmed |
| `onParseFile` | `function` | none | **Required:** Parse and validate uploaded file |
| `isExporting` | `boolean` | `false` | Export in progress |
| `isImporting` | `boolean` | `false` | Import in progress |
| `className` | `string` | none | Additional CSS class |

## Data structure

The [`SettingsExportData`](/v0-0-2/reference/app-toolkit/ui-kit/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 (/v0-0-2/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`](/v0-0-2/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](/v0-0-2/ui/react/foundation#prerequisites)

## `AddUserModal`

<ComponentDescription name="AddUserModal" />

## Import

```tsx
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | — | **Required:** Whether the modal is visible |
| `roles` | `array` | — | **Required:** Available roles for selection |
| `onSubmit` | `function` | — | **Required:** Called with form data on submit |
| `onClose` | `function` | — | **Required:** Called when modal should close |
| `isSubmitting` | `boolean` | `false` | Shows loading state on submit button |

### `RoleOption` structure

Full type: [`RoleOption` in Types reference](/v0-0-2/reference/app-toolkit/ui-kit/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 | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | — | **Required:** Whether the modal is visible |
| `user` | [`SettingsUser`](/v0-0-2/reference/app-toolkit/ui-kit/types#settingsuser) | — | **Required:** User being edited |
| `roles` | `array` | — | **Required:** Available roles |
| `rolePermissions` | `object` | — | **Required:** Permissions by role |
| `permissionLabels` | `object` | — | **Required:** Permission display names |
| `onSubmit` | `function` | — | **Required:** Called with updated data on submit |
| `onClose` | `function` | — | **Required:** Called when modal should close |
| `isSubmitting` | `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 | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | — | **Required:** Whether the modal is visible |
| `title` | `string` | — | **Required:** Modal title |
| `children` | `ReactNode` | — | Modal body content |
| `onConfirm` | `function` | — | **Required:** Called when end user confirms |
| `onClose` | `function` | — | **Required:** Called when end user cancels or closes |
| `confirmText` | `string` | `'Confirm'` | Text for confirm button |
| `destructive` | `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

# Get started with React (/v0-0-2/ui/react/get-started)

## 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`](/v0-0-2/ui/react/core) and [`/foundation`](/v0-0-2/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="/v0-0-2/ui/react/quickstart"
    description={
      <>
        <span style={cardProse}>
          Install all three packages, wrap in MdkProvider, wire stores and theming
        </span>
        <span style={cardTime}>⏱️ &lt;3 min</span>
      </>
    }
  />
  <Card
    icon={<Compass />}
    title={<span style={cardTitle}>Explore the demo</span>}
    href="/v0-0-2/ui/react/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}>⏱️ &lt;1 min</span>
      </>
    }
  />
  <Card
    icon={<BookOpen />}
    title={<span style={cardTitle}>Tutorial</span>}
    href="/v0-0-2/tutorials/ui/react/tutorial"
    description={
      <>
        <span style={cardProse}>
          Step-by-step app scaffold with MdkProvider, adapter hooks, and foundation components
        </span>
        <span style={cardTime}>⏱️ &lt;5 min</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>mdk-ui CLI</span>}
    href="/v0-0-2/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Agent-first tooling via <code>@tetherto/mdk-ui-cli</code> — registry, scaffold, and docs for agents
        </span>
        <span style={cardCta}>Coming soon</span>
      </>
    }
  />
</Cards>

## Prerequisites

<include>../../../../_snippets/v0-0-2/ui-prerequisites.mdx</include>

## About the React stack

The React UI Kit is published as **three workspace packages** in the [MDK monorepo](https://github.com/tetherto/mdk): 

- **[`@tetherto/mdk-ui-core`](/v0-0-2/reference/app-toolkit/ui-core)** — 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-core` 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-core`** 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`](/v0-0-2/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`](/v0-0-2/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 package](/v0-0-2/ui/react/core) providing primitives: buttons, forms, charts, and themes
- Explore the [foundation package](/v0-0-2/ui/react/foundation) providing mining-domain components and hooks
- See the [UI Kit overview](/v0-0-2/ui) for how the headless layer fits other frameworks
- Browse the [Hooks](/v0-0-2/reference/app-toolkit/hooks) reference — [state](/v0-0-2/reference/app-toolkit/hooks/state), [component](/v0-0-2/reference/app-toolkit/hooks/components), and [utility](/v0-0-2/reference/app-toolkit/hooks/utilities) hooks

# Quickstart (/v0-0-2/ui/react/quickstart)

This page walks through the minimum integration of the MDK UI toolkit into a React application.

## Prerequisites

<include>../../../../_snippets/v0-0-2/ui-prerequisites.mdx</include>

## Install

<include>../../../../_snippets/v0-0-2/ui-installation-tabs.mdx</include>

## 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(
  <MdkProvider apiBaseUrl="https://app-node.example.com">
    <App />
  </MdkProvider>,
)
```

## 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](/v0-0-2/ui/react/core/theme) for design tokens and `@layer` override rules.

## Next steps

- [Tutorial](/v0-0-2/tutorials/ui/react/tutorial) — full integration walkthrough
- [Hooks](/v0-0-2/reference/app-toolkit/hooks) — [state hooks](/v0-0-2/reference/app-toolkit/hooks/state), [component hooks](/v0-0-2/reference/app-toolkit/hooks/components), and [utility hooks](/v0-0-2/reference/app-toolkit/hooks/utilities)
- [Explore the demo](/v0-0-2/ui/react/explore-the-demo) — run the demo browser without adding MDK to your own app yet
- [Core](/v0-0-2/ui/react/core) — primitives reference (`@tetherto/mdk-react-devkit/core`)
- [Foundation](/v0-0-2/ui/react/foundation) — mining-domain components (`@tetherto/mdk-react-devkit/foundation`)