@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

package/src/domain/components/device-explorer/styles.scss

@@ -0,0 +1,113 @@
+@use '@primitives/styles/mixins' as *;
+
+@forward './components/device-card-col-text/styles.scss';
+@forward './components/mining-status-indicator/styles.scss';
+@forward './components/status-label/styles.scss';
+
+.mdk-device-explorer {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+
+  &__toolbar {
+    @include flex_center;
+    align-items: stretch;
+    gap: 8px;
+    margin: 20px 0;
+    min-width: 0;
+
+    &__filter {
+      flex-shrink: 0;
+
+      .mdk-list-view-filter__trigger,
+      .mdk-badge-wrapper,
+      .mdk-button {
+        height: 100%;
+      }
+    }
+
+    &__search {
+      flex: 1;
+      min-width: 0;
+    }
+
+    @media screen and (max-width: 800px) {
+      @include flex_column;
+
+      &__filter {
+        flex-shrink: 0;
+
+        .mdk-list-view-filter__trigger,
+        .mdk-badge-wrapper,
+        .mdk-button {
+          width: 100%;
+        }
+      }
+    }
+  }
+
+  &__table {
+    width: 100%;
+
+    &__cell-wrapper {
+      @include flex_align;
+
+      gap: 6px;
+    }
+
+    &__cell {
+      &--type-temp,
+      &--type-hash-rate,
+      &--type-status,
+      &--type-power-mode {
+        @include flex_center;
+
+        gap: 6px;
+      }
+
+      &--type-efficiency {
+        width: 100px;
+      }
+
+      &--type-status {
+        &__value {
+          width: 65px;
+        }
+      }
+
+      &--type-power-mode {
+        &__value {
+          width: 80px;
+        }
+
+        &__icon {
+          @include flex_center;
+        }
+      }
+
+      &--type-led {
+        @include flex_column_center;
+
+        color: var(--mdk-color-white);
+        font-size: 9px;
+        font-weight: 500;
+        text-transform: uppercase;
+        border-radius: 3px;
+        background-color: var(--mdk-color-brick-red);
+        padding: 3px;
+        width: min-content;
+        height: min-content;
+
+        &--value-on {
+          background-color: var(--mdk-color-brick-green);
+        }
+      }
+    }
+
+    &__alarms {
+      &__status-container {
+        @include flex_center;
+      }
+    }
+  }
+}

package/src/domain/components/enabled-disable-toggle/USAGE.md

@@ -0,0 +1,29 @@
+# `EnabledDisableToggle`
+
+Switch with confirmation that enables or disables a container tank, miner, or feature flag. Renders a switch when the current state is known (boolean), or Enable/Disable buttons when state is unknown. Disables all controls when the container is offline.
+
+<!-- BEGIN GENERATED: props — do not edit; npm run generate:usage-proptables (source: component JSDoc/types via registry.json) -->
+## Props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `isButtonDisabled` | Required | `boolean` | - | Disables the Enable/Disable buttons when a command is in-flight |
+| `isOffline` | Required | `boolean` | - | Disables all controls and shows an offline tooltip |
+| `onToggle` | Required | `(params: EnabledDisableToggleCbParams) => void` | - | Callback fired when the user confirms a state change |
+| `tankNumber` | Required | `string \| number` | - | Tank identifier used in the label (`Tank {N} Circulation`). Pass an empty string for the air exhaust label |
+| `value` | Required | `unknown` | - | Current state. A boolean drives a switch display; non-boolean shows action buttons |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { EnabledDisableToggle } from "@tetherto/mdk-react-devkit";
+
+<EnabledDisableToggle
+  value={true}
+  tankNumber={1}
+  isButtonDisabled={false}
+  isOffline={false}
+  onToggle={({ tankNumber, isOn }) => console.log(tankNumber, isOn)}
+/>
+```

package/src/domain/components/enabled-disable-toggle/enabled-disable-toggle.example.tsx

@@ -0,0 +1,15 @@
+import { EnabledDisableToggle } from '@tetherto/mdk-react-devkit'
+
+export const EnabledDisableToggleExample = () => (
+  <div className="mdk-example-row">
+    <EnabledDisableToggle
+      value={true}
+      tankNumber={1}
+      isButtonDisabled={false}
+      isOffline={false}
+      onToggle={({ tankNumber, isOn }) => {
+        console.warn(`tank ${tankNumber} toggled to ${isOn}`)
+      }}
+    />
+  </div>
+)

package/src/domain/components/enabled-disable-toggle/enabled-disable-toggle.scss

@@ -0,0 +1,17 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-enabled-disable-toggle {
+  @include flex_column_center;
+
+  &__toggle {
+    @include flex_between;
+
+    flex-basis: 50%;
+    flex-grow: 0;
+    flex-shrink: 0;
+    gap: 12px;
+    padding: 0 5px;
+    box-sizing: border-box;
+    margin-block: 5px;
+  }
+}

package/src/domain/components/header-actions/USAGE.md

@@ -0,0 +1,99 @@
+# `HeaderActions`
+
+Top-bar buttons designed to live in the `actions` slot of `<AppHeader>`:
+`AlarmsBellButton` and `ProfileMenu`.
+
+<!-- BEGIN GENERATED: props — do not edit; npm run generate:usage-proptables (source: component JSDoc/types via registry.json) -->
+## Props
+
+### `AlarmsBellButton` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `className` | Optional | `string` | - | Additional class names |
+| `counts` | Optional | `AlarmsBellButtonCounts` | `{}` | Severity-bucketed alarm counts rendered in the stacked badge |
+| `label` | Optional | `string` | `"Active alarms"` | Accessible label. Defaults to "Active alarms" |
+| `onClick` | Optional | `((event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void)` | - | Click handler — typically opens an alerts panel or routes to /alerts |
+| `onSeverityClick` | Optional | `((severity: AlarmSeverity, event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void)` | - | Click handler for an individual severity count. When provided, each badge row becomes its own button so an operator can jump straight to the alerts page filtered by that severity (e.g. `/alerts?severity=critical`). When omitted, the counts render as plain (non-interactive) text |
+
+### `ProfileMenu` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `items` | Required | `ProfileMenuItem[]` | - | Items rendered in the dropdown, top-to-bottom |
+| `className` | Optional | `string` | - | Additional class names |
+| `icon` | Optional | `React.ReactNode` | `<UserAvatarIcon />` | Override the trigger icon — defaults to the user-avatar icon |
+| `label` | Optional | `string` | `"Profile menu"` | Accessible label for the trigger button |
+| `user` | Optional | `React.ReactNode` | - | Optional user label rendered at the top of the dropdown (e.g. an email) |
+
+### `AlarmsBellButtonCounts`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `critical` | Optional | `number` | - | Critical alarm count, shown as the top badge row; omit to hide the row |
+| `high` | Optional | `number` | - | High alarm count, shown as the middle badge row; omit to hide the row |
+| `medium` | Optional | `number` | - | Medium alarm count, shown as the bottom badge row; omit to hide the row |
+
+### `ProfileMenuItem`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `string` | - | Item text; also used as the React key, so keep it unique within `items` |
+| `onSelect` | Required | `() => void` | - | Called when the item is chosen by click or keyboard |
+| `danger` | Optional | `boolean` | - | Render as a destructive action (red) |
+| `description` | Optional | `React.ReactNode` | - | Optional secondary line under the label (e.g. "Current: Europe/Podgorica") |
+| `disabled` | Optional | `boolean` | - | Disable the menu item |
+| `icon` | Optional | `React.ReactNode` | - | Optional leading icon |
+<!-- END GENERATED: props -->
+
+## `AlarmsBellButton`
+
+Renders a bell icon with a three-line severity-stacked count badge
+(critical / high / medium). Counts are caller-provided — bucket the rows
+your alerts route returns.
+
+```tsx
+import { AlarmsBellButton } from '@tetherto/mdk-react-devkit'
+
+// `incidents` comes from your own alerts route.
+const counts = (incidents ?? []).reduce(
+  (acc, row) => ({
+    ...acc,
+    [row.severity]: (acc[row.severity] ?? 0) + 1,
+  }),
+  { critical: 0, high: 0, medium: 0 },
+)
+
+<AlarmsBellButton counts={counts} onClick={() => navigate('/alerts')} />
+```
+
+## `ProfileMenu`
+
+A dropdown wrapping the core `DropdownMenu`. The trigger renders the
+user-avatar icon (override via `icon`). The `items` array drives the menu
+surface — keep it short.
+
+```tsx
+import { ProfileMenu, authStore } from '@tetherto/mdk-react-devkit'
+
+<ProfileMenu
+  user={currentUserEmail}
+  items={[
+    {
+      label: 'Sign out',
+      onSelect: () => {
+        authStore.getState().reset()
+        navigate('/signin')
+      },
+      danger: true,
+    },
+  ]}
+/>
+```
+
+## Notes
+
+- Both buttons own their styles in cascade layer `mdk`; consumer overrides
+  in `app` win without specificity hacks
+- The bell badge hides itself entirely when all counts are undefined — the
+  empty state is the loading state too

package/src/domain/components/header-actions/header-actions.example.tsx

@@ -0,0 +1,22 @@
+import { AlarmsBellButton } from './alarms-bell-button'
+import { ProfileMenu } from './profile-menu'
+
+/**
+ * Top-bar action cluster — the alarms bell (with severity-stacked counts) and a
+ * profile menu (here with just a "Sign out" item).
+ */
+export const HeaderActionsExample = (): React.ReactNode => (
+  <>
+    <AlarmsBellButton counts={{ critical: 171, high: 72, medium: 322 }} />
+    <ProfileMenu
+      user="you@example.com"
+      items={[
+        {
+          label: 'Sign out',
+          onSelect: () => console.warn('sign out'),
+          danger: true,
+        },
+      ]}
+    />
+  </>
+)

package/src/domain/components/header-actions/header-actions.scss

@@ -0,0 +1,228 @@
+@use '@primitives/styles/mixins' as *;
+
+@keyframes warnBlink {
+  from { opacity: 1; }
+  to   { opacity: 0.25; }
+}
+
+@layer mdk {
+  /* Base tile shared by all header action buttons (profile, etc.). */
+  .mdk-header-action-button {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+    width: 2.8125rem; /* 45px */
+    height: 2.8125rem;
+    padding: 0.5rem;
+    background: color-mix(in srgb, var(--mdk-color-primary, #f7931a) 20%, transparent);
+    border: none;
+    color: var(--mdk-color-text-primary, #f5f5f0);
+    cursor: pointer;
+    clip-path: polygon(
+      11px 0,
+      100% 0,
+      100% calc(100% - 11px),
+      calc(100% - 11px) 100%,
+      0 100%,
+      0 11px
+    );
+    transition: color 120ms ease, background 120ms ease;
+
+    &:hover,
+    &:focus-visible {
+      color: var(--mdk-color-text-primary, #f5f5f0);
+      background: color-mix(in srgb, var(--mdk-color-primary, #f7931a) 32%, transparent);
+      outline: none;
+    }
+
+    &__icon {
+      display: inline-grid;
+      place-items: center;
+      font-size: 1.25rem;
+      color: currentColor;
+      &::after {
+        content: '';
+        position: absolute;
+        bottom: 0;
+        right: 0;
+        width: 0;
+        height: 0;
+        z-index: 1;
+        border-style: solid;
+        border-width: 0 0 8px 8px;
+        border-color: transparent transparent rgb(23, 19, 15) transparent;
+      }
+    }
+  }
+
+  /* Bell button */
+  .mdk-alarms-bell-button-group {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    background-color: color-mix(in srgb, var(--mdk-color-primary, #f7931a) 20%, transparent);
+    transition: background-color 120ms ease;
+
+    /* Top-left cut. */
+    &::before {
+      content: '';
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: 0;
+      height: 0;
+      z-index: 1;
+      border-style: solid;
+      border-width: 8px 8px 0 0;
+      border-color: rgb(23, 19, 15) transparent transparent transparent;
+    }
+
+    &:hover {
+      background-color: color-mix(in srgb, var(--mdk-color-primary, #f7931a) 32%, transparent);
+    }
+  }
+
+  .mdk-alarms-bell-button {
+    /* Transparent icon tile — background and cut live on the group.
+     * Extra left padding reserves space for the severity badge column. */
+    width: auto;
+    min-width: 2.8125rem;
+    max-width: max-content;
+    height: 2.8125rem;
+    padding: 0.5rem 0rem 0.5rem 1.75rem;
+    background: transparent;
+    clip-path: none;
+    color: var(--mdk-color-primary);
+
+    &:hover,
+    &:focus-visible {
+      background: transparent;
+      color: var(--mdk-color-primary);
+    }
+
+    .mdk-header-action-button__icon {
+      height: 45px;
+      width: 45px;
+    }
+
+    /* Severity numbers — absolutely positioned to the left of the icon tile. */
+    &__badge {
+      position: absolute;
+      left: 0.375rem;
+      top: 50%;
+      transform: translateY(-50%);
+      z-index: 1;
+      display: flex;
+      flex-direction: column;
+      align-items: flex-start;
+      gap: 0.05rem;
+      font-family: var(--mdk-font-mono, "JetBrains Mono", ui-monospace, monospace);
+      font-size: 0.5625rem;
+      font-weight: 800;
+      line-height: 1;
+      font-variant-numeric: tabular-nums;
+      letter-spacing: 0.025em;
+      pointer-events: none;
+      line-height: 14px;
+
+      &-row {
+        background: transparent;
+
+        /* Highest-severity row blinks to draw the operator's eye. */
+        &:first-child {
+          animation: warnBlink 0.25s cubic-bezier(0.7, 0, 1, 1) 0s infinite alternate none running;
+        }
+
+        &--critical { color: var(--mdk-color-severity-critical); }
+        &--high     { color: var(--mdk-color-severity-high); }
+        &--medium   { color: var(--mdk-color-severity-medium); }
+
+        &--interactive {
+          margin: 0;
+          padding: 0;
+          border: 0;
+          font: inherit;
+          background: none;
+          text-align: left;
+          cursor: pointer;
+          pointer-events: auto;
+
+          &:hover,
+          &:focus-visible {
+            text-decoration: underline;
+            outline: none;
+          }
+        }
+      }
+    }
+  }
+
+  /* ── Profile menu ───────────────────────────────────────────────────────*/
+  .mdk-profile-menu {
+    /* Full BTC orange fill — the "active" action tile. */
+    &__trigger {
+      width: 2.8125rem;
+      min-width: 0;
+      height: 2.8125rem;
+      background: var(--mdk-color-primary, #f7931a);
+      color: #11100f;
+
+      &:hover,
+      &:focus-visible {
+        background: var(--mdk-color-primary, #f7931a);
+        color: #11100f;
+      }
+    }
+
+    &__user {
+      display: flex;
+      flex-direction: column;
+      gap: 0.125rem;
+      padding: 0.5rem 0.625rem 0.625rem;
+      color: var(--mdk-color-text-primary, #f5f5f0);
+
+      &-email { font-weight: 700; }
+
+      &-role {
+        font-size: 0.8125rem;
+        color: rgba(255, 255, 255, 0.5);
+      }
+    }
+
+    &__item {
+      display: flex;
+      align-items: flex-start;
+      gap: 0.625rem;
+
+      &--two-line { align-items: flex-start; }
+      &--danger   { color: var(--mdk-color-danger, #ff5a5a); }
+    }
+
+    &__item-icon {
+      flex: 0 0 auto;
+      display: inline-grid;
+      place-items: center;
+      width: 1.25rem;
+      color: currentColor;
+    }
+
+    &__item-body {
+      display: flex;
+      flex-direction: column;
+      gap: 0.125rem;
+      min-width: 0;
+    }
+
+    &__item-label {
+      font-weight: 500;
+      color: currentColor;
+    }
+
+    &__item-description {
+      font-size: 0.8125rem;
+      color: rgba(255, 255, 255, 0.5);
+    }
+  }
+}

package/src/domain/components/header-stats/USAGE.md

@@ -0,0 +1,102 @@
+# `HeaderStats`
+
+Dashboard header stat boxes: `HeaderStatsBar` (container) plus four
+slot-fillers — `HeaderMinersBox`, `HeaderHashrateBox`,
+`HeaderConsumptionBox`, `HeaderEfficiencyBox`. Each box is a pure
+presentational component: pass numeric props, get the formatted display.
+No internal data fetching — the page reads its site summary route and
+passes the numbers in.
+
+<!-- BEGIN GENERATED: props — do not edit; npm run generate:usage-proptables (source: component JSDoc/types via registry.json) -->
+## Props
+
+### `HeaderConsumptionBox` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `className` | Optional | `string` | - | Additional class names |
+| `icon` | Optional | `React.ReactNode` | - | Icon shown next to the stat |
+| `unit` | Optional | `string` | `MW` | Unit label — defaults to `MW` |
+| `valueMw` | Optional | `number` | - | Current site-level power consumption, in megawatts |
+
+### `HeaderEfficiencyBox` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `className` | Optional | `string` | - | Additional class names |
+| `icon` | Optional | `React.ReactNode` | - | Icon shown next to the stat |
+| `unit` | Optional | `string` | `W/TH/S` | Unit label — defaults to `W/TH/S` |
+| `valueWthS` | Optional | `number` | - | Efficiency in watts per TH/s |
+
+### `HeaderHashrateBox` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `appLabel` | Optional | `string` | `WEBAPP_SHORT_NAME ("APP")` | Label for the app-side row |
+| `appPhs` | Optional | `number` | - | App-side aggregate hashrate in PH/s |
+| `className` | Optional | `string` | - | Additional class names |
+| `fractionDigits` | Optional | `number` | `3` | Decimal places shown for both values — defaults to `3` |
+| `icon` | Optional | `React.ReactNode` | - | Icon shown next to the stat |
+| `poolPhs` | Optional | `number` | - | Pool-side aggregate hashrate in PH/s |
+| `unit` | Optional | `string` | `PH/s` | Hashrate unit label — defaults to `PH/s` |
+
+### `HeaderMinersBox` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `appLabel` | Optional | `string` | `WEBAPP_SHORT_NAME ("APP")` | Label for the app-side row |
+| `appTotal` | Optional | `number` | - | Optional app-side meta line — total miners reporting to the app |
+| `className` | Optional | `string` | - | Additional class names |
+| `error` | Optional | `number` | - | Miners flagged in warning (the small amber count) |
+| `icon` | Optional | `React.ReactNode` | - | Icon shown next to the "Miners" label. Caller-provided so the package stays icon-agnostic |
+| `offline` | Optional | `number` | - | Miners offline (the small red count) |
+| `online` | Optional | `number` | - | Online miners (the `158` numerator) |
+| `poolMismatch` | Optional | `number` | - | Optional pool-side mismatch count (red) |
+| `poolOnline` | Optional | `number` | - | Optional pool-side online count (green) |
+| `poolTotal` | Optional | `number` | - | Optional pool-side meta — total miners as reported by upstream pools |
+| `total` | Optional | `number` | - | Total miners across the site (denominator of the `158 / 2,188` ratio) |
+
+### `HeaderStatsBar` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `children` | Required | `React.ReactNode` | - | Stat boxes to render in order, left-to-right |
+| `className` | Optional | `string` | - | Optional class hook |
+<!-- END GENERATED: props -->
+
+## Composition
+
+```tsx
+import {
+  AppHeader,
+  HeaderStatsBar,
+  HeaderMinersBox,
+  HeaderHashrateBox,
+  HeaderConsumptionBox,
+  HeaderEfficiencyBox,
+} from '@tetherto/mdk-react-devkit'
+
+// `summary` comes from your own site summary route (e.g. read with `useQuery`).
+const Header = ({ summary }: { summary?: SiteSummary }) => (
+  <AppHeader>
+    <HeaderStatsBar>
+      <HeaderMinersBox
+        total={summary?.miners.total}
+        online={summary?.miners.online}
+        error={summary?.miners.error}
+        offline={summary?.miners.offline}
+      />
+      <HeaderHashrateBox appPhs={summary?.hashratePhs} />
+      <HeaderConsumptionBox valueMw={summary?.powerMw} />
+      <HeaderEfficiencyBox valueWthS={summary?.efficiencyWthS} />
+    </HeaderStatsBar>
+  </AppHeader>
+)
+```
+
+## Notes
+
+- Undefined numbers render as `—`. Loading state is the empty state
+- The icon slot on each box is optional — pass a 16/20px SVG
+- Styles use cascade layer `mdk`; consumer styles in `app` win without
+  specificity tricks