@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

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

@@ -0,0 +1,71 @@
+# Dialog
+
+A modal dialog built on Radix UI `@radix-ui/react-dialog`. Provides composable primitives plus a high-level `DialogContent` that handles the overlay, portal, title, description, and optional close button in one component.
+
+<!-- BEGIN GENERATED: props — do not edit; npm run generate:usage-proptables (source: component JSDoc/types via registry.json) -->
+## Props
+
+### `DialogContent` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `bare` | Optional | `boolean` | `false` | Applies `mdk-dialog__header--bare` to the header |
+| `closable` | Optional | `boolean` | - | Shows an ✕ close button in the header |
+| `closeOnClickOutside` | Optional | `boolean` | `true` | Whether clicking the overlay closes the dialog |
+| `closeOnEscape` | Optional | `boolean` | `true` | Whether pressing Escape closes the dialog |
+| `description` | Optional | `string` | - | Renders `DialogDescription` below the title |
+| `onClose` | Optional | `VoidFunction` | - | Fired when the ✕ button is clicked |
+| `title` | Optional | `string` | - | Renders `DialogTitle` (and optional `DialogDescription`) inside the header |
+
+### `DialogHeader` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `bare` | Optional | `boolean` | `false` | Applies `mdk-dialog__header--bare` to the header |
+| `closable` | Optional | `boolean` | - | Shows an ✕ close button in the header |
+| `onClose` | Optional | `VoidFunction` | - | Fired when the ✕ button is clicked |
+<!-- END GENERATED: props -->
+
+## Exports
+
+| Name | Description |
+| ---- | ----------- |
+| `Dialog` | Root compound component (`Radix Root`) |
+| `DialogTrigger` | Element that opens the dialog |
+| `DialogPortal` | Renders dialog into a portal |
+| `DialogOverlay` | Dark backdrop |
+| `DialogContent` | Panel with built-in header, title, description, close button, and portal/overlay handling |
+| `DialogHeader` | Header container with optional close button |
+| `DialogTitle` | Accessible dialog title |
+| `DialogDescription` | Accessible description |
+| `DialogFooter` | Footer container |
+| `DialogClose` | Raw Radix close primitive |
+
+## Example
+
+```tsx
+import { Dialog, DialogContent, DialogFooter, Button } from "@tetherto/mdk-react-devkit"
+
+const [open, setOpen] = useState(false)
+
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogContent
+    title="Confirm Action"
+    description="This will apply the changes."
+    closable
+    onClose={() => setOpen(false)}
+    closeOnClickOutside={false}
+  >
+    <p>Are you sure you want to proceed?</p>
+    <DialogFooter>
+      <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+      <Button variant="primary" onClick={handleConfirm}>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Notes
+
+- `DialogContent` omits `aria-describedby` automatically when no `description` is provided
+- Use `DialogTrigger` for uncontrolled open state; use the `open` / `onOpenChange` props on `Dialog` for controlled usage

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

@@ -0,0 +1,55 @@
+/**
+ * Runnable example for Dialog.
+ */
+import { useState } from 'react'
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogTrigger,
+} from '@tetherto/mdk-react-devkit'
+
+export const DialogExample = () => {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <div className="mdk-example-row">
+      <Dialog>
+        <DialogTrigger asChild>
+          <Button variant="secondary">Open Dialog</Button>
+        </DialogTrigger>
+        <DialogContent
+          title="Device Settings"
+          description="Adjust configuration for this miner."
+          closable
+        >
+          <p>Dialog body content goes here. Add form fields, tables, or any content.</p>
+          <DialogFooter>
+            <Button variant="secondary">Cancel</Button>
+            <Button variant="primary">Save Changes</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogTrigger asChild>
+          <Button variant="primary">Controlled Dialog</Button>
+        </DialogTrigger>
+        <DialogContent
+          title="Confirm Action"
+          closable
+          onClose={() => setOpen(false)}
+          closeOnClickOutside={false}
+        >
+          <p>This dialog cannot be dismissed by clicking outside.</p>
+          <DialogFooter>
+            <Button variant="secondary" onClick={() => setOpen(false)}>
+              Close
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  )
+}

package/src/primitives/components/dialog/styles.scss

@@ -0,0 +1,176 @@
+@use '../../styles/mixins' as *;
+/**
+ * Dialog Component Styles
+ */
+
+:root {
+  --mdk-dialog-max-width: 32rem;
+}
+
+.mdk-dialog {
+  &__overlay {
+    position: fixed;
+    inset: 0;
+    /* Above side drawers; still below the floating-UI layer (dropdowns/tooltips
+       at 10000+) so those render on top of the dialog when opened from inside it. */
+    z-index: 300;
+    background: var(--mdk-overlay-bg);
+
+    &[data-state='open'] {
+      animation: fadeIn 200ms ease-out;
+    }
+
+    &[data-state='closed'] {
+      animation: fadeOut 200ms ease-in;
+    }
+  }
+
+  &__content {
+    position: fixed;
+    left: 50%;
+    top: 50%;
+    gap: 1rem;
+    z-index: 300;
+    width: 100%;
+    display: grid;
+    padding: 1.5rem;
+    box-sizing: border-box;
+    max-width: var(--mdk-dialog-max-width);
+    max-height: calc(100vh - 2rem);
+    overflow-y: auto;
+    translate: -50% -50%;
+    animation-duration: 200ms;
+    background: var(--mdk-color-surface);
+    border: 1px solid var(--mdk-dialog-border-color);
+    box-shadow: 0 10px 15px -3px var(--mdk-dialog-box-shadow-color);
+
+    &[data-state='open'] {
+      animation: dialogIn 200ms ease-out;
+    }
+
+    &[data-state='closed'] {
+      animation: dialogOut 200ms ease-in;
+    }
+  }
+
+  &__header {
+    @include flex_align_start_between;
+    position: relative;
+
+    padding-bottom: 28px;
+    border-bottom: 1px solid var(--mdk-dialog-border-color);
+
+    &--bare {
+      padding-bottom: 0;
+      border-bottom: none;
+    }
+
+    &__container {
+      @include flex_column;
+
+      gap: 0.75rem;
+    }
+
+    &__close {
+      position: relative;
+      right: -0.5rem;
+      top: 0;
+      border: 0;
+      width: 32px;
+      height: 32px;
+      min-width: unset;
+      min-height: unset;
+      background: transparent;
+      color: var(--mdk-color-white-60);
+      transition:
+        background 0.2s ease-in-out,
+        color 0.2s ease-in-out;
+
+      svg {
+        width: 16px;
+        height: 16px;
+      }
+
+      &:hover {
+        color: var(--mdk-color-white) !important;
+        background: var(--mdk-color-white-12) !important;
+      }
+    }
+
+    @media (min-width: 640px) {
+      text-align: left;
+    }
+  }
+
+  &__footer {
+    display: flex;
+    flex-direction: column-reverse;
+    padding-top: 24px;
+    border-top: 1px solid var(--mdk-dialog-border-color);
+
+    @media (min-width: 640px) {
+      flex-direction: row;
+      justify-content: flex-end;
+      gap: 0.5rem;
+    }
+  }
+
+  &__title {
+    font-family: var(--font-mono);
+    font-size: 1.125rem;
+    font-weight: 600;
+    line-height: 1.5;
+    letter-spacing: -0.025em;
+  }
+
+  &__description {
+    font-family: var(--font-mono);
+    font-size: 0.875rem;
+    line-height: 1.5;
+    color: hsl(var(--muted-foreground));
+  }
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes fadeOut {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes dialogIn {
+  from {
+    opacity: 0;
+    scale: 0.95;
+    translate: -50% -48%;
+  }
+  to {
+    opacity: 1;
+    scale: 1;
+    translate: -50% -50%;
+  }
+}
+
+@keyframes dialogOut {
+  from {
+    opacity: 1;
+    scale: 1;
+    translate: -50% -50%;
+  }
+  to {
+    opacity: 0;
+    scale: 0.95;
+    translate: -50% -48%;
+  }
+}

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

@@ -0,0 +1,40 @@
+# Divider
+
+A styled horizontal or vertical separator line, optionally containing a label. Wraps Radix UI `@radix-ui/react-separator`.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `align` | Optional | `"center" \| "left" \| "right"` | `"center"` | Horizontal alignment of the label |
+| `children` | Optional | `React.ReactNode` | - | Text or node rendered in the middle of the divider |
+| `className` | Optional | `string` | - | Custom className |
+| `dashed` | Optional | `boolean` | `false` | Line style |
+| `dotted` | Optional | `boolean` | `false` | Renders a dotted line (takes precedence over `dashed`) |
+| `orientation` | Optional | `"horizontal" \| "vertical"` | `"horizontal"` | Line orientation |
+| `plain` | Optional | `boolean` | `false` | Plain text style — no border around label |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { Divider } from "@tetherto/mdk-react-devkit"
+
+// Plain horizontal line
+<Divider />
+
+// With label
+<Divider align="left">Section title</Divider>
+
+// Dashed vertical
+<Divider orientation="vertical" dashed />
+
+// Dotted with centered label
+<Divider dotted>or</Divider>
+```
+
+## Notes
+
+- Labels are ignored on vertical dividers
+- `dotted` takes precedence over `dashed` when both are set

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

@@ -0,0 +1,26 @@
+/**
+ * Runnable example for Divider.
+ */
+import { Divider } from '@tetherto/mdk-react-devkit'
+
+export const DividerExample = () => (
+  <div className="mdk-example-col">
+    {/* Solid (default) */}
+    <Divider />
+
+    {/* Dashed */}
+    <Divider dashed />
+
+    {/* Dotted */}
+    <Divider dotted />
+
+    {/* With centered label */}
+    <Divider>Section</Divider>
+
+    {/* With left-aligned label */}
+    <Divider align="left">Pool Statistics</Divider>
+
+    {/* Plain (no border around label) */}
+    <Divider plain>or</Divider>
+  </div>
+)

package/src/primitives/components/divider/styles.scss

@@ -0,0 +1,106 @@
+@use '../../styles/mixins' as *;
+
+.mdk-divider {
+  &--horizontal {
+    @include flex_align;
+
+    width: 100%;
+    min-width: 100%;
+    border: none;
+    margin: 16px 0;
+
+    &::before,
+    &::after {
+      content: '';
+      flex: 1;
+      border: 1px solid var(--mdk-color-white-transparent);
+    }
+  }
+
+  &--vertical {
+    display: inline-block;
+    width: 1px;
+    height: 0.9em;
+    margin: 0 8px;
+    vertical-align: middle;
+    border: none;
+    border-left-width: 1px;
+    border-left-style: solid;
+    border-color: var(--mdk-color-white-transparent);
+  }
+
+  &--dashed {
+    &::before,
+    &::after {
+      border-top-style: dashed;
+    }
+
+    &.mdk-divider--vertical {
+      border-left-style: dashed;
+    }
+  }
+
+  &--dotted {
+    &::before,
+    &::after {
+      border-top-style: dotted;
+    }
+
+    &.mdk-divider--vertical {
+      border-left-style: dotted;
+    }
+  }
+
+  &--with-label {
+    &::before,
+    &::after {
+      content: '';
+    }
+  }
+
+  &--label-center {
+    &::before,
+    &::after {
+      flex: 1;
+    }
+  }
+
+  &--label-left {
+    &::before {
+      flex: 0 0 5%;
+      min-width: 24px;
+    }
+
+    &::after {
+      flex: 1;
+    }
+  }
+
+  &--label-right {
+    &::before {
+      flex: 1;
+    }
+
+    &::after {
+      flex: 0 0 5%;
+      min-width: 24px;
+    }
+  }
+
+  &__label {
+    padding: 0 12px;
+    font-size: 14px;
+    font-weight: 500;
+    color: var(--mdk-color-text-secondary);
+    white-space: nowrap;
+    flex-shrink: 0;
+  }
+
+  &--plain {
+    .mdk-divider__label {
+      font-size: 12px;
+      font-weight: 400;
+      color: var(--mdk-color-white-alpha-026);
+    }
+  }
+}

package/src/primitives/components/doughnut-chart/USAGE.md

@@ -0,0 +1,55 @@
+# `DoughnutChart`
+
+A Chart.js doughnut chart with a custom HTML legend, slice toggle, and percentage display.
+
+<!-- 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 | `DoughnutChartDataset[]` | - | Array of labelled slices |
+| `borderWidth` | Optional | `number` | `4` | Border width between segments (default: 4) |
+| `className` | Optional | `string` | - | Additional class for the root element |
+| `cutout` | Optional | `string` | `"75%"` | Doughnut cutout percentage (default: '75%') |
+| `formatValue` | Optional | `((value: number) => string)` | - | Formats slice values in the built-in legend and default tooltip (default: raw number) |
+| `height` | Optional | `number` | `260` | Chart height in pixels |
+| `legendPosition` | Optional | `"left" \| "right" \| "top" \| "bottom"` | `"top"` | Where to place the legend relative to the chart (default: 'top') |
+| `options` | Optional | `object` | - | Chart.js options – merged with defaults |
+| `tooltip` | Optional | `ChartTooltipConfig` | - | Custom HTML tooltip configuration. When provided, replaces the default doughnut tooltip (which shows label, value with unit, and percentage). Use `valueFormatter` to replicate the percentage display if needed |
+| `unit` | Optional | `string` | `""` | Unit suffix appended to values in tooltips and legends |
+
+### `DoughnutChartDataset`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `string` | - | Slice label |
+| `value` | Required | `number` | - | Numeric slice value |
+| `color` | Optional | `string` | - | Slice color (falls back to the built-in palette) |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { DoughnutChart } from "@tetherto/mdk-react-devkit"
+
+<DoughnutChart
+  data={[
+    { label: "Online", value: 120, color: "#34C759" },
+    { label: "Offline", value: 30, color: "#FF3B30" },
+    { label: "Sleeping", value: 15 },
+  ]}
+  unit="miners"
+/>
+
+// Legend on the right
+<DoughnutChart
+  data={data}
+  legendPosition="right"
+  cutout="60%"
+/>
+```
+
+## Notes
+
+- Clicking a legend item toggles the corresponding slice on the chart and dims the legend button
+- When the `data` reference changes (labels change), all hidden states reset automatically

package/src/primitives/components/doughnut-chart/doughnut-chart.example.tsx

@@ -0,0 +1,24 @@
+/**
+ * Runnable example for DoughnutChart.
+ */
+import { DoughnutChart } from '@tetherto/mdk-react-devkit'
+
+const deviceStatusData = [
+  { label: 'Online', value: 142, color: '#34C759' },
+  { label: 'Offline', value: 23, color: '#FF3B30' },
+  { label: 'Maintenance', value: 8, color: '#FF9500' },
+]
+
+const hashDistributionData = [
+  { label: 'Foundry EU', value: 450 },
+  { label: 'AntPool', value: 320 },
+  { label: 'F2Pool', value: 180 },
+  { label: 'Other', value: 50 },
+]
+
+export const DoughnutChartExample = () => (
+  <div className="mdk-example-row">
+    <DoughnutChart data={deviceStatusData} unit="devices" legendPosition="right" />
+    <DoughnutChart data={hashDistributionData} unit="TH/s" height={200} legendPosition="bottom" />
+  </div>
+)

package/src/primitives/components/doughnut-chart/styles.scss

@@ -0,0 +1,100 @@
+@use '../../styles/mixins' as *;
+.mdk-doughnut-chart {
+  @include flex_column;
+
+  gap: 24px;
+  width: 100%;
+
+  &--legend-left,
+  &--legend-right {
+    flex-direction: row;
+    align-items: center;
+  }
+
+  // ── Legend ─────────────────────────────────────────────────────────────────
+  &__legend {
+    @include flex_column;
+
+    gap: 8px;
+    width: 100%;
+    flex-shrink: 0;
+  }
+
+  &--legend-left &__legend,
+  &--legend-right &__legend {
+    width: auto;
+    min-width: 0;
+    flex: 1 1 0%;
+  }
+
+  &__legend-item {
+    @include flex_align;
+
+    gap: 12px;
+    width: 100%;
+    padding: 0;
+    background: none;
+    border: none;
+    cursor: pointer;
+
+    &--hidden {
+      opacity: 0.3;
+    }
+  }
+
+  &__legend-color {
+    width: 14px;
+    height: 14px;
+    flex-shrink: 0;
+    border: 1px solid;
+  }
+
+  &__legend-label {
+    @include text_ellipsis;
+    font-family: var(--font-mono);
+    flex: 1;
+    min-width: 0;
+    font-size: 12px;
+    font-weight: 500;
+    text-align: left;
+    color: hsl(210 40% 98% / 0.85);
+  }
+
+  &__legend-stats {
+    @include flex_align;
+
+    gap: 8px;
+    margin-left: auto;
+  }
+
+  &__legend-pct {
+    font-size: 12px;
+    font-weight: 600;
+    white-space: nowrap;
+    font-family: var(--font-mono);
+    color: hsl(210 40% 98% / 0.6);
+  }
+
+  &__legend-count {
+    font-size: 12px;
+    font-weight: 700;
+    white-space: nowrap;
+    font-family: var(--font-mono);
+    color: hsl(210 40% 98% / 0.9);
+  }
+
+  // ── Chart ─────────────────────────────────────────────────────────────────
+  &__chart {
+    @include flex_center;
+
+    width: 100%;
+    flex-shrink: 0;
+    position: relative;
+    align-self: center;
+    
+    canvas {
+      max-width: 100% !important;
+      height: auto !important;
+    }
+  }
+}