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

package/src/domain/components/stat-cards/miner-metric-card/miner-metric-card.scss

@@ -0,0 +1,72 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-miner-metric-card {
+  padding: 10px;
+  position: relative;
+  border: 1px solid var(--mdk-border-default-color);
+
+  &__title {
+    padding: 5px 5px 5px 10px;
+    color: var(--mdk-color-white);
+  }
+
+  &__efficiency {
+    @include flex_row;
+
+    gap: 6px;
+    font-size: 14px;
+    font-weight: 400;
+    text-indent: 10px;
+
+    @media (min-width: 1240px) {
+      position: absolute;
+      top: 16px;
+      right: 15px;
+    }
+  }
+
+  &__content {
+    @include flex_column;
+
+    gap: 10px;
+    padding: 10px 10px 0 10px;
+
+    @media (min-width: 1024px) {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+    }
+  }
+
+  &__box {
+    @include flex_column;
+
+    gap: 8px;
+    background-color: rgba(var(--mdk-color-white-rgb), 0.1);
+    padding: 8px 10px;
+  }
+
+  &__grid-box {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 8px;
+    grid-column: span 2;
+    padding: 8px 10px;
+    background-color: rgba(var(--mdk-color-white-rgb), 0.1);
+
+    @media (min-width: 1024px) {
+      grid-template-columns: 1fr 1fr;
+    }
+  }
+
+  &__item {
+    @include flex_row;
+
+    gap: 6px;
+    font-size: 14px;
+    font-weight: 400;
+  }
+
+  &__label {
+    color: rgba(var(--mdk-color-white-rgb), 0.6);
+  }
+}

package/src/domain/components/stat-cards/single-stat-card/USAGE.md

@@ -0,0 +1,28 @@
+# `SingleStatCard`
+
+Prominent stat tile for displaying a single key metric. Supports flash animations and four visual variants.
+
+<!-- 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` | - | Additional class for the root element |
+| `color` | Optional | `string` | `"inherit"` | Color for flash/border |
+| `flash` | Optional | `boolean` | `false` | Enable flash animation |
+| `name` | Optional | `string` | - | Stat name/label |
+| `row` | Optional | `boolean` | `false` | Row layout |
+| `subtitle` | Optional | `string` | `""` | Subtitle text |
+| `superflash` | Optional | `boolean` | `false` | Enable superflash animation (faster) |
+| `unit` | Optional | `string` | `""` | Unit of measurement |
+| `value` | Optional | `string \| number \| null` | `null` | Stat value |
+| `variant` | Optional | `"primary" \| "secondary" \| "tertiary" \| "highlighted" \| "compact"` | `"primary"` | Card variant. `compact` is a centred name-over-value tile in muted text, for dense grids of secondary metrics |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { SingleStatCard } from "@tetherto/mdk-react-devkit";
+
+<SingleStatCard name="Hashrate" value={95.5} unit="TH/s" variant="primary" />
+```

package/src/domain/components/stat-cards/single-stat-card/single-stat-card.example.tsx

@@ -0,0 +1,10 @@
+import { SingleStatCard } from '@tetherto/mdk-react-devkit'
+
+export const SingleStatCardExample = () => (
+  <div className="mdk-example-row">
+    <SingleStatCard name="Hashrate" value={95.5} unit="TH/s" variant="primary" />
+    <SingleStatCard name="Efficiency" value={28.3} unit="J/TH" variant="secondary" />
+    <SingleStatCard name="Temperature" value={65} unit="°C" variant="highlighted" />
+    <SingleStatCard name="Consumption" value={3250} unit="W" variant="tertiary" />
+  </div>
+)

package/src/domain/components/stat-cards/single-stat-card/single-stat-card.scss

@@ -0,0 +1,179 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-single-stat-card {
+  @include flex_column;
+
+  gap: 3px;
+  width: 100%;
+  padding: 0.75rem;
+  font-size: 10px;
+  font-weight: 400;
+  line-height: normal;
+
+  @media (min-width: 768px) {
+    font-size: 12px;
+  }
+
+  &--row {
+    @include flex_row;
+  }
+
+  &--secondary,
+  &--tertiary {
+    @include flex_align_start_between;
+
+    flex-wrap: nowrap;
+    overflow: hidden;
+    padding: 12px;
+  }
+
+  &--tertiary {
+    border: 1px solid var(--stat-color);
+
+    .mdk-single-stat-card__text,
+    .mdk-single-stat-card__name,
+    .mdk-single-stat-card__subtitle,
+    .mdk-single-stat-card__value {
+      color: var(--stat-color, inherit);
+    }
+  }
+
+  // Centred name-over-value tile in muted text: dense grids of secondary
+  // metrics (replaces the former SecondaryStatCard)
+  &--compact {
+    @include flex_column_center;
+
+    gap: 0;
+    height: 70px;
+    padding: 0;
+
+    .mdk-single-stat-card__name,
+    .mdk-single-stat-card__value {
+      color: rgb(var(--mdk-color-soft-gray));
+      line-height: 22px;
+      text-align: center;
+    }
+
+    .mdk-single-stat-card__name {
+      font-size: 12px;
+      letter-spacing: -0.05px;
+    }
+
+    .mdk-single-stat-card__value {
+      font-size: 14px;
+      font-weight: 500;
+    }
+  }
+
+  &--highlighted {
+    .mdk-single-stat-card__name,
+    .mdk-single-stat-card__subtitle {
+      color: rgba(var(--mdk-color-white-rgb), 0.5);
+    }
+  }
+
+  &--flash {
+    animation: flash-border 1s infinite;
+
+    .mdk-single-stat-card__name,
+    .mdk-single-stat-card__subtitle,
+    .mdk-single-stat-card__value {
+      animation: flash-text 1s infinite;
+    }
+  }
+
+  &--superflash {
+    animation: flash-border 0.5s infinite;
+
+    .mdk-single-stat-card__name,
+    .mdk-single-stat-card__subtitle,
+    .mdk-single-stat-card__value {
+      animation: flash-text 0.5s infinite;
+      font-weight: 500;
+    }
+  }
+
+  &__text {
+    @include flex_column;
+
+    gap: 3px;
+  }
+
+  &__name {
+    white-space: nowrap;
+
+    .mdk-single-stat-card--primary & {
+      color: rgba(var(--mdk-color-white-rgb), 0.5);
+    }
+
+    @media (min-width: 768px) {
+      font-size: 12px;
+    }
+  }
+
+  &__subtitle {
+    .mdk-single-stat-card--primary & {
+      color: rgba(var(--mdk-color-white-rgb), 0.5);
+    }
+
+    @media (min-width: 768px) {
+      .mdk-single-stat-card--secondary &,
+      .mdk-single-stat-card--tertiary & {
+        font-size: 12px;
+      }
+    }
+  }
+
+  &__value {
+    font-size: 10px;
+    color: var(--mdk-color-white);
+
+    .mdk-single-stat-card--secondary &,
+    .mdk-single-stat-card--tertiary & {
+      text-align: end;
+    }
+
+    .mdk-single-stat-card--primary & {
+      font-size: 10px;
+      white-space: nowrap;
+    }
+
+    .mdk-single-stat-card--long-value & {
+      font-size: 14px;
+    }
+
+    .mdk-single-stat-card--highlighted & {
+      @include text_ellipsis;
+
+      font-size: 25px;
+      font-weight: 700;
+      color: var(--stat-color, inherit);
+    }
+
+    @media (min-width: 768px) {
+      .mdk-single-stat-card--primary & {
+        font-size: 12px;
+      }
+    }
+  }
+}
+
+@keyframes flash-border {
+  0%,
+  100% {
+    border-color: rgba(var(--mdk-color-black), 0.5);
+  }
+  50% {
+    border-color: var(--stat-color, inherit);
+  }
+}
+
+@keyframes flash-text {
+  0%,
+  100% {
+    color: var(--mdk-color-white);
+  }
+  50% {
+    color: var(--stat-color, inherit);
+  }
+}

package/src/domain/components/timeframe/USAGE.md

@@ -0,0 +1,15 @@
+# Timeframe
+
+Date-range helpers for reporting views. The timeframe pickers live alongside, in [`timeframe-controls`](./timeframe-controls/USAGE.md) and [`report-time-frame-selector`](./report-time-frame-selector/USAGE.md).
+
+| Export | Description |
+|---|---|
+| `useFinancialDateRange` | Hook for managing financial date-range state (period, year, month). |
+
+## `useFinancialDateRange`
+
+```tsx
+import { useFinancialDateRange } from "@tetherto/mdk-react-devkit";
+
+const { dateRange, period, setYear, setMonth } = useFinancialDateRange({ defaultPeriod: "monthly" });
+```

package/src/domain/components/timeframe/report-time-frame-selector/USAGE.md

@@ -0,0 +1,27 @@
+# ReportTimeFrameSelector
+
+Reporting-period picker with preset windows (1d / 7d / 30d / custom range). Used in financial reporting sections to control the visible date range.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `dateRange` | Required | `[Date, Date]` | - | Custom date range as a `[start, end]` tuple |
+| `presetTimeFrame` | Required | `number \| null` | - | Selected preset in days (`1`, `7`, `30`); `null` means the custom range is active |
+| `setDateRange` | Required | `(value: [Date, Date]) => void` | - | Update the custom date range |
+| `setPresetTimeFrame` | Required | `(value: number \| null) => void` | - | Update the preset selection |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { ReportTimeFrameSelector } from "@tetherto/mdk-react-devkit";
+
+<ReportTimeFrameSelector
+  presetTimeFrame={30}
+  dateRange={[new Date(), new Date()]}
+  setPresetTimeFrame={(value) => setState(value)}
+  setDateRange={(r) => setRange(r)}
+/>
+```

package/src/domain/components/timeframe/report-time-frame-selector/report-time-frame-selector.example.tsx

@@ -0,0 +1,18 @@
+import { useState } from 'react'
+import { ReportTimeFrameSelector } from '@tetherto/mdk-react-devkit'
+
+export const ReportTimeFrameSelectorExample = () => {
+  const [preset, setPreset] = useState<number | null>(30)
+  const now = new Date()
+  const [range, setRange] = useState<[Date, Date]>([now, now])
+  return (
+    <div className="mdk-example-row">
+      <ReportTimeFrameSelector
+        presetTimeFrame={preset}
+        dateRange={range}
+        setPresetTimeFrame={setPreset}
+        setDateRange={setRange}
+      />
+    </div>
+  )
+}

package/src/domain/components/timeframe/report-time-frame-selector/report-time-frame-selector.scss

@@ -0,0 +1,7 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-report-time-frame-selector {
+  @include flex_align;
+
+  gap: 8px;
+}

package/src/domain/components/timeframe/timeframe-controls/USAGE.md

@@ -0,0 +1,69 @@
+# `TimeframeControls` & `TimeframeWeekTreeContent`
+
+Controls for selecting a reporting time frame: year, month, and optional week picker.
+
+| Component                  | Description                                                                                        |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| `TimeframeControls`        | Full time-frame picker: year, month, and optional week selection in horizontal or stacked layout   |
+| `TimeframeWeekTreeContent` | Hierarchical year → month → week tree used inside `TimeframeControls`                              |
+
+<!-- BEGIN GENERATED: props — do not edit; npm run generate:usage-proptables (source: component JSDoc/types via registry.json) -->
+## Props
+
+### `TimeframeControls` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `dateRange` | Optional | `TimeframeControlsDateRange` | - | Current date range |
+| `hint` | Optional | `string` | - | Helper text below the controls |
+| `isMonthSelectVisible` | Optional | `boolean` | `true` | Show month selector |
+| `isWeekSelectVisible` | Optional | `boolean` | `true` | Show week selector |
+| `layout` | Optional | `"horizontal" \| "stacked"` | `"horizontal"` | Layout direction |
+| `onRangeChange` | Optional | `TimeframeControlsOnRangeChange` | - | Called when the range changes |
+| `onReset` | Optional | `VoidFunction` | - | Called when the Reset button is clicked |
+| `onTimeframeTypeChange` | Optional | `(type: TimeframeTypeValue) => void` | - | Called when timeframe type changes |
+| `showResetButton` | Optional | `boolean` | `false` | Shows the Reset button |
+| `timeframeType` | Optional | `null \| "month" \| "week" \| "year"` | - | Active timeframe type |
+
+### `TimeframeWeekFlatContent` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `visibleWeeks` | Required | `Week[]` | - | - |
+
+### `TimeframeWeekTreeContent` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `selectedMonth` | Required | `number` | - | - |
+| `selectedYear` | Required | `number` | - | - |
+| `timezone` | Required | `string` | - | - |
+
+### `TimeframeControlsDateRange`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `end` | Required | `number` | - | Range end (epoch ms); matched with `start` against calendar weeks to restore a week selection |
+| `start` | Required | `number` | - | Range start (epoch ms); the year/month/week pickers sync to this date |
+
+### `Week`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `bucketMonth` | Required | `number` | - | Month (0-11) of the week's end date in the selected timezone; sent as `month` to `onRangeChange` |
+| `bucketYear` | Required | `number` | - | Year of the week's end date in the selected timezone; sent as `year` to `onRangeChange` |
+| `end` | Required | `Date` | - | Sunday 23:59:59.999 (local time) that closes the week, capped to the end of yesterday |
+| `label` | Required | `string` | - | Option text, `DD/MM - DD/MM` in the selected timezone |
+| `start` | Required | `Date` | - | Monday 00:00:00.000 (local time) that opens the week |
+| `disabled` | Optional | `boolean` | - | True when the week starts after the end of yesterday; the option is shown but not selectable |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { TimeframeControls } from "@tetherto/mdk-react-devkit";
+
+<TimeframeControls
+  onRangeChange={(range) => console.log(range)}
+/>
+```

package/src/domain/components/timeframe/timeframe-controls/timeframe-controls-week-content.example.tsx

@@ -0,0 +1,7 @@
+import { TimeframeWeekTreeContent } from '@tetherto/mdk-react-devkit'
+
+export const TimeframeWeekTreeContentExample = () => (
+  <div className="mdk-example-row">
+    <TimeframeWeekTreeContent timezone="UTC" selectedYear={2026} selectedMonth={4} />
+  </div>
+)

package/src/domain/components/timeframe/timeframe-controls/timeframe-controls.example.tsx

@@ -0,0 +1,10 @@
+import { TimeframeControls } from '@tetherto/mdk-react-devkit'
+
+export const TimeframeControlsExample = () => (
+  <div className="mdk-example-row">
+    <TimeframeControls
+      onRangeChange={(range) => console.warn('range changed', range)}
+      layout="horizontal"
+    />
+  </div>
+)

package/src/domain/components/timeframe/timeframe-controls/timeframe-controls.scss

@@ -0,0 +1,121 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-timeframe-controls {
+  &--banded {
+    margin-block: 12px;
+    margin-bottom: 20px;
+  }
+
+  &--banded &__toolbar {
+    padding-block: 16px;
+    border-top: 1px solid var(--mdk-color-white-transparent);
+    border-bottom: 1px solid var(--mdk-color-white-transparent);
+    margin-bottom: 4px;
+  }
+
+  &--stacked &__toolbar {
+    flex-direction: column;
+    flex-wrap: nowrap;
+    align-items: stretch;
+  }
+
+  &--stacked &__control {
+    width: 100%;
+    min-width: 0;
+    max-width: 200px;
+  }
+
+  &--stacked &__control > .mdk-select__trigger {
+    width: 100%;
+  }
+
+  &__hint {
+    margin: 0 0 12px;
+    font-size: 11px;
+    font-weight: 500;
+    letter-spacing: 0.5px;
+    text-transform: uppercase;
+    color: var(--mdk-color-white-alpha-08c);
+  }
+
+  &__toolbar {
+    @include flex_wrap;
+    gap: 12px;
+    align-items: stretch;
+    width: 100%;
+    box-sizing: border-box;
+
+    &--with-reset {
+      @include flex_align_between;
+
+      flex-wrap: nowrap;
+    }
+  }
+
+  &__selects {
+    @include flex_wrap;
+
+    flex: 1;
+    gap: 12px;
+    min-width: 0;
+  }
+
+  &__reset {
+    flex-shrink: 0;
+    align-self: center;
+  }
+
+  &__control {
+    @include flex_column;
+    box-sizing: border-box;
+    align-items: stretch;
+    flex: 0 0 auto;
+    width: 200px;
+    min-width: 200px;
+    max-width: 200px;
+
+    /* Select.Root has no DOM; trigger is the direct flex child — inline-flex ignores parent width */
+    > .mdk-select__trigger {
+      display: flex;
+      width: 100%;
+      min-width: 0;
+      box-sizing: border-box;
+    }
+  }
+
+  &__multi-level-content {
+    min-width: var(--radix-select-trigger-width);
+    max-width: min(360px, 92vw);
+  }
+
+  &__control-target {
+    @include text_ellipsis;
+
+    width: 100%;
+    max-width: 100%;
+    box-sizing: border-box;
+
+    &:focus,
+    &:focus-visible {
+      outline: none;
+      box-shadow: none;
+    }
+
+    &.mdk-select__trigger {
+      justify-content: flex-start;
+
+      .mdk-select__icon {
+        flex-shrink: 0;
+        margin-left: auto;
+      }
+
+      > *:not(.mdk-select__icon):not(.mdk-select__clear) {
+        @include text_ellipsis;
+
+        flex: 1 1 auto;
+        min-width: 0;
+        text-align: left;
+      }
+    }
+  }
+}

package/src/domain/components/timeframe/use-financial-date-range.example.tsx

@@ -0,0 +1,12 @@
+import { useFinancialDateRange } from '@tetherto/mdk-react-devkit'
+
+const FinancialDateRangeDisplay = () => {
+  const { dateRange } = useFinancialDateRange({ defaultPeriod: 'monthly' as never })
+  return (
+    <div className="mdk-example-row">
+      <pre>{JSON.stringify(dateRange, null, 2)}</pre>
+    </div>
+  )
+}
+
+export const UseFinancialDateRangeExample = () => <FinancialDateRangeDisplay />

package/src/domain/components/timeline-chart/USAGE.md

@@ -0,0 +1,52 @@
+# `TimelineChart`
+
+Discrete-event timeline chart (e.g. miner state over time) with a category
+legend. Supports streaming updates via `newData`.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `initialData` | Required | `TimelineChartData` | - | Initial timeline data |
+| `axisTitleText` | Optional | `AxisTitleText` | `{ x: "Time", y: "" }` | Axis title strings |
+| `height` | Optional | `number` | - | Chart pixel height |
+| `isLoading` | Optional | `boolean` | `false` | Show loader |
+| `newData` | Optional | `TimelineChartData` | - | Streaming updates appended to the initial data |
+| `range` | Optional | `ChartRange` | - | Visible time window |
+| `skipUpdates` | Optional | `boolean` | `false` | Ignore `newData` |
+| `title` | Optional | `string` | - | Chart title |
+
+### `TimelineChartData`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `datasets` | Required | `TimelineChartDataset[]` | - | Bar series; each dataset's `label` is its tooltip title and legend entry |
+| `labels` | Required | `string[]` | - | Row labels, one row each; a data point lands in the row whose label equals its `y`. Nothing renders when empty |
+
+### `ChartRange`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `max` | Required | `number \| Date` | - | Right edge of the time axis (`Date` or epoch ms) |
+| `min` | Required | `number \| Date` | - | Left edge of the time axis (`Date` or epoch ms); without a range the axis spans the data |
+
+### `AxisTitleText`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `x` | Required | `string` | - | Title under the time axis; hidden when empty |
+| `y` | Required | `string` | - | Title beside the row labels; hidden when empty |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<TimelineChart initialData={data} range={{ min, max }} title="State" />
+```
+
+## Data contracts
+
+`TimelineChartData` lives in [`timeline-chart.types.ts`](./timeline-chart.types.ts). Each dataset has a
+`label` plus a list of `{ x: [startMs, endMs], y, mode }` items where `mode`
+maps to a category color in the legend.

package/src/domain/components/timeline-chart/timeline-chart.example.tsx

@@ -0,0 +1,35 @@
+/**
+ * Runnable example for TimelineChart.
+ */
+import { TimelineChart } from '@tetherto/mdk-react-devkit'
+
+const NOW = Date.now()
+const HOUR = 60 * 60 * 1000
+
+const mockTimelineData = {
+  labels: ['miner-01', 'miner-02', 'miner-03'],
+  datasets: [
+    {
+      label: 'miner-01',
+      data: [
+        { x: [NOW - 6 * HOUR, NOW - 4 * HOUR], y: 'miner-01', mode: 'normal' },
+        { x: [NOW - 4 * HOUR, NOW - HOUR], y: 'miner-01', mode: 'boost' },
+      ],
+    },
+    {
+      label: 'miner-02',
+      data: [{ x: [NOW - 6 * HOUR, NOW], y: 'miner-02', mode: 'normal' }],
+    },
+  ],
+}
+
+export const TimelineChartExample = () => {
+  return (
+    <TimelineChart
+      initialData={mockTimelineData as never}
+      range={{ min: NOW - 6 * HOUR, max: NOW }}
+      title="Miner activity"
+      height={240}
+    />
+  )
+}