@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

package/src/primitives/components/action-button/USAGE.md

@@ -0,0 +1,64 @@
+# `ActionButton`
+
+A button that requires confirmation before executing an action. The confirmation UI can be an inline popover or a modal dialog.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `confirmation` | Required | `ActionButtonConfirmation` | - | Configuration for the confirmation UI |
+| `className` | Optional | `string` | - | Additional class for the trigger button |
+| `disabled` | Optional | `boolean` | - | Disables the trigger button |
+| `label` | Optional | `string` | - | Button label text |
+| `loading` | Optional | `boolean` | - | Shows a spinner on the trigger button |
+| `mode` | Optional | `"dialog" \| "popover"` | `"popover"` | Confirmation mode: popover (inline) or dialog (modal) |
+| `variant` | Optional | `"primary" \| "danger" \| "secondary"` | `"secondary"` | Visual style of the trigger button |
+
+### `ActionButtonConfirmation`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `title` | Required | `string` | - | Heading shown in the confirmation UI |
+| `cancelLabel` | Optional | `string` | `"Cancel"` | Label for the cancel button |
+| `confirmLabel` | Optional | `string` | `'OK' (popover) / 'Confirm' (dialog)` | Label for the confirm button. Defaults to `'OK'` in popover mode and `'Confirm'` in dialog mode |
+| `description` | Optional | `React.ReactNode` | - | Body text or node shown below the title |
+| `icon` | Optional | `React.ReactNode` | `<QuestionMarkCircledIcon>` | Icon shown in the popover header (popover mode only) |
+| `onCancel` | Optional | `VoidFunction` | - | Fired when the user cancels |
+| `onConfirm` | Optional | `VoidFunction` | - | Fired when the user confirms |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { ActionButton } from "@tetherto/mdk-react-devkit"
+
+<ActionButton
+  label="Reboot Device"
+  variant="secondary"
+  confirmation={{
+    title: "Reboot Device",
+    description: "This will restart all communication workers.",
+    onConfirm: () => rebootDevice(),
+    onCancel: () => console.log("Cancelled"),
+  }}
+/>
+
+// Modal dialog variant with danger style
+<ActionButton
+  label="Factory Reset"
+  variant="danger"
+  mode="dialog"
+  confirmation={{
+    title: "Confirm Factory Reset",
+    description: "This action cannot be undone.",
+    confirmLabel: "Reset",
+    onConfirm: () => factoryReset(),
+  }}
+/>
+```
+
+## Notes
+
+- In `popover` mode the confirm button defaults to `variant="primary"`; in `dialog` mode it uses the same `variant` as the trigger
+- The component manages its own open/close state — no external state required

package/src/primitives/components/action-button/action-button.example.tsx

@@ -0,0 +1,40 @@
+/**
+ * Runnable example for ActionButton.
+ */
+import { ActionButton } from '@tetherto/mdk-react-devkit'
+
+export const ActionButtonExample = () => (
+  <div className="mdk-example-row">
+    <ActionButton
+      label="Reboot Device"
+      variant="secondary"
+      confirmation={{
+        title: 'Reboot Device',
+        description:
+          'This will restart all communication workers. The device will be temporarily unavailable.',
+        confirmLabel: 'Reboot',
+        cancelLabel: 'Cancel',
+      }}
+    />
+
+    <ActionButton
+      label="Factory Reset"
+      variant="danger"
+      mode="dialog"
+      confirmation={{
+        title: 'Confirm Factory Reset',
+        description: 'This action cannot be undone. All device settings will be erased.',
+        confirmLabel: 'Reset',
+      }}
+    />
+
+    <ActionButton
+      label="Disabled Action"
+      variant="secondary"
+      disabled
+      confirmation={{
+        title: 'Disabled',
+      }}
+    />
+  </div>
+)

package/src/primitives/components/action-button/styles.scss

@@ -0,0 +1,61 @@
+@use '../../styles/mixins' as *;
+
+.mdk_action_button {
+  &__trigger {
+    letter-spacing: 0.05em;
+  }
+
+  &__popover {
+    max-width: 400px;
+    border: none !important;
+    border-radius: 0 !important;
+    padding: 1rem 1.25rem !important;
+    background-color: var(--mdk-color-gray-900) !important;
+  }
+
+  &__header {
+    @include flex_align;
+
+    gap: 0.5rem;
+    margin-bottom: 0.75rem;
+  }
+
+  &__icon {
+    display: flex;
+    flex-shrink: 0;
+
+    svg {
+      width: 1.125rem;
+      height: 1.125rem;
+    }
+
+    &--danger {
+      color: var(--mdk-color-brick-red);
+    }
+
+    &--primary,
+    &--secondary {
+      color: var(--mdk-button-primary-bg);
+    }
+  }
+
+  &__title {
+    font-weight: 500;
+    font-size: 1rem;
+    font-family: var(--font-mono);
+    color: var(--mdk-color-white);
+  }
+
+  &__description {
+    line-height: 1.7;
+    font-size: 0.875rem;
+    margin-bottom: 1.25rem;
+    color: var(--mdk-color-text-secondary);
+  }
+
+  &__actions {
+    @include flex_justify_end;
+
+    gap: 0.5rem;
+  }
+}

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

@@ -0,0 +1,51 @@
+# Alert
+
+Contextual feedback banner for success, info, warning, and error messages. Supports icons, close button, an action slot, and an optional full-width banner mode.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `action` | Optional | `React.ReactNode` | - | Action element rendered to the right |
+| `banner` | Optional | `boolean` | `false` | Display as full-width banner (no border radius, no margin) |
+| `className` | Optional | `string` | - | Custom className |
+| `closable` | Optional | `boolean` | `false` | Shows an ✕ button; clicking it hides the alert |
+| `description` | Optional | `React.ReactNode` | - | Secondary/detail content shown below the title |
+| `icon` | Optional | `React.ReactNode` | - | Custom icon (used when showIcon is true) |
+| `onClose` | Optional | `React.MouseEventHandler<HTMLButtonElement>` | - | Called when close button is clicked |
+| `showIcon` | Optional | `boolean` | `false` | Renders the type icon (or the `icon` override) before the content |
+| `style` | Optional | `React.CSSProperties` | - | Custom styles |
+| `title` | Optional | `React.ReactNode` | - | Main message |
+| `type` | Optional | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Controls the color scheme and default icon |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { CoreAlert } from '@tetherto/mdk-react-devkit'
+
+<CoreAlert type="success" title="Saved successfully" showIcon />
+
+<CoreAlert
+  type="warning"
+  title="Low hashrate detected"
+  description="Average hashrate dropped below threshold."
+  showIcon
+  closable
+/>
+
+<CoreAlert
+  type="error"
+  title="Connection lost"
+  action={<Button onClick={retry}>Retry</Button>}
+/>
+
+{/* Full-width banner */}
+<CoreAlert type="info" title="Maintenance window tonight" banner />
+```
+
+## Notes
+
+- Once closed via the ✕ button, the component returns `null` and cannot be reopened without unmounting/remounting
+- Setting `description` automatically adds the `mdk-alert--with-description` modifier for extra spacing

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

@@ -0,0 +1,35 @@
+/**
+ * Runnable example for Alert.
+ */
+import { CoreAlert } from '@tetherto/mdk-react-devkit'
+
+export const AlertExample = () => (
+  <div className="mdk-example-col">
+    <CoreAlert
+      type="info"
+      title="Informational"
+      description="Your miner firmware update is ready to install."
+      showIcon
+    />
+    <CoreAlert
+      type="success"
+      title="Success"
+      description="Pool credentials updated successfully."
+      showIcon
+      closable
+    />
+    <CoreAlert
+      type="warning"
+      title="Warning"
+      description="Hash rate dropped below threshold — check your connections."
+      showIcon
+    />
+    <CoreAlert
+      type="error"
+      title="Error"
+      description="Failed to connect to the pool. Verify your credentials."
+      showIcon
+      closable
+    />
+  </div>
+)

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

@@ -0,0 +1,125 @@
+@use '../../styles/mixins' as *;
+
+.mdk-alert {
+  @include flex_align;
+
+  position: relative;
+  gap: 10px;
+  padding: 10px 14px;
+  border: 1px solid transparent;
+  font-size: 14px;
+  font-family: var(--font-mono);
+  font-weight: 500;
+  line-height: 1.5;
+  box-sizing: border-box;
+  width: 100%;
+
+  &--success {
+    background-color: rgba(var(--mdk-color-success), 0.1);
+    border-color: rgba(var(--mdk-color-success), 0.3);
+    color: rgb(var(--mdk-color-success));
+  }
+
+  &--info {
+    background-color: rgba(var(--mdk-color-sleep-blue), 0.1);
+    border-color: rgba(var(--mdk-color-sleep-blue), 0.3);
+    color: rgb(var(--mdk-color-sleep-blue));
+  }
+
+  &--warning {
+    background-color: rgba(var(--mdk-color-warning-rgb), 0.1);
+    border-color: rgba(var(--mdk-color-warning-rgb), 0.3);
+    color: rgb(var(--mdk-color-warning-rgb));
+  }
+
+  &--error {
+    background-color: rgba(var(--mdk-color-error), 0.1);
+    border-color: rgba(var(--mdk-color-error), 0.3);
+    color: rgb(var(--mdk-color-error));
+  }
+
+  &--banner {
+    border-radius: 0;
+    border-left: none;
+    border-right: none;
+    border-top: none;
+  }
+
+  &--with-description {
+    @include flex_align_start;
+
+    padding: 14px 16px;
+
+    .mdk-alert__icon {
+      margin-top: 2px;
+
+      svg {
+        width: 20px;
+        height: 20px;
+      }
+    }
+
+    .mdk-alert__title {
+      font-weight: 600;
+    }
+  }
+
+  &__icon {
+    flex-shrink: 0;
+
+    svg {
+      display: block;
+      width: 16px;
+      height: 16px;
+    }
+  }
+
+  &__content {
+    @include flex_column;
+
+    flex: 1;
+    min-width: 0;
+    gap: 4px;
+  }
+
+  &__title {
+    line-height: 1.4;
+  }
+
+  &__description {
+    font-size: 12px;
+    opacity: 0.85;
+    font-weight: 400;
+    line-height: 1.6;
+  }
+
+  &__action {
+    flex-shrink: 0;
+    margin-left: auto;
+  }
+
+  &__close {
+    @include inline_flex_align;
+
+    flex-shrink: 0;
+    margin-left: auto;
+    padding: 2px;
+    background: none;
+    border: none;
+    cursor: pointer;
+    color: inherit;
+    opacity: 0.6;
+    border-radius: 3px;
+    transition: opacity 0.2s;
+
+    svg {
+      display: block;
+      width: 14px;
+      height: 14px;
+    }
+
+    &:hover {
+      opacity: 1;
+    }
+  }
+}

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

@@ -0,0 +1,60 @@
+# `AlertDialog`
+
+A set of composable primitives wrapping Radix UI `@radix-ui/react-alert-dialog` with MDK class names. Use for destructive confirmations that should block interaction with the rest of the page.
+
+## Exports
+
+| Name | Description |
+| ---- | ----------- |
+| `AlertDialog` | Root compound component (Radix `Root`) |
+| `AlertDialogTrigger` | Button that opens the dialog (Radix `Trigger`) |
+| `AlertDialogPortal` | Renders the dialog into a portal |
+| `AlertDialogOverlay` | Dark backdrop |
+| `AlertDialogContent` | Dialog panel rendered inside the portal |
+| `AlertDialogHeader` | Header container (`div`) |
+| `AlertDialogFooter` | Footer container (`div`) |
+| `AlertDialogTitle` | Accessible dialog title |
+| `AlertDialogDescription` | Accessible description |
+| `AlertDialogAction` | Confirm button — styled with `mdk-button--variant-primary` |
+| `AlertDialogCancel` | Cancel button — styled with `mdk-button--variant-outline` |
+
+All components forward their `ref` and accept `className` for additional styling.
+
+## Example
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "@tetherto/mdk-react-devkit"
+
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="danger">Delete Account</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>
+        This action cannot be undone.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## Notes
+
+- `AlertDialogContent` automatically renders `AlertDialogPortal` and `AlertDialogOverlay` — you do not need to wrap them manually.
+- Unlike `Dialog`, `AlertDialog` does not close when clicking outside or pressing Escape by default (Radix behaviour for alert dialogs).

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

@@ -0,0 +1,37 @@
+/**
+ * Runnable example for AlertDialog.
+ */
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@tetherto/mdk-react-devkit'
+
+export const AlertDialogExample = () => (
+  <div className="mdk-example-row">
+    <AlertDialog>
+      <AlertDialogTrigger className="mdk-button mdk-button--variant-secondary mdk-button--size-md">
+        Delete Device
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Delete Device</AlertDialogTitle>
+          <AlertDialogDescription>
+            This action cannot be undone. The device and all associated data will be permanently
+            removed.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction>Delete</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  </div>
+)

package/src/primitives/components/app-header/USAGE.md

@@ -0,0 +1,47 @@
+# `AppHeader`
+
+A generic three-slot top-bar. The `start`, `children` (middle), and
+`actions` slots accept any ReactNode — the component owns no domain.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `actions` | Optional | `React.ReactNode` | - | Right-edge action cluster — e.g. alarms bell, profile menu, or sign-out |
+| `children` | Optional | `React.ReactNode` | - | Middle slot — e.g. the dashboard stats strip or page title |
+| `className` | Optional | `string` | - | Optional class hook for the outer `<header>` element |
+| `logo` | Optional | `React.ReactNode` | - | Left-most slot — typically the app's brand lockup / logo |
+| `start` | Optional | `React.ReactNode` | - | Left-edge content — e.g. a sidebar collapse toggle or brand wordmark |
+| `sticky` | Optional | `boolean` | `true` | Render the header sticky to the top of its scroll container |
+<!-- END GENERATED: props -->
+
+## When to use
+
+- You're building an app shell with a persistent header.
+- You want sticky-to-top behavior without writing layout CSS.
+- You'd otherwise hand-roll a `<header>` with flex columns.
+
+## Example
+
+```tsx
+import { AppHeader, AlarmsBellButton, ProfileMenu } from '@tetherto/mdk-react-devkit'
+
+<AppHeader
+  start={<button onClick={toggleSidebar}>≡</button>}
+  actions={
+    <>
+      <AlarmsBellButton counts={{ critical: 2 }} />
+      <ProfileMenu items={[{ label: 'Sign out', onSelect: signOut, danger: true }]} />
+    </>
+  }
+>
+  <HeaderStatsBar>…</HeaderStatsBar>
+</AppHeader>
+```
+
+## Notes
+
+- Sticky positioning is on by default. Pass `sticky={false}` to disable.
+- The component sets `position: sticky; top: 0`; the outer scroll container
+  must be a scrollable ancestor for the sticky behavior to engage.

package/src/primitives/components/app-header/app-header.example.tsx

@@ -0,0 +1,11 @@
+import { AppHeader } from './app-header'
+
+/**
+ * Three-slot top-bar shell. `start` for a brand/toggle, `children` for the
+ * main strip, `actions` for the right-edge cluster.
+ */
+export const AppHeaderExample = (): React.ReactNode => (
+  <AppHeader start={<strong>MDK</strong>} actions={<button type="button">Sign out</button>}>
+    <div style={{ padding: '0 1rem', alignSelf: 'center' }}>Header content</div>
+  </AppHeader>
+)

package/src/primitives/components/app-header/app-header.scss

@@ -0,0 +1,94 @@
+@use '../../styles/mixins' as *;
+
+@layer mdk {
+  .mdk-app-header {
+    display: flex;
+    align-items: center;
+    gap: 0;
+    width: 100%;
+    /* Include border + padding in the width: 100% calculation so the
+     * header never exceeds its grid cell (which is what was creating
+     * the "page wider than viewport" effect — without border-box the
+     * 0.5px bottom border plus 1rem horizontal padding added on top
+     * of the 100% width). */
+    box-sizing: border-box;
+    /* As a grid/flex item (the shell places the header in a grid row),
+     * the default min-width: auto floors the track at the header's
+     * min-content width — logo + full stats strip + actions. On narrow
+     * windows that pushes the track past the viewport and clips the
+     * actions cluster with no way to scroll to it. min-width: 0 lets
+     * the header shrink so the __main slot absorbs the squeeze. */
+    min-width: 0;
+    min-height: 4.6875rem; /* 75px */
+    padding: 0 1rem;
+    background: var(--mdk-color-surface, #0a0a09);
+    color: var(--mdk-color-text-primary, #f5f5f0);
+    /* Sits above the sidebar (z-index 10) so the sidebar's top-right
+     * notch ::after tucks under the header's bottom border, forming
+     * the continuous reference-app-style L-shape. */
+    position: relative;
+    z-index: 11;
+    border-bottom: 0.5px solid var(--mdk-color-primary, #f7931a);
+
+    &--sticky {
+      position: sticky;
+      top: 0;
+      z-index: 20;
+    }
+
+    &__logo {
+      display: flex;
+      align-items: center;
+      /* Pin to the sidebar's expanded width so the leading
+       * HeaderStatDividerIcon in the stats bar starts at exactly
+       * the sidebar's right edge, forming the continuous orange
+       * stroke from sidebar to header chevron (an L-shape). */
+      width: var(--mdk-shell-sidebar-width, 220px);
+      box-sizing: border-box;
+      padding: 0 0.75rem 0 0.25rem;
+      color: var(--mdk-color-primary);
+      flex: 0 0 auto;
+    }
+
+    &__start {
+      display: flex;
+      align-items: center;
+      padding: 0 0.75rem;
+      flex: 0 0 auto;
+    }
+
+    &__main {
+      display: flex;
+      align-items: center;
+      /* flex-basis 0 + min-width 0 + overflow hidden together force
+       * the middle slot to shrink to its share of the row instead of
+       * its content's intrinsic width. HeaderStatsBar handles the
+       * overflow with its own overflow-x: auto inside this slot. */
+      flex: 1 1 0;
+      min-width: 0;
+      overflow: hidden;
+      padding: 0 0.5rem 0 0;
+    }
+
+    &__actions {
+      display: flex;
+      align-items: center;
+      flex: 0 0 auto;
+      gap: 1rem;
+      padding-left: 1rem;
+    }
+
+    @media (max-width: 768px) {
+      padding-inline: 0.5rem;
+
+      &__logo {
+        display: none;
+      }
+
+      &__actions {
+        gap: 0.5rem;
+        padding-left: 0.5rem;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+# `AreaChart`
+
+Presentational Chart.js area chart (`Line` with fill). Data must be provided
+via props — no data fetching.
+
+<!-- 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 | `ChartData<"line", (number \| Point \| null)[], unknown>` | - | Chart data - required, provided by parent |
+| `className` | Optional | `string` | - | Additional class names |
+| `height` | Optional | `number` | `300` | Chart height in pixels |
+| `options` | Optional | `object` | - | Chart.js options - merged with defaults |
+| `tooltip` | Optional | `ChartTooltipConfig` | - | Custom HTML tooltip configuration. When provided, replaces the default Chart.js tooltip |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<AreaChart data={areaData} options={options} height={300} />
+```

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

@@ -0,0 +1,21 @@
+/**
+ * Runnable example for AreaChart.
+ */
+import { AreaChart } from '@tetherto/mdk-react-devkit'
+
+const labels = Array.from({ length: 12 }, (_, i) => `m${i + 1}`)
+
+const data = {
+  labels,
+  datasets: [
+    {
+      label: 'Pool A',
+      borderColor: '#4f9ef5',
+      data: labels.map((_, i) => 100 + Math.sin(i / 3) * 8 + Math.random() * 2),
+    },
+  ],
+}
+
+export const AreaChartExample = () => {
+  return <AreaChart data={data} height={280} />
+}

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

@@ -0,0 +1,9 @@
+.mdk-area-chart {
+  position: relative;
+  width: 100%;
+  
+  canvas {
+    max-width: 100% !important;
+    height: auto !important;
+  }
+}