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

package/src/domain/components/dashboard/export-button/USAGE.md

@@ -0,0 +1,39 @@
+# `ExportButton`
+
+Split-button trigger for downloading dashboard data. Left half labels the
+action; right half opens a `DropdownMenu` with the available formats.
+The page decides what to serialize and handles the download.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `onExport` | Required | `(format: ExportFormat) => void \| Promise<void>` | - | Fires with the chosen format when the user picks an item. Return a promise to show a loading state until it settles; a rejection clears it and is not rethrown, so report failures inside the handler |
+| `className` | Optional | `string` | - | Optional class hook on the wrapper |
+| `disabled` | Optional | `boolean` | `false` | Disable the button |
+| `formats` | Optional | `readonly ExportFormat[]` | `['csv', 'json']` | Formats to offer in the dropdown — defaults to `['csv', 'json']` |
+| `label` | Optional | `string` | `"Export"` | Button label — defaults to `'Export'` |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { ExportButton } from "@tetherto/mdk-react-devkit"
+
+<ExportButton
+  onExport={(format) => (format === "csv" ? downloadCsv(rows) : downloadJson(rows))}
+/>
+```
+
+## Notes
+
+- The component is presentation-only. It does not decide *what* to
+  serialize — the page-level handler builds the file from the data it is
+  showing and triggers the download
+- Pass `formats={['csv']}` if you want a single-format button
+- Return a promise from `onExport` to show a spinner, with the button disabled, until
+  the export settles. A rejection clears the spinner and is not rethrown, so show
+  the failure (a toast, say) inside the handler
+- Replaces `StatsExport`: `onCsvExport` / `onJsonExport` become one
+  `onExport={(format) => (format === 'csv' ? exportCsv() : exportJson())}`

package/src/domain/components/dashboard/export-button/export-button.example.tsx

@@ -0,0 +1,15 @@
+/**
+ * Runnable example for ExportButton.
+ *
+ * The handler in this demo just logs the selected format. A real page
+ * would serialise the data it is showing in that format and download it.
+ */
+import { ExportButton } from '@tetherto/mdk-react-devkit'
+
+export const ExportButtonExample = () => (
+  <ExportButton
+    onExport={(format) => {
+      console.warn('Export requested:', format)
+    }}
+  />
+)

package/src/domain/components/dashboard/export-button/export-button.scss

@@ -0,0 +1,42 @@
+@use "@primitives/styles/mixins" as *;
+
+@layer mdk {
+  /* The compound selector outranks the bare `.mdk-button` so we override
+   * the default `width: 100%` / stretch behaviour without `!important`. */
+  .mdk-button.mdk-export-button {
+    display: inline-flex;
+    width: auto;
+    min-width: 0;
+    max-width: max-content;
+    gap: 0.5rem;
+  }
+
+  .mdk-export-button {
+    &__label {
+      flex: 0 0 auto;
+    }
+
+    &__chevron {
+      flex: 0 0 auto;
+      width: 0.875rem;
+      height: 0.875rem;
+      margin-left: 0.5rem;
+      padding-left: 0.625rem;
+      border-left: 1px solid color-mix(
+        in srgb,
+        var(--mdk-color-text-secondary, #b7b7af) 30%,
+        transparent
+      );
+      box-sizing: content-box;
+      opacity: 0.85;
+    }
+
+    /* Radix exposes the trigger width as `--radix-dropdown-menu-trigger-width`
+     * on the content element — wire it through so the menu matches the
+     * trigger width visually. */
+    &__menu {
+      width: var(--radix-dropdown-menu-trigger-width);
+      min-width: var(--radix-dropdown-menu-trigger-width);
+    }
+  }
+}

package/src/domain/components/dashboard/power-mode-timeline-chart/USAGE.md

@@ -0,0 +1,34 @@
+# `PowerModeTimelineChart`
+
+Timeline chart for power-mode state changes over time. Wraps `TimelineChart`
+with mining-specific data shaping.
+
+<!-- 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 | `PowerModeTimelineEntry[]` | `[]` | Initial power-mode entries (each with start/end ts + mode) |
+| `dataUpdates` | Optional | `PowerModeTimelineEntry[]` | `[]` | Streaming updates appended to the initial data |
+| `isLoading` | Optional | `boolean` | `false` | Show a loading skeleton instead of the chart |
+| `timezone` | Optional | `string` | `"UTC"` | IANA timezone string for x-axis tick formatting |
+| `title` | Optional | `string` | `CHART_TITLES.POWER_MODE_TIMELINE` | Chart title |
+
+### `PowerModeTimelineEntry`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `power_mode_group_aggr` | Optional | `Record<string, string>` | - | Power mode keyed by miner; takes precedence over the miner's status for the bar's mode |
+| `status_group_aggr` | Optional | `Record<string, string>` | - | Status keyed by miner; its keys decide which miners get a row, and an entry without it adds nothing |
+| `ts` | Optional | `number` | - | Sample time (epoch ms); consecutive samples with the same mode merge into one bar |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<PowerModeTimelineChart data={powerModeLog} timezone="UTC" />
+```
+
+## Data contracts
+
+`PowerModeTimelineEntry` lives in [`power-mode-timeline-chart.helper.ts`](./power-mode-timeline-chart.helper.ts).

package/src/domain/components/dashboard/power-mode-timeline-chart/power-mode-timeline-chart.example.tsx

@@ -0,0 +1,17 @@
+/**
+ * Runnable example for PowerModeTimelineChart.
+ */
+import { PowerModeTimelineChart } from '@tetherto/mdk-react-devkit'
+
+const NOW = Date.now() / 1000
+const HOUR = 60 * 60
+
+const mockEntries = [
+  { ts: NOW - 6 * HOUR, mode: 'normal', id: 'miner-01' },
+  { ts: NOW - 4 * HOUR, mode: 'boost', id: 'miner-01' },
+  { ts: NOW - 2 * HOUR, mode: 'normal', id: 'miner-01' },
+]
+
+export const PowerModeTimelineChartExample = () => {
+  return <PowerModeTimelineChart data={mockEntries as never} timezone="UTC" title="Power mode" />
+}

package/src/domain/components/dashboard/site-stats-bar/USAGE.md

@@ -0,0 +1,40 @@
+# `SiteStatsBar`
+
+Site-level summary strip sitting at the top of a dashboard page. Composes
+`WidgetTopRow` (title + current power) and `GenericDataBox` (hashrate, miner
+count, container count) into one horizontal card.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `title` | Required | `string` | - | Site label rendered in the header row |
+| `className` | Optional | `string` | - | Optional class hook |
+| `containerCount` | Optional | `number` | - | Total container count across the site |
+| `hashrateUnit` | Optional | `string` | `"TH/s"` | Hashrate display unit — defaults to `TH/s` |
+| `isLoading` | Optional | `boolean` | `false` | Render a skeleton bar while data is loading |
+| `minerCount` | Optional | `number` | - | Total miner count across the site |
+| `power` | Optional | `number` | - | Current site-level power consumption, in watts. It is displayed divided by 1000, so `powerUnit` names the kilo unit (`kW` by default) |
+| `powerUnit` | Optional | `string` | `"kW"` | Display unit for `power` — defaults to `kW` |
+| `totalHashrate` | Optional | `number` | - | Aggregate hashrate, in TH/s |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<SiteStatsBar
+  title='Site A'
+  power={1_320_000}
+  totalHashrate={92.3}
+  minerCount={1024}
+  containerCount={4}
+/>
+```
+
+## Notes
+
+- Renders `'—'` for any stat that's `undefined`. Pass `isLoading` for a
+  cleaner first-paint experience
+- `WidgetTopRow` reads timezone formatting via `useTimezoneFormatter`, so this
+  component must live inside an `<MdkProvider>` tree

package/src/domain/components/dashboard/site-stats-bar/site-stats-bar.example.tsx

@@ -0,0 +1,20 @@
+/**
+ * Runnable example for SiteStatsBar.
+ *
+ * Compose the four site-level stats (current power, hashrate, miner count,
+ * container count) into one summary strip. Drives off pre-computed numbers
+ * — a page derives them from its own site summary route.
+ */
+import { SiteStatsBar } from '@tetherto/mdk-react-devkit'
+
+export const SiteStatsBarExample = () => (
+  <SiteStatsBar
+    title="Site A"
+    power={1_320_000}
+    powerUnit="kW"
+    totalHashrate={92.3}
+    hashrateUnit="TH/s"
+    minerCount={1024}
+    containerCount={4}
+  />
+)

package/src/domain/components/dashboard/site-stats-bar/site-stats-bar.scss

@@ -0,0 +1,20 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-site-stats-bar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: stretch;
+  gap: var(--mdk-spacing-md, 12px);
+  padding: var(--mdk-spacing-md, 12px);
+  border-radius: var(--mdk-radius-md, 8px);
+  background: var(--mdk-color-surface, transparent);
+
+  &__header {
+    flex: 1 1 320px;
+    min-width: 0;
+  }
+
+  &--loading {
+    min-height: 88px;
+  }
+}

package/src/domain/components/dashboard/timeline-selector/USAGE.md

@@ -0,0 +1,25 @@
+# `TimelineSelector`
+
+Dropdown for picking the dashboard time range — wraps [`core/Select`](../../../../primitives/components/select/index.tsx) with the
+canonical option list from `getTimelineOptions`. Controlled: the page owns
+the selected timeline and passes it to its chart queries.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `onChange` | Required | `(next: string) => void` | - | Called whenever the user picks a new option |
+| `value` | Required | `string` | - | Currently selected timeline value (e.g. `'1m'`, `'5m'`) |
+| `className` | Optional | `string` | - | Tailwind/BEM class hook on the trigger |
+| `label` | Optional | `string` | `"Time range"` | ARIA label / placeholder for the trigger |
+| `options` | Optional | `TimelineOption[]` | `getTimelineOptions()` | Available options — defaults to {@link getTimelineOptions}. Pass a custom list to localise labels or restrict the range |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+const [timeline, setTimeline] = useState("5m")
+
+<TimelineSelector value={timeline} onChange={setTimeline} />
+```

package/src/domain/components/dashboard/timeline-selector/timeline-selector.example.tsx

@@ -0,0 +1,13 @@
+/**
+ * Runnable example for TimelineSelector.
+ *
+ * Controlled component — the caller owns its `value` and reacts to
+ * `onChange`.
+ */
+import { TimelineSelector } from '@tetherto/mdk-react-devkit'
+import { useState } from 'react'
+
+export const TimelineSelectorExample = () => {
+  const [value, setValue] = useState('5m')
+  return <TimelineSelector value={value} onChange={setValue} />
+}

package/src/domain/components/data-box/content-box/content-box.scss

@@ -0,0 +1,24 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-content-box {
+  background: var(--mdk-color-surface);
+  padding: 1rem;
+  flex-grow: 1;
+  flex-basis: 100%;
+  height: 100%;
+
+  @media (min-width: 768px) {
+    flex-basis: 50%;
+  }
+
+  &__title {
+    color: var(--mdk-color-white);
+    font-size: 18px;
+    font-weight: 600;
+    margin: 0 0 1rem 0;
+  }
+
+  &__content {
+    color: var(--mdk-color-white);
+  }
+}

package/src/domain/components/data-box/data-row/data-row.scss

@@ -0,0 +1,60 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-data-row {
+  display: table-row;
+  font-size: 0.8125rem; // 13px
+  font-weight: 400;
+  color: var(--mdk-color-text-secondary);
+
+  &__label {
+    display: table-cell;
+  }
+
+  &__value {
+    display: table-cell;
+    padding-left: 0.5rem; // 8px
+  }
+
+  &__units {
+    display: table-cell;
+    padding-left: 0.25rem; // 4px
+  }
+
+  // Highlighted state
+  &--highlighted {
+    font-size: 0.875rem; // 14px
+    font-weight: 600;
+  }
+
+  // Flash animation
+  &--flash {
+    animation: flashText 1s infinite;
+  }
+
+  // Flash animation with custom color
+  &--flash[style*='color'] {
+    animation: flashTextWithColor 1s infinite;
+  }
+}
+
+// Flash animation (default)
+@keyframes flashText {
+  0%,
+  100% {
+    color: var(--mdk-color-text-secondary);
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
+// Flash animation preserving custom color
+@keyframes flashTextWithColor {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}

package/src/domain/components/data-box/generic-data-box/USAGE.md

@@ -0,0 +1,25 @@
+# `GenericDataBox`
+
+Reusable labelled stat box for container summary panels. Renders a vertical list of label-value-unit rows with optional highlight and color/flash states driven by threshold rules.
+
+<!-- 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 | `DataItem[]` | `[]` | Array of data items to display |
+| `fallbackValue` | Optional | `unknown` | - | Fallback value when value is undefined |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { GenericDataBox } from "@tetherto/mdk-react-devkit";
+
+<GenericDataBox
+  data={[
+    { label: "Temperature", value: 45, units: "°C" },
+    { label: "Pressure", value: 2.5, units: "bar", isHighlighted: true },
+  ]}
+/>
+```

package/src/domain/components/data-box/generic-data-box/generic-data-box.example.tsx

@@ -0,0 +1,13 @@
+import { GenericDataBox } from '@tetherto/mdk-react-devkit'
+
+export const GenericDataBoxExample = () => (
+  <div className="mdk-example-row">
+    <GenericDataBox
+      data={[
+        { label: 'Temperature', value: 45, units: '°C' },
+        { label: 'Pressure', value: 2.5, units: 'bar', isHighlighted: true },
+        { label: 'Status', value: 'Running', color: 'green' },
+      ]}
+    />
+  </div>
+)

package/src/domain/components/data-box/generic-data-box/generic-data-box.scss

@@ -0,0 +1,4 @@
+.mdk-generic-data-box {
+  display: table;
+  width: 100%;
+}

package/src/domain/components/device-explorer/USAGE.md

@@ -0,0 +1,83 @@
+# DeviceExplorer
+
+Device explorer: filter + search toolbar over a sortable, selectable device
+table. Shows the miner columns by default; pass `columns` to change them.
+Designed to be controlled by URL state in the host app.
+
+<!-- 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` | Required | `Device[]` | - | Rows |
+| `filterOptions` | Required | `DeviceExplorerFilterOption[]` | - | Filter category definitions |
+| `getFormattedDate` | Required | `(date: Date) => string` | - | Date formatter from the host's timezone setup; used by the default miner columns |
+| `onFiltersChange` | Required | `(value: LocalFilters) => void` | - | Setter for filters |
+| `onSearchTagsChange` | Required | `(tags: string[]) => void` | - | Setter for search tags |
+| `searchOptions` | Required | `DeviceExplorerSearchOption[]` | - | Searchable column definitions |
+| `searchTags` | Required | `string[]` | - | Active search-tag chips |
+| `className` | Optional | `string` | - | Additional class names |
+| `columns` | Optional | `ColumnDef<Device>[]` | - | Table columns. Defaults to the miner columns ({@link getMinerColumns}) |
+| `filters` | Optional | `LocalFilters` | - | Controlled filter values |
+| `onRowClick` | Optional | `((device: Device) => void)` | - | Called when a row is clicked (e.g. to open the device's detail page) |
+| `onSelectedDevicesChange` | Optional | `((selections: RowSelectionState) => void)` | - | Setter for row selection |
+| `onSortingChange` | Optional | `((sorting: SortingState) => void)` | - | - |
+| `selectedDevices` | Optional | `RowSelectionState` | - | Controlled row-selection state |
+
+### `DeviceExplorerFilterOption`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `string` | - | Text shown in the filter cascader |
+| `value` | Required | `string` | - | Category key at the top level (e.g. `status`), or a selectable value under it; selections reach `onFiltersChange` as `[category, value]` paths |
+| `children` | Optional | `DeviceExplorerFilterOption[]` | - | Values selectable under this category; omit on leaf options |
+
+### `DeviceExplorerSearchOption`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `string` | - | Suggestion text, matched case-insensitively against the typed query and shown on the chip |
+| `value` | Required | `string` | - | Tag added to `searchTags` when this suggestion is picked (free-text tags are also allowed) |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+<DeviceExplorer
+  data={devices}
+  filterOptions={filterOptions}
+  searchOptions={searchOptions}
+  searchTags={searchTags}
+  onSearchTagsChange={setSearchTags}
+  onFiltersChange={setFilters}
+  getFormattedDate={(date) => formatInTimezone(date, tz)}
+/>
+```
+
+## Custom columns
+
+Spread the default miner columns and add your own, e.g. a per-row action:
+
+```tsx
+import { DeviceExplorer, getMinerColumns } from "@tetherto/mdk-react-devkit"
+
+const columns = [
+  ...getMinerColumns({ getFormattedDate }),
+  { id: "action", header: "Actions", cell: ({ row }) => <RowActionMenu device={row.original} /> },
+]
+
+<DeviceExplorer {...props} columns={columns} />
+```
+
+An app with several device kinds renders one explorer per kind (e.g. under the
+primitive `Tabs`), each with its own `columns` and `data`.
+
+## Data contracts
+
+- `Device` — [`foundation/types/device`](../../types/device.ts)
+- `LocalFilters`, `DataTableRowSelectionState` — re-exported from `core`.
+
+## Notes
+
+- Props only: no provider is required. `getFormattedDate` comes from the host,
+  e.g. `useTimezoneFormatter().getFormattedDate` from `@tetherto/mdk-react-adapter`

package/src/domain/components/device-explorer/components/device-card-col-text/styles.scss

@@ -0,0 +1,19 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-device-card-col-text {
+  @include text_ellipsis;
+  @include flex_column_center;
+
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 18px;
+  font-style: normal;
+  align-items: flex-start;
+  color: var(--mdk-color-white);
+
+  &:hover {
+    overflow: visible;
+    white-space: normal;
+    width: auto;
+  }
+}

package/src/domain/components/device-explorer/components/mining-status-indicator/styles.scss

@@ -0,0 +1,9 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-mining-status-indicator {
+  @include flex_center;
+
+  &--alert {
+    color: var(--mdk-color-severity-medium);
+  }
+}

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

@@ -0,0 +1,27 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-device-explorer__status-label {
+  @include flex-center;
+  color: var(--mdk-color-white);
+  font-size: 9px;
+  font-weight: 500;
+  text-transform: uppercase;
+  border-radius: 3px;
+  padding: 3px;
+  width: min-content;
+  height: min-content;
+
+  background-color: var(--mdk-color-brick-green);
+
+  &--error {
+    background-color: var(--mdk-color-brick-red);
+  }
+
+  &--sleep {
+    background-color: var(--mdk-color-medium-blue);
+  }
+
+  &--offline {
+    background-color: var(--mdk-color-dark-grey);
+  }
+}

package/src/domain/components/device-explorer/device-explorer.example.tsx

@@ -0,0 +1,60 @@
+/**
+ * Runnable example for DeviceExplorer, with the default miner columns. Pass
+ * `columns` (e.g. `[...getMinerColumns({ getFormattedDate }), myColumn]`) to
+ * change them.
+ */
+import { useState } from 'react'
+import { DeviceExplorer } from '@tetherto/mdk-react-devkit'
+
+const mockMiners = [
+  {
+    id: 'miner-01',
+    code: 1,
+    macAddress: 'AA:BB:CC:00:00:01',
+    status: 'online',
+    container: 'cont-A',
+    ip: '10.0.0.11',
+    hashrate: 102.4,
+    powerW: 3200,
+    lastActive: Date.now() - 60_000,
+  },
+  {
+    id: 'miner-02',
+    code: 2,
+    macAddress: 'AA:BB:CC:00:00:02',
+    status: 'warning',
+    container: 'cont-A',
+    ip: '10.0.0.12',
+    hashrate: 95.1,
+    powerW: 3450,
+    lastActive: Date.now() - 600_000,
+  },
+]
+
+const filterOptions = {
+  status: [
+    { label: 'Online', value: 'online' },
+    { label: 'Warning', value: 'warning' },
+    { label: 'Offline', value: 'offline' },
+  ],
+}
+
+const searchOptions = [{ label: 'Miner ID', value: 'id' }]
+
+export const DeviceExplorerExample = () => {
+  const [searchTags, setSearchTags] = useState<string[]>([])
+  const [filters, setFilters] = useState({})
+
+  return (
+    <DeviceExplorer
+      data={mockMiners as never}
+      filters={filters as never}
+      filterOptions={filterOptions as never}
+      onFiltersChange={setFilters as never}
+      searchOptions={searchOptions as never}
+      searchTags={searchTags}
+      onSearchTagsChange={setSearchTags}
+      getFormattedDate={(ts) => new Date(Number(ts)).toLocaleString()}
+    />
+  )
+}