@tetherto/mdk-react-devkit 0.0.0-stage → 0.12.1

package/src/domain/components/header-stats/header-stats-bar.scss

@@ -0,0 +1,113 @@
+@use "@primitives/styles/mixins" as *;
+
+@layer mdk {
+  .mdk-header-stats-bar {
+    display: flex;
+    align-items: center;
+    min-width: 0;
+    max-width: 100%;
+    gap: 0;
+    /* Cells carry tabular data and don't truncate gracefully — when the
+     * viewport is narrower than the natural width of the strip, scroll
+     * horizontally instead of letting cells overlap their dividers.
+     * The scrollbar itself is hidden. */
+    overflow: auto hidden;
+    scrollbar-width: none;
+
+    &::-webkit-scrollbar {
+      display: none;
+    }
+
+    &__divider {
+      flex: 0 0 auto;
+      width: 1.5rem;
+      height: 4.375rem;
+      color: var(--mdk-color-primary);
+      pointer-events: none;
+    }
+  }
+
+  .mdk-header-stat-box {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.625rem 0.875rem;
+    flex: 0 0 auto;
+    border: 1.5px solid transparent;
+    border-radius: 10px;
+    font-family: var(--mdk-font-mono, "JetBrains Mono", ui-monospace, monospace);
+    line-height: 1.5;
+
+    &__icon {
+      flex: 0 0 auto;
+      display: inline-grid;
+      place-items: center;
+      color: var(--mdk-color-text-primary, #f5f5f0);
+      font-size: 1rem;
+    }
+
+    &__body {
+      display: flex;
+      flex-direction: column;
+      gap: 0;
+      min-width: 0;
+      font-size: 0.625rem;
+    }
+
+    &__row {
+      display: flex;
+      align-items: baseline;
+      gap: 0.5rem;
+      white-space: nowrap;
+      line-height: 1.5;
+    }
+
+    &__label {
+      font-weight: 500;
+      letter-spacing: 0.05em;
+      color: var(--mdk-color-text-primary, #f5f5f0);
+    }
+
+    &__muted {
+      color: rgba(255, 255, 255, 0.5);
+    }
+
+    &__value {
+      font-weight: 800;
+      font-size: 0.875rem;
+      color: var(--mdk-color-text-primary);
+      font-variant-numeric: tabular-nums;
+    }
+
+    &__accent {
+      font-weight: 800;
+      font-size: 0.875rem;
+      color: var(--mdk-color-primary);
+      font-variant-numeric: tabular-nums;
+    }
+
+    &__danger {
+      color: var(--mdk-color-danger);
+      font-variant-numeric: tabular-nums;
+    }
+
+    &__success {
+      color: rgb(var(--mdk-color-success, 114 245 158));
+      font-variant-numeric: tabular-nums;
+    }
+
+    &__warning {
+      color: var(--mdk-color-warning);
+      font-variant-numeric: tabular-nums;
+    }
+
+    &__unit {
+      color: rgba(255, 255, 255, 0.5);
+      font-size: 0.75rem;
+    }
+
+    &--accent &__value {
+      color: var(--mdk-color-primary);
+    }
+  }
+}

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

@@ -0,0 +1,27 @@
+import { HeaderConsumptionBox } from './header-consumption-box'
+import { HeaderEfficiencyBox } from './header-efficiency-box'
+import { HeaderHashrateBox } from './header-hashrate-box'
+import { HeaderMinersBox } from './header-miners-box'
+import { HeaderStatsBar } from './header-stats-bar'
+
+/**
+ * Four-box dashboard header strip — Miners / Hashrate / Consumption /
+ * Efficiency. Lives in the middle slot of `<AppHeader>`.
+ */
+export const HeaderStatsExample = (): React.ReactNode => (
+  <HeaderStatsBar>
+    <HeaderMinersBox
+      total={2188}
+      online={158}
+      error={1}
+      offline={57}
+      appTotal={216}
+      poolTotal={205}
+      poolOnline={201}
+      poolMismatch={4}
+    />
+    <HeaderHashrateBox appPhs={63.262} poolPhs={52.687} />
+    <HeaderConsumptionBox valueMw={1.663} />
+    <HeaderEfficiencyBox valueWthS={26.29} />
+  </HeaderStatsBar>
+)

package/src/domain/components/info-container/USAGE.md

@@ -0,0 +1,27 @@
+# InfoContainer / DeviceInfo
+
+Labeled key/value containers. `InfoContainer` renders a single labeled row;
+`DeviceInfo` renders a list of them from a single `data` array.
+
+## `InfoContainer` Props detail
+
+| Prop    | Status   | Type / Options | Default | Description |
+| ------- | -------- | -------- | ------- | ----------- |
+| `title` | Optional | `string` | —       | Row label   |
+| `value` | Optional | `string \| string[] \| number` | — | Row value (arrays render multi-line) |
+
+## `DeviceInfo` Props detail
+
+| Prop   | Status   | Type / Options | Default | Description    |
+| ------ | -------- | ------------ | ------- | -------------- |
+| `data` | Optional | `InfoItem[]` | —       | Rows to render |
+
+## Example
+
+```tsx
+<InfoContainer title="Worker" value="rig-01" />
+<DeviceInfo data={[
+  { title: "MAC", value: "AA:BB:CC:00:00:01" },
+  { title: "IP", value: "10.0.0.11" },
+]} />
+```

package/src/domain/components/info-container/info-container.example.tsx

@@ -0,0 +1,20 @@
+/**
+ * Runnable example for InfoContainer and DeviceInfo.
+ */
+import { DeviceInfo, InfoContainer } from './info-container'
+
+const mockDeviceData = [
+  { title: 'MAC Address', value: 'AA:BB:CC:00:00:01' },
+  { title: 'IP', value: '10.0.0.11' },
+  { title: 'Worker', value: 'rig-01' },
+  { title: 'Pool', value: 'pool.example.com:3333' },
+  { title: 'Status', value: 'online' },
+]
+
+export const InfoContainerExample = () => (
+  <div className="mdk-example-row">
+    <InfoContainer title="Worker" value="rig-01" />
+    <InfoContainer title="Tags" value={['bitcoin', 'sha256', 'liquid-cooled']} />
+    <DeviceInfo data={mockDeviceData} />
+  </div>
+)

package/src/domain/components/info-container/info-container.scss

@@ -0,0 +1,32 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-device-info {
+  @include flex_column;
+
+  box-sizing: border-box;
+  width: 100%;
+  gap: 5px;
+  padding: 10px;
+}
+
+.mdk-info-container {
+  @include flex_align_between;
+
+  font-size: 12px;
+
+  &__title {
+    @include text_ellipsis;
+
+    font-weight: 600;
+    margin-right: 5px;
+    color: rgb(var(--mdk-color-dark-grey));
+  }
+
+  &__value {
+    @include text_ellipsis;
+
+    color: var(--mdk-color-text-secondary);
+    max-width: 200px;
+    text-align: right;
+  }
+}

package/src/domain/components/line-chart-card/USAGE.md

@@ -0,0 +1,62 @@
+# `LineChartCard`
+
+Composable line-chart card with title, timeline range selector, legend
+(basic or detailed), error boundary, and an optional min/max/avg footer.
+
+Accepts either pre-shaped `data` or `rawData` + a `dataAdapter` callback so
+upstream domain components can keep their data wrangling local.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `chartProps` | Optional | `Partial<LightWeightLineChartProps>` | - | Pass-through props to the core LineChart |
+| `chartRef` | Optional | `React.MutableRefObject<IChartApi \| null>` | - | Ref to the lightweight-charts IChartApi |
+| `className` | Optional | `string` | - | Custom class name |
+| `data` | Optional | `LineChartCardData` | - | Pre-adapted chart data (use this OR rawData+dataAdapter) |
+| `dataAdapter` | Optional | `(data: unknown) => LineChartCardData` | - | Adapter to transform rawData into LineChartCardData |
+| `defaultTimeline` | Optional | `string` | `first option` | Default timeline when uncontrolled |
+| `detailLegends` | Optional | `boolean` | `false` | Show detail legends with current values |
+| `headerAction` | Optional | `React.ReactNode` | - | Optional action rendered on the right of the card header (e.g. an expand toggle). Passed straight through to `ChartContainer`. Additive - omit it and the card header is unchanged |
+| `isLoading` | Optional | `boolean` | `false` | Loading state |
+| `minHeight` | Optional | `string \| number` | `350` | Minimum chart height |
+| `onTimelineChange` | Optional | `(timeline: string) => void` | - | Callback when timeline changes |
+| `rawData` | Optional | `unknown` | - | Raw data to be transformed by dataAdapter |
+| `shouldResetZoom` | Optional | `boolean` | `true` | Whether to reset zoom on timeline change (default: true) |
+| `timeline` | Optional | `string` | - | Controlled timeline value |
+| `timelineOptions` | Optional | `TimelineOption[]` | - | Timeline range selector options |
+| `title` | Optional | `string` | - | Chart title |
+| `titleExtra` | Optional | `React.ReactNode` | - | Optional node rendered next to the title (e.g. an info tooltip). Passed straight through to `ChartContainer`. Additive |
+
+### `TimelineOption`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `string` | - | Range-selector button text |
+| `value` | Required | `string` | - | Timeline key (e.g. `5m`, `1h`) passed to `onTimelineChange` and matched against `timeline` |
+| `disabled` | Optional | `boolean` | - | Not forwarded to the range selector; currently has no effect |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+<LineChartCard
+  title="Hashrate"
+  data={chartData}
+  timelineOptions={[{ label: "5m", value: "5m" }, { label: "1h", value: "1h" }]}
+  defaultTimeline="5m"
+/>
+```
+
+## Data contracts
+
+`LineChartCardData` exposes `datasets`, `minMaxAvg`, `highlightedValue`,
+`footerStats`, `yTicksFormatter`, and `priceFormatter`. See [`types.ts`](./types.ts) in
+the same directory for the full shape.
+
+## Notes
+
+- Wrapped in `withErrorBoundary` — chart-level crashes won't blow up the page
+- For mining-domain charts, map your history route's response to the
+  `ChartCardData` payload in the query's `select` and pass it in

package/src/domain/components/line-chart-card/line-chart-card.example.tsx

@@ -0,0 +1,45 @@
+/**
+ * Runnable example for LineChartCard.
+ */
+import { LineChartCard, type LineChartCardData } from '@tetherto/mdk-react-devkit'
+
+const NOW = Date.now()
+const MS_PER_MIN = 60 * 1000
+
+/* `x` is a Unix timestamp in **milliseconds** — `LineChart` divides it by 1000
+ * itself to derive the lightweight-charts `UTCTimestamp`. Pass seconds here and
+ * every point lands in January 1970. */
+const points = Array.from({ length: 90 }, (_, i) => ({
+  x: NOW - (90 - i) * MS_PER_MIN,
+  y: 50 + Math.sin(i / 8) * 6 + Math.random() * 1.2,
+}))
+
+const chartData: LineChartCardData = {
+  datasets: [
+    {
+      label: 'Pool A',
+      borderColor: '#4f9ef5',
+      data: points,
+    },
+  ],
+  minMaxAvg: { min: '44', max: '58', avg: '51' },
+  highlightedValue: { value: 52.3, unit: 'TH/s' },
+}
+
+const timelineOptions = [
+  { label: '5m', value: '5m' },
+  { label: '1h', value: '1h' },
+  { label: '1d', value: '1D' },
+]
+
+export const LineChartCardExample = () => {
+  return (
+    <LineChartCard
+      title="Hashrate"
+      data={chartData}
+      timelineOptions={timelineOptions}
+      defaultTimeline="5m"
+      minHeight={320}
+    />
+  )
+}

package/src/domain/components/line-chart-card/styles.scss

@@ -0,0 +1,51 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-line-chart-card {
+  @include flex_column;
+
+  width: 100%;
+  box-sizing: border-box;
+  min-height: var(--mdk-line-chart-card-min-height, 350px);
+
+  @media (min-width: 769px) {
+    width: auto;
+    min-height: calc(var(--mdk-line-chart-card-min-height, 350px) + 50px);
+  }
+
+  &__header {
+    flex: 1;
+    padding-top: 20px;
+    border-top: 1px solid rgba(var(--mdk-color-white-rgb), 0.13);
+  }
+
+  &__legends {
+    @include flex_align;
+
+    flex: 1;
+    padding-bottom: 6px;
+  }
+
+  &__chart-area {
+    @include flex_column_center;
+
+    position: relative;
+    width: 100%;
+    min-width: 0;
+    height: 100%;
+    /* content-box so the 20px vertical padding adds to (not eats into) the
+     * canvas height — a global border-box reset would otherwise shrink the
+     * canvas and clip the top Y-axis label. */
+    box-sizing: content-box;
+    overflow: hidden;
+    padding: 20px 0;
+    min-height: 200px;
+  }
+
+  &__empty {
+    @include flex_column_center;
+
+    height: 100%;
+    min-height: 200px;
+    color: rgba(var(--mdk-color-white-rgb), 0.5);
+  }
+}

package/src/domain/components/miners-activity-chart/USAGE.md

@@ -0,0 +1,46 @@
+# `MinersActivityChart`
+
+Stacked-area chart of miner-state counts (online / offline / faulted) over the selected time window. Built on Chart.js via `react-chartjs-2`.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `data` | Optional | `MinersActivityData` | `{}` | Time-series data for online/offline/faulted counts |
+| `error` | Optional | `MinerActivityChartErrorProp \| null` | `null` | Error details to display |
+| `isDemoMode` | Optional | `boolean` | `false` | Use demo/mock data |
+| `isError` | Optional | `boolean` | `false` | Show error state |
+| `isLoading` | Optional | `boolean` | `false` | Show loading state |
+| `large` | Optional | `boolean` | `false` | Use tall variant |
+| `showLabel` | Optional | `boolean` | `true` | Show axis labels |
+| `variant` | Optional | `"indicators" \| "tiles"` | `"indicators"` | `indicators` (default) renders coloured dots; `tiles` renders tinted status tiles |
+
+### `MinersActivityData`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `total` | Optional | `number` | - | Total miner count; not rendered, since each tile reads its own status key (e.g. `offline`, `error`, `sleep`) and shows 0 when absent |
+
+### `MinerActivityChartErrorProp`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `data` | Optional | `{ message?: string }` | - | Error payload; `message` becomes the error alert description when `isError` is set, else a generic retry hint |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { MinersActivityChart } from "@tetherto/mdk-react-devkit";
+
+<MinersActivityChart
+  data={{ online: [], offline: [], faulted: [] }}
+  large={false}
+  isLoading={false}
+  isError={false}
+  error={null}
+  showLabel={true}
+  isDemoMode={true}
+/>
+```

package/src/domain/components/miners-activity-chart/miners-activity-chart.example.tsx

@@ -0,0 +1,15 @@
+import { MinersActivityChart } from '@tetherto/mdk-react-devkit'
+
+export const MinersActivityChartExample = () => (
+  <div className="mdk-example-row">
+    <MinersActivityChart
+      data={{ online: [], offline: [], faulted: [] } as never}
+      large={false}
+      isLoading={false}
+      isError={false}
+      error={null}
+      showLabel={true}
+      isDemoMode={true}
+    />
+  </div>
+)

package/src/domain/components/miners-activity-chart/miners-activity-chart.scss

@@ -0,0 +1,90 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-miners-activity-chart {
+  &__root {
+    @include flex_align;
+
+    gap: 8px;
+
+    &--tiles {
+      align-items: stretch;
+      gap: 6px;
+    }
+  }
+
+  &__tile {
+    display: flex;
+    flex: 1 1 0%;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 4px;
+    min-width: 0;
+    // Match the operator app: compact, square (no radius), 0 horizontal padding.
+    padding: 4px 0;
+    text-transform: capitalize;
+
+    &--large {
+      gap: 8px;
+      padding: 8px 0;
+    }
+  }
+
+  &__tile-label {
+    // 11px keeps the widest label ("Offline") inside its equal-share tile,
+    // which has zero horizontal padding.
+    font-size: 11px;
+    white-space: nowrap;
+
+    @media (max-width: 475px) {
+      font-size: 9px;
+    }
+  }
+
+  &__tile-value {
+    font-size: 14px;
+    font-weight: 600;
+  }
+
+  &__spinner {
+    @include flex_align;
+
+    min-height: 80px;
+
+    &--large {
+      min-height: 120px;
+    }
+  }
+
+  &__label {
+    white-space: nowrap;
+    text-align: center;
+    text-transform: capitalize;
+
+    @media (max-width: 475px) {
+      font-size: 9px;
+    }
+
+    &--large {
+      font-size: 14px;
+      white-space: nowrap;
+      text-align: center;
+      text-transform: capitalize;
+
+      @media (max-width: 475px) {
+        font-size: 9px;
+      }
+    }
+  }
+
+  &__item {
+    flex: 1 1 0%;
+    text-transform: capitalize;
+    padding: 4px 0;
+
+    &--large {
+      font-size: 16px;
+      gap: 8px;
+    }
+  }
+}

package/src/domain/components/mining-pools-panel/USAGE.md

@@ -0,0 +1,61 @@
+# `MiningPoolsPanel`
+
+Dashboard panel listing the site's mining pools — one row per
+`minerpool-<poolType>-shelf-<index>` — with 24h BTC revenue, hashrate,
+and an optional "Show details" popover.
+
+Map your pools route's response to `MiningPoolRow`s (see the data
+contract below) and pass them in.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `className` | Optional | `string` | - | Extra className for the root |
+| `emptyMessage` | Optional | `string` | `"No pools configured"` | Message shown when `rows` is empty |
+| `hideHeader` | Optional | `boolean` | `false` | Hide the title row entirely |
+| `isLoading` | Optional | `boolean` | `false` | Loading state — renders skeleton rows |
+| `label` | Optional | `string` | `"Mining Pools"` | Override the card title — defaults to `Mining Pools` |
+| `onShowDetails` | Optional | `(row: MiningPoolRow) => void` | - | Called when the user clicks the per-row "Show details" button |
+| `rows` | Optional | `MiningPoolRow[]` | `[]` | Pool rows, in display order |
+| `skeletonRows` | Optional | `number` | `3` | Number of skeleton rows to show while loading |
+
+### `MiningPoolRow`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `id` | Required | `string` | - | Stable React key |
+| `name` | Required | `string` | - | Display name (e.g. `minerpool-f2pool-shelf-0`) |
+| `details` | Optional | `PoolDetailItem[]` | - | Key/value details rendered inside the "Show details" popover |
+| `hashratePhs` | Optional | `number` | - | Hashrate in PH/s — used for display (TH/s shown automatically below 1 PH/s) |
+| `revenue24hBtc` | Optional | `number` | - | 24h revenue in BTC; rendered as `0.00 BTC` when undefined |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { MiningPoolsPanel, type MiningPoolRow } from "@tetherto/mdk-react-devkit";
+
+export const PoolsSection = ({ rows, isLoading }: { rows: MiningPoolRow[]; isLoading: boolean }) => (
+  <MiningPoolsPanel rows={rows} isLoading={isLoading} />
+);
+```
+
+## Data contract
+
+```ts
+type MiningPoolRow = {
+  id: string;             // stable react key
+  name: string;           // e.g. "minerpool-f2pool-shelf-0"
+  revenue24hBtc?: number; // formatted as "0.0231 BTC" / "0 BTC"
+  hashratePhs?: number;   // PH/s; rendered as TH/s when < 1 PH/s
+  details?: PoolDetailItem[]; // optional — drives the "Show details" popover
+};
+```
+
+## Notes
+
+- The "Show details" button is only rendered when `row.details` is non-empty
+- Default popover layout uses the shared `<PoolDetailsCard>` primitive — the
+  same one consumed by `<HeaderActions>`'s pool dropdown

package/src/domain/components/mining-pools-panel/mining-pools-panel.example.tsx

@@ -0,0 +1,42 @@
+/**
+ * Runnable example for MiningPoolsPanel.
+ *
+ * Uses static rows. In an app, map your pools route's response to
+ * `MiningPoolRow`s and pass them in.
+ */
+import { type MiningPoolRow, MiningPoolsPanel } from '@tetherto/mdk-react-devkit'
+
+const rows: MiningPoolRow[] = [
+  {
+    id: 'f2pool-shelf-0',
+    name: 'minerpool-f2pool-shelf-0',
+    revenue24hBtc: 0.0231,
+    hashratePhs: 0.901,
+    details: [
+      { title: 'Id', value: 'f2pool-shelf-0' },
+      { title: 'Rack', value: 'R-12' },
+      { title: 'User name', value: 'operator' },
+      { title: 'Balance', value: '0.0214 BTC' },
+      { title: 'Unsettled', value: '0.0017 BTC' },
+      { title: 'Revenue last 24hrs', value: '0.0231 BTC' },
+      { title: 'Active Worker Count', value: 24 },
+    ],
+  },
+  {
+    id: 'ocean-shelf-0',
+    name: 'minerpool-ocean-shelf-0',
+    revenue24hBtc: 0.0142,
+    hashratePhs: 1.21,
+    details: [
+      { title: 'Id', value: 'ocean-shelf-0' },
+      { title: 'Rack', value: 'R-04' },
+      { title: 'User name', value: 'operator' },
+      { title: 'Balance', value: '0.0136 BTC' },
+      { title: 'Unsettled', value: '0.0006 BTC' },
+      { title: 'Revenue last 24hrs', value: '0.0142 BTC' },
+      { title: 'Active Worker Count', value: 18 },
+    ],
+  },
+]
+
+export const MiningPoolsPanelExample = () => <MiningPoolsPanel rows={rows} />