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

package/src/primitives/components/multi-select/USAGE.md

@@ -0,0 +1,76 @@
+# `MultiSelect`
+
+Pick multiple values from a dropdown. Built on Radix Popover + the core
+Checkbox so it stays open on toggle - the canonical Radix pattern for
+multi-select (Radix Select itself is single-select by design).
+
+Use for filter rows (miner type, mining unit, status), multi-target
+actions, or any tag-style input. For a single-value picker use `<Select>`
+instead.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `options` | Required | `MultiSelectOption[]` | - | `{ value, label, disabled? }` entries to render as option rows |
+| `aria-label` | Optional | `string` | - | Accessible label - applied to the trigger button |
+| `className` | Optional | `string` | - | Extra class on the trigger button |
+| `contentClassName` | Optional | `string` | - | Extra class on the popover content |
+| `defaultValue` | Optional | `string[]` | `[]` | Initial values for uncontrolled mode. Ignored when `value` is provided |
+| `disabled` | Optional | `boolean` | `false` | Disables the trigger (popover does not open) |
+| `emptyMessage` | Optional | `React.ReactNode` | `"No options"` | Rendered inside the popover when `options` is empty |
+| `id` | Optional | `string` | - | - |
+| `maxSelectedDisplay` | Optional | `number` | - | Max number of selected chips rendered in the trigger before collapsing the rest into a "+N more" badge. `undefined` (default) renders every chip |
+| `name` | Optional | `string` | - | - |
+| `onValueChange` | Optional | `((next: string[]) => void)` | - | Fires with the next array on toggle / chip remove / clear-all |
+| `placeholder` | Optional | `React.ReactNode` | `"Select..."` | Rendered when nothing is selected |
+| `size` | Optional | `"sm" \| "md" \| "lg"` | `"lg"` | Trigger sizing tokens. Mirror the `<Select>` sizes |
+| `value` | Optional | `string[]` | - | Controlled selected values. Omit to use `defaultValue` for uncontrolled mode |
+| `variant` | Optional | `"default" \| "colored"` | `"default"` | `'colored'` paints the trigger in the primary tint (matches `<Select>`'s colored variant) |
+
+### `MultiSelectOption`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `React.ReactNode` | - | Shown in the option row and on the selected chip; a string label also names the chip's remove button |
+| `value` | Required | `string` | - | Value added to or removed from the selection; matched by strict equality, and also the React key |
+| `disabled` | Optional | `boolean` | - | Option is shown but cannot be toggled from the list; an already-selected one can still be removed via its chip |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { useState } from 'react'
+import { MultiSelect, type MultiSelectOption } from '@tetherto/mdk-react-devkit/primitives'
+
+const MINER_TYPES: MultiSelectOption[] = [
+  { value: 'miner-am-s19xp', label: 'Antminer S19XP' },
+  { value: 'miner-wm-m56s', label: 'WhatsMiner M56S' },
+  { value: 'miner-demo-m1', label: 'Demo M1' },
+]
+
+export const ExampleUsage = () => {
+  const [selected, setSelected] = useState<string[]>([])
+  return (
+    <MultiSelect
+      options={MINER_TYPES}
+      value={selected}
+      onValueChange={setSelected}
+      placeholder="Filter by miner type"
+      maxSelectedDisplay={2}
+    />
+  )
+}
+```
+
+## Behaviour notes
+
+- The popover **stays open** after toggling an option so multi-pick is
+  ergonomic without re-opening on every change
+- Clear-all surfaces in the trigger only when `>= 2` values are selected
+- Per-chip `x` buttons are not in the tab order (the parent trigger handles
+  focus); they remove only that value on click
+- Keyboard: Enter / Space on the trigger opens the popover, Arrow Down / Up
+  move focus through rows, Space toggles the focused row without closing,
+  Esc closes and returns focus to the trigger

package/src/primitives/components/multi-select/multi-select.example.tsx

@@ -0,0 +1,26 @@
+/**
+ * Runnable example for MultiSelect.
+ */
+import { MultiSelect, type MultiSelectOption } from '@tetherto/mdk-react-devkit/primitives'
+import { useState } from 'react'
+
+const MINER_TYPES: MultiSelectOption[] = [
+  { value: 'miner-am-s19xp', label: 'Antminer S19XP' },
+  { value: 'miner-wm-m56s', label: 'WhatsMiner M56S' },
+  { value: 'miner-av-a1346', label: 'Avalon A1346' },
+  { value: 'miner-demo-m1', label: 'Demo M1' },
+]
+
+export const MultiSelectExample = () => {
+  const [selected, setSelected] = useState<string[]>([])
+
+  return (
+    <MultiSelect
+      options={MINER_TYPES}
+      value={selected}
+      onValueChange={setSelected}
+      placeholder="Filter by miner type"
+      maxSelectedDisplay={2}
+    />
+  )
+}

package/src/primitives/components/multi-select/styles.scss

@@ -0,0 +1,245 @@
+@use '../../styles/mixins' as *;
+
+// Mirrors select sizing tokens so MultiSelect drops into the same rows as Select.
+$multi-select-lg-padding: 6px 8px 6px 12px;
+$multi-select-lg-font-size: 14px;
+$multi-select-lg-gap: 6px;
+$multi-select-lg-min-height: 40px;
+
+$multi-select-md-padding: 4px 6px 4px 10px;
+$multi-select-md-font-size: 12px;
+$multi-select-md-gap: 6px;
+$multi-select-md-min-height: 32px;
+
+$multi-select-sm-padding: 4px 6px 4px 8px;
+$multi-select-sm-font-size: 12px;
+$multi-select-sm-gap: 4px;
+$multi-select-sm-min-height: 24px;
+
+.mdk-multi-select__trigger {
+  @include inline_flex_align;
+
+  width: 100%;
+  cursor: pointer;
+  font-weight: 400;
+  border-radius: 0;
+  user-select: none;
+  line-height: normal;
+  font-family: var(--font-mono);
+  justify-content: space-between;
+  color: var(--mdk-color-white-7);
+  background: var(--mdk-color-background-dark);
+  border: 1px solid var(--mdk-color-white-2);
+  transition:
+    border-color 0.3s,
+    color 0.3s;
+
+  &:hover {
+    border-color: var(--mdk-color-primary);
+  }
+
+  &[data-state='open'] {
+    border-color: var(--mdk-color-primary);
+  }
+
+  &:focus {
+    outline: none;
+    box-shadow: none;
+  }
+
+  &[data-disabled] {
+    opacity: 0.5;
+    pointer-events: none;
+  }
+
+  &--lg {
+    gap: $multi-select-lg-gap;
+    min-height: $multi-select-lg-min-height;
+    padding: $multi-select-lg-padding;
+    font-size: $multi-select-lg-font-size;
+  }
+
+  &--md {
+    gap: $multi-select-md-gap;
+    min-height: $multi-select-md-min-height;
+    padding: $multi-select-md-padding;
+    font-size: $multi-select-md-font-size;
+  }
+
+  &--sm {
+    gap: $multi-select-sm-gap;
+    min-height: $multi-select-sm-min-height;
+    padding: $multi-select-sm-padding;
+    font-size: $multi-select-sm-font-size;
+  }
+
+  &--colored {
+    background: var(--multi-select-bg, var(--mdk-color-primary-10));
+    color: var(--multi-select-color, var(--mdk-color-primary));
+    border: 1px solid transparent;
+
+    &:hover,
+    &[data-state='open'] {
+      border-color: var(--multi-select-color, var(--mdk-color-primary));
+    }
+  }
+}
+
+.mdk-multi-select__chips {
+  @include flex_align;
+
+  flex: 1;
+  min-width: 0;
+  gap: 4px;
+  flex-wrap: wrap;
+}
+
+.mdk-multi-select__placeholder {
+  color: var(--mdk-color-white-7);
+  font-family: var(--font-mono);
+}
+
+.mdk-multi-select__token {
+  @include inline_flex_align;
+
+  gap: 4px;
+  padding: 2px 4px 2px 6px;
+  background: var(--mdk-color-white-2);
+  color: var(--mdk-color-white-7);
+  font-family: var(--font-mono);
+  font-size: 12px;
+  line-height: 1;
+  max-width: 100%;
+
+  &--overflow {
+    color: var(--mdk-color-text-secondary);
+    background: transparent;
+    padding: 2px 4px;
+  }
+}
+
+.mdk-multi-select__token-label {
+  @include text_ellipsis;
+
+  max-width: 200px;
+}
+
+.mdk-multi-select__token-clear,
+.mdk-multi-select__clear-all {
+  @include flex_center;
+
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  flex-shrink: 0;
+
+  &:hover {
+    color: var(--mdk-color-primary);
+  }
+
+  svg {
+    width: 12px;
+    height: 12px;
+  }
+}
+
+.mdk-multi-select__clear-all {
+  margin-left: 4px;
+  color: var(--mdk-color-white-7);
+}
+
+.mdk-multi-select__icon {
+  flex-shrink: 0;
+  width: 24px;
+  height: 24px;
+  color: var(--mdk-color-white-7);
+  transition: transform 0.3s ease;
+}
+
+.mdk-multi-select__trigger[data-state='open'] .mdk-multi-select__icon {
+  transform: rotate(180deg);
+}
+
+.mdk-multi-select__content {
+  z-index: 10000;
+  overflow: hidden;
+  border-radius: 0;
+  min-width: var(--radix-popover-trigger-width);
+  max-height: min(320px, var(--radix-popover-content-available-height));
+  background: var(--mdk-color-background-dark);
+  border: 1px solid var(--mdk-color-white-2);
+  box-shadow: var(--mdk-shadow-md);
+  padding: 0;
+}
+
+.mdk-multi-select__list {
+  @include flex_column;
+
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  max-height: min(320px, var(--radix-popover-content-available-height));
+}
+
+.mdk-multi-select__option {
+  @include flex_align;
+
+  gap: 10px;
+  padding: 8px 16px;
+  border: none;
+  background: transparent;
+  font-family: var(--font-mono);
+  font-size: 14px;
+  line-height: 20px;
+  color: var(--mdk-color-white-7);
+  text-align: left;
+  cursor: pointer;
+  transition:
+    background-color 0.2s,
+    color 0.2s;
+
+  &:not(:last-child) {
+    border-bottom: 1px solid var(--mdk-color-white-transparent);
+  }
+
+  &:hover:not([data-disabled]) {
+    color: var(--mdk-color-primary);
+    background-color: var(--mdk-color-primary-10);
+  }
+
+  &:focus-visible {
+    outline: 1px solid var(--mdk-color-primary);
+    outline-offset: -1px;
+  }
+
+  &[data-state='checked'] {
+    color: var(--mdk-color-primary);
+  }
+
+  &[data-disabled] {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.mdk-multi-select__option-label {
+  @include text_ellipsis;
+
+  flex: 1;
+}
+
+.mdk-multi-select__option-checkbox {
+  flex-shrink: 0;
+  pointer-events: none;
+}
+
+.mdk-multi-select__empty {
+  padding: 16px;
+  font-family: var(--font-mono);
+  font-size: 14px;
+  color: var(--mdk-color-text-secondary);
+  text-align: center;
+}

package/src/primitives/components/not-found-page/USAGE.md

@@ -0,0 +1,36 @@
+# `NotFoundPage`
+
+A full-page 404 "not found" screen with a customizable title, message, and optional "Go Home" button.
+
+<!-- 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 CSS class name |
+| `message` | Optional | `string` | `"The page you are looking for does not exist."` | Message displayed below the title |
+| `onGoHome` | Optional | `VoidFunction` | - | Callback fired when the "Go Home" button is clicked |
+| `title` | Optional | `string` | `"404"` | Page title |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { NotFoundPage } from "@tetherto/mdk-react-devkit"
+import { useNavigate } from "react-router"
+
+const navigate = useNavigate()
+
+<NotFoundPage onGoHome={() => navigate("/")} />
+
+// Custom message
+<NotFoundPage
+  title="Page Not Found"
+  message="Check the URL and try again."
+  onGoHome={() => navigate("/")}
+/>
+```
+
+## Notes
+
+- When `onGoHome` is omitted the button is not rendered, giving a read-only display

package/src/primitives/components/not-found-page/not-found-page.example.tsx

@@ -0,0 +1,27 @@
+/**
+ * Runnable example for NotFoundPage.
+ */
+import { NotFoundPage } from '@tetherto/mdk-react-devkit'
+
+export const NotFoundPageExample = () => (
+  <div className="mdk-example-row" style={{ display: 'flex', flexDirection: 'column', gap: 32 }}>
+    {/* Default 404 with Go Home button */}
+    <NotFoundPage
+      onGoHome={() => {
+        /* navigate home */
+      }}
+    />
+
+    {/* Custom title and message */}
+    <NotFoundPage
+      title="Page Not Found"
+      message="Check the URL and try again."
+      onGoHome={() => {
+        /* navigate home */
+      }}
+    />
+
+    {/* No button (read-only display) */}
+    <NotFoundPage title="403" message="You do not have permission to view this page." />
+  </div>
+)

package/src/primitives/components/not-found-page/styles.scss

@@ -0,0 +1,27 @@
+@use '../../styles/mixins' as *;
+.mdk-not-found-page {
+  @include flex_column_center;
+  
+  padding: 24px;
+  min-height: 100vh;
+
+  &__title {
+    font-family: var(--font-mono);
+    font-size: 48px;
+    font-weight: 700;
+    color: var(--mdk-color-white);
+    margin-bottom: 12px;
+  }
+
+  &__message {
+    font-family: var(--font-mono);
+    font-size: 18px;
+    color: var(--mdk-color-gray-400);
+    margin-bottom: 32px;
+    text-align: center;
+  }
+
+  &__button {
+    margin-top: 8px;
+  }
+}

package/src/primitives/components/operations-energy-cost-chart/USAGE.md

@@ -0,0 +1,29 @@
+# `OperationsEnergyCostChart`
+
+Doughnut chart comparing Operations and Energy cost ($/MWh). Includes
+`ChartContainer` chrome: title, unit subtitle, loading, and empty state.
+
+<!-- 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 class on the container |
+| `data` | Optional | `Partial<{ energyCostsUSD: number; operationalCostsUSD: number }>` | - | `operationalCostsUSD` and `energyCostsUSD` |
+| `emptyMessage` | Optional | `string` | - | Message when both costs are zero or missing |
+| `height` | Optional | `number` | `200` | Doughnut height in pixels |
+| `isLoading` | Optional | `boolean` | `false` | Shows loading overlay on the chart area |
+| `title` | Optional | `string` | `"Operations vs Energy Cost"` | Chart title |
+| `unit` | Optional | `string` | `$/MWh` | Subtitle and tooltip unit label |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<OperationsEnergyCostChart
+  data={{
+    operationalCostsUSD: 1000,
+    energyCostsUSD: 500,
+  }}
+/>
+```

package/src/primitives/components/operations-energy-cost-chart/operations-energy-cost-chart.example.tsx

@@ -0,0 +1,12 @@
+import { OperationsEnergyCostChart } from '@tetherto/mdk-react-devkit/primitives'
+
+export const OperationsEnergyCostChartExample = () => (
+  <div className="mdk-example-row">
+    <OperationsEnergyCostChart
+      data={{
+        energyCostsUSD: 500,
+        operationalCostsUSD: 1000,
+      }}
+    />
+  </div>
+)

package/src/primitives/components/operations-energy-cost-chart/styles.scss

@@ -0,0 +1,22 @@
+@use '../../styles/mixins' as *;
+
+.mdk-operations-energy-cost-chart {
+  &__header {
+    @include flex_column;
+
+    gap: 4px;
+  }
+
+  &__title {
+    margin: 0;
+    font-size: 14px;
+    font-weight: 500;
+    color: var(--mdk-chart-container-title);
+  }
+
+  &__unit {
+    font-size: 12px;
+    font-family: var(--font-mono);
+    color: rgb(var(--mdk-color-grey-idle));
+  }
+}

package/src/primitives/components/pagination/USAGE.md

@@ -0,0 +1,43 @@
+# Pagination
+
+Page navigation control with prev/next, page numbers, first/last jumps and an
+optional page-size selector.
+
+<!-- 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` | - | Custom className for the root element |
+| `current` | Optional | `number` | `1` | Current active page number |
+| `disabled` | Optional | `boolean` | `false` | Disable pagination |
+| `onChange` | Optional | `((page: number, pageSize: number) => void)` | - | Callback when page number or page size changes |
+| `onSizeChange` | Optional | `((current: number, size: number) => void)` | - | Callback when page size changes |
+| `pageSize` | Optional | `number` | `20` | Number of items per page |
+| `pageSizeOptions` | Optional | `number[]` | `[10, 20, 50, 100]` | Page size options for the select dropdown |
+| `showSizeChanger` | Optional | `boolean` | `true` | Show page size changer |
+| `showTotal` | Optional | `boolean` | `false` | Show total count text |
+| `size` | Optional | `"sm" \| "md" \| "lg"` | `"sm"` | Size variant |
+| `total` | Optional | `number` | `0` | Total number of items |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+const [page, setPage] = useState(1);
+const [pageSize, setPageSize] = useState(20);
+
+<Pagination
+  total={483}
+  current={page}
+  pageSize={pageSize}
+  showTotal
+  onChange={(p, ps) => { setPage(p); setPageSize(ps); }}
+/>;
+```
+
+## Notes
+
+- For server-side pagination, pass `current`/`total` from your fetch state and
+  refetch in `onChange`
+- Pair with `DataTable` by reading the table's `pagination` state

package/src/primitives/components/pagination/pagination.example.tsx

@@ -0,0 +1,23 @@
+/**
+ * Runnable example for Pagination.
+ */
+import { useState } from 'react'
+import { Pagination } from '@tetherto/mdk-react-devkit'
+
+export const PaginationExample = () => {
+  const [page, setPage] = useState(1)
+  const [pageSize, setPageSize] = useState(20)
+
+  return (
+    <Pagination
+      total={483}
+      current={page}
+      pageSize={pageSize}
+      showTotal
+      onChange={(p, ps) => {
+        setPage(p)
+        setPageSize(ps)
+      }}
+    />
+  )
+}