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

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

@@ -0,0 +1,29 @@
+# Avatar
+
+Composable image avatar with an automatic fallback. Wraps Radix UI `@radix-ui/react-avatar`.
+
+## Exports
+
+| Name | Description |
+| ---- | ----------- |
+| `Avatar` | Root container (`mdk-avatar`) |
+| `AvatarImage` | The `<img>` element (`mdk-avatar__image`) |
+| `AvatarFallback` | Content shown while the image is loading or fails (`mdk-avatar__fallback`) |
+
+All three components accept a `className` prop and forward their `ref`. All native Radix props are also passed through.
+
+## Example
+
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from "@tetherto/mdk-react-devkit"
+
+<Avatar>
+  <AvatarImage src="https://example.com/user.png" alt="Jane Doe" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+## Notes
+
+- `AvatarFallback` is only rendered while the image is loading or when the image fails to load; Radix handles the visibility automatically.
+- Size and shape are controlled via CSS — apply utility classes or override `mdk-avatar` dimensions via CSS variables.

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

@@ -0,0 +1,24 @@
+/**
+ * Runnable example for Avatar.
+ */
+import { Avatar, AvatarFallback, AvatarImage } from '@tetherto/mdk-react-devkit'
+
+export const AvatarExample = () => (
+  <div className="mdk-example-row">
+    <Avatar>
+      <AvatarImage src="https://i.pravatar.cc/40?img=1" alt="Alice" />
+      <AvatarFallback>AL</AvatarFallback>
+    </Avatar>
+
+    <Avatar>
+      <AvatarImage src="https://i.pravatar.cc/40?img=2" alt="Bob" />
+      <AvatarFallback>BO</AvatarFallback>
+    </Avatar>
+
+    {/* Fallback shown when image fails to load */}
+    <Avatar>
+      <AvatarImage src="/broken-url.png" alt="Charlie" />
+      <AvatarFallback>CH</AvatarFallback>
+    </Avatar>
+  </div>
+)

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

@@ -0,0 +1,29 @@
+@use '../../styles/mixins' as *;
+/**
+ * Avatar Component Styles
+ */
+
+.mdk-avatar {
+  position: relative;
+  display: flex;
+  height: 2.5rem;
+  width: 2.5rem;
+  flex-shrink: 0;
+  overflow: hidden;
+  border-radius: 9999px;
+
+  &__image {
+    aspect-ratio: 1;
+    height: 100%;
+    width: 100%;
+  }
+
+  &__fallback {
+    @include flex_center;
+
+    height: 100%;
+    width: 100%;
+    border-radius: 9999px;
+    background: hsl(var(--muted));
+  }
+}

package/src/primitives/components/average-downtime-chart/USAGE.md

@@ -0,0 +1,41 @@
+# `AverageDowntimeChart`
+
+Stacked bar chart of Curtailment vs Op. Issues downtime rates. 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 |
+|------|--------|----------------|---------|-------------|
+| `barWidth` | Optional | `number` | `38` | Max bar thickness |
+| `className` | Optional | `string` | - | Extra class on the container |
+| `data` | Optional | `AverageDowntimeChartData` | - | Period labels and rate arrays (fractions 0–1) |
+| `emptyMessage` | Optional | `string` | - | Message when there are no period labels or rate series |
+| `height` | Optional | `number` | `280` | Chart height in pixels |
+| `isLoading` | Optional | `boolean` | `false` | Shows loading overlay |
+| `showDataLabels` | Optional | `boolean` | `false` | Show values above stacked bars |
+| `title` | Optional | `string` | `"Monthly Average Downtime"` | Chart title (unit renders on its own line below) |
+| `unit` | Optional | `string` | `%` | Unit subtitle under the title |
+| `yTicksFormatter` | Optional | `(value: number) => string` | - | Formats Y-axis ticks, tooltips, and bar data labels (values are 0–1 rates). Defaults to rate × 100 via `formatNumber` |
+
+### `AverageDowntimeChartData`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `labels` | Required | `string[]` | - | X-axis period labels, one per bar; empty renders the empty state |
+| `curtailment` | Optional | `number[]` | - | "Curtailment" downtime rate per period, as a fraction (0–1), aligned to `labels` |
+| `operationalIssues` | Optional | `number[]` | - | "Op. Issues" downtime rate per period, as a fraction (0–1), stacked on `curtailment` |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<AverageDowntimeChart
+  data={{
+    labels: ['Jan', 'Feb'],
+    curtailment: [0.02, 0.01],
+    operationalIssues: [0.05, 0.04],
+  }}
+/>
+```

package/src/primitives/components/average-downtime-chart/average-downtime-chart.example.tsx

@@ -0,0 +1,13 @@
+import { AverageDowntimeChart } from '@tetherto/mdk-react-devkit/primitives'
+
+export const AverageDowntimeChartExample = () => (
+  <div className="mdk-example-row">
+    <AverageDowntimeChart
+      data={{
+        labels: ['Mon', 'Tue', 'Wed'],
+        curtailment: [0.02, 0.01, 0.03],
+        operationalIssues: [0.05, 0.04, 0.06],
+      }}
+    />
+  </div>
+)

package/src/primitives/components/average-downtime-chart/styles.scss

@@ -0,0 +1,15 @@
+@use '../../styles/mixins' as *;
+
+.mdk-average-downtime-chart {
+  &__header {
+    @include flex_column;
+
+    gap: 4px;
+  }
+
+  &__unit {
+    font-size: 12px;
+    font-family: var(--font-mono);
+    color: rgb(var(--mdk-color-grey-idle));
+  }
+}

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

@@ -0,0 +1,39 @@
+# Badge
+
+Small status indicator displayed standalone or overlaid on another element.
+Renders as a number, dot, custom text, or status pill.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `children` | Optional | `React.ReactNode` | - | Badge content (wraps children with badge) |
+| `className` | Optional | `string` | - | Custom className for badge |
+| `color` | Optional | `"success" \| "info" \| "warning" \| "error" \| "primary" \| "secondary" \| "default"` | `"primary"` | Color variant |
+| `count` | Optional | `number` | `0` | Number to display in badge If > overflowCount, will show "overflowCount+" |
+| `dot` | Optional | `boolean` | `false` | Show badge as a dot |
+| `offset` | Optional | `[number, number]` | `[0, 0]` | Offset position [x, y] in pixels |
+| `overflowCount` | Optional | `number` | `99` | Maximum count to display |
+| `showZero` | Optional | `boolean` | `false` | Whether to show badge when count is 0 |
+| `size` | Optional | `"sm" \| "md" \| "lg"` | `"md"` | Badge size |
+| `square` | Optional | `boolean` | `false` | Square badge (no border-radius) |
+| `status` | Optional | `"success" \| "warning" \| "error" \| "default" \| "processing"` | - | Status badge (small dot badge with text) |
+| `text` | Optional | `string` | - | Custom badge content (overrides count) |
+| `title` | Optional | `string` | - | Badge title for accessibility |
+| `wrapperClassName` | Optional | `string` | - | Custom className for wrapper |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<Badge count={5}><Button>Messages</Button></Badge>
+<Badge dot><BellIcon /></Badge>
+<Badge status="success" text="Online" />
+<Badge count={120} overflowCount={99} />
+```
+
+## Notes
+
+- When used without `children`, renders standalone
+- `dot` and `status` ignore `count` / `text` for the visual but keep `text` as the label when `status` is set

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

@@ -0,0 +1,21 @@
+/**
+ * Runnable example for Badge.
+ */
+import { Badge, Button } from '@tetherto/mdk-react-devkit'
+
+export const BadgeExample = () => (
+  <div className="mdk-example-row">
+    <Badge count={5}>
+      <Button>Messages</Button>
+    </Badge>
+    <Badge count={120} overflowCount={99}>
+      <Button>Notifications</Button>
+    </Badge>
+    <Badge dot>
+      <Button>Updates</Button>
+    </Badge>
+    <Badge status="success" text="Online" />
+    <Badge status="error" text="Offline" />
+    <Badge text="NEW" color="primary" square />
+  </div>
+)

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

@@ -0,0 +1,265 @@
+@use '../../styles/mixins' as *;
+/* ========================================
+   Badge Component Styles
+   ======================================== */
+
+/* Wrapper (when badge has children) */
+.mdk-badge-wrapper {
+  position: relative;
+  line-height: 1;
+}
+
+/* Base Badge */
+.mdk-badge {
+  @include inline_flex_align;
+
+  justify-content: center;
+  font-weight: 700;
+  line-height: 1;
+  white-space: nowrap;
+  text-align: center;
+  border-radius: 9999px; // Default: fully rounded
+  transition: all 0.2s ease;
+  color: var(--mdk-color-white);
+
+  /* When badge has children, position absolutely */
+  .mdk-badge-wrapper & {
+    position: absolute;
+    top: 0;
+    right: 0;
+    transform: translate(50%, -50%);
+    transform-origin: 100% 0%;
+    z-index: 10;
+  }
+
+  /* Animation for new badges */
+  animation: badge-zoom 0.3s cubic-bezier(0.12, 0.4, 0.29, 1.46);
+}
+
+@keyframes badge-zoom {
+  0% {
+    transform: translate(50%, -50%) scale(0);
+  }
+  100% {
+    transform: translate(50%, -50%) scale(1);
+  }
+}
+
+/* Standalone badge (no children) */
+.mdk-badge--standalone {
+  position: relative;
+  transform: none;
+  animation: none;
+}
+
+/* Square badge (no border-radius) */
+.mdk-badge--square {
+  border-radius: 0;
+
+  // Dot badges should still be circles even when square
+  &.mdk-badge--dot {
+    border-radius: 50%;
+  }
+}
+
+/* ========================================
+   SIZE VARIANTS
+   ======================================== */
+
+/* Small */
+.mdk-badge--sm {
+  min-width: 0.875rem;
+  height: 0.875rem;
+  padding: 0 0.25rem;
+  font-size: 0.5625rem;
+  line-height: 0.875rem;
+
+  &.mdk-badge--dot {
+    width: 0.5rem;
+    height: 0.5rem;
+    min-width: 0;
+    padding: 0;
+  }
+
+  .mdk-badge-wrapper & {
+    transform: translate(40%, -40%);
+  }
+
+  @media (min-width: 769px) {
+    min-width: 1rem;
+    height: 1rem;
+    padding: 0 0.3125rem;
+    font-size: 0.625rem;
+    line-height: 1rem;
+  }
+}
+
+/* Medium (Mobile) */
+.mdk-badge--md {
+  min-width: 1rem;
+  height: 1rem;
+  padding: 0 0.375rem;
+  font-size: 0.625rem;
+  line-height: 1rem;
+
+  &.mdk-badge--dot {
+    width: 0.625rem;
+    height: 0.625rem;
+    min-width: 0;
+    padding: 0;
+  }
+
+  .mdk-badge-wrapper & {
+    transform: translate(50%, -50%);
+  }
+
+  @media (min-width: 769px) {
+    min-width: 1.25rem;
+    height: 1.25rem;
+    padding: 0 0.4375rem;
+    font-size: 0.75rem;
+    line-height: 1.25rem;
+  }
+}
+
+/* Large  */
+.mdk-badge--lg {
+  min-width: 1.25rem;
+  height: 1.25rem;
+  padding: 0 0.4375rem;
+  font-size: 0.75rem;
+  line-height: 1.25rem;
+
+  &.mdk-badge--dot {
+    width: 0.75rem;
+    height: 0.75rem;
+    min-width: 0;
+    padding: 0;
+  }
+
+  .mdk-badge-wrapper & {
+    transform: translate(50%, -50%);
+  }
+
+  @media (min-width: 769px) {
+    min-width: 1.5rem;
+    height: 1.5rem;
+    padding: 0 0.5rem;
+    font-size: 0.875rem;
+    line-height: 1.5rem;
+  }
+}
+
+/* ========================================
+   COLOR VARIANTS
+   ======================================== */
+
+/* Default (Gray) */
+.mdk-badge--default {
+  color: var(--mdk-color-surface);
+  background-color: var(--mdk-color-surface);
+}
+
+/* Primary (Orange) */
+.mdk-badge--primary {
+  background-color: var(--mdk-color-primary);
+  color: var(--mdk-color-white);
+}
+
+/* Success (Green) */
+.mdk-badge--success {
+  background-color: var(--mdk-color-brick-green);
+}
+
+/* Warning (Yellow/Orange) */
+.mdk-badge--warning {
+  background-color: rgb(var(--mdk-color-orange-warning));
+}
+
+/* Error (Red) */
+.mdk-badge--error {
+  background-color: rgb(var(--mdk-color-error));
+}
+
+/* Info (Blue) */
+.mdk-badge--info {
+  background-color: rgb(var(--mdk-color-sleep-blue));
+}
+
+/* ========================================
+   DOT BADGE
+   ======================================== */
+
+.mdk-badge--dot {
+  padding: 0;
+  border-radius: 50%; // Always circular for dots
+
+  .mdk-badge-wrapper & {
+    transform: translate(30%, -30%);
+  }
+}
+
+/* ========================================
+   STATUS BADGE
+   ======================================== */
+
+.mdk-badge--status {
+  @include inline_flex_align;
+
+  position: relative;
+  gap: 0.5rem;
+  padding: 0;
+  min-width: 0;
+  height: auto;
+  background: transparent;
+  box-shadow: none;
+  transform: none;
+  animation: none;
+  font-weight: 400;
+  font-size: 0.875rem;
+
+  &::before {
+    content: '';
+    display: inline-block;
+    width: 0.5rem;
+    height: 0.5rem;
+    border-radius: 50%;
+    flex-shrink: 0;
+  }
+
+  &.mdk-badge--status-default::before {
+    background-color: var(--mdk-color-primary);
+  }
+
+  &.mdk-badge--status-success::before {
+    background-color: var(--mdk-color-brick-green);
+  }
+
+  &.mdk-badge--status-processing::before {
+    background-color: rgb(var(--mdk-color-sleep-blue));
+    animation: badge-processing 1.5s ease-in-out infinite;
+  }
+
+  &.mdk-badge--status-error::before {
+    background-color: rgb(var(--mdk-color-error));
+  }
+
+  &.mdk-badge--status-warning::before {
+    background-color: rgb(var(--mdk-color-orange-warning));
+  }
+}
+
+@keyframes badge-processing {
+  0% {
+    opacity: 0.6;
+    transform: scale(0.8);
+  }
+  50% {
+    opacity: 1;
+    transform: scale(1.2);
+  }
+  100% {
+    opacity: 0.6;
+    transform: scale(0.8);
+  }
+}

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

@@ -0,0 +1,56 @@
+# `BarChart`
+
+A Chart.js bar chart with gradient fills, optional stacking, horizontal layout, data labels, and a custom HTML tooltip.
+
+<!-- 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 | `any` | - | Chart data - required, provided by parent. Use `as any` for mixed bar+line datasets |
+| `className` | Optional | `string` | - | Additional class for the wrapper `div` |
+| `formatDataLabel` | Optional | `((value: number) => string)` | - | Format data label values (default: round to nearest integer) |
+| `formatYLabel` | Optional | `((value: number) => string)` | - | Format Y-axis tick labels |
+| `height` | Optional | `number` | `300` | Chart height in pixels |
+| `isHorizontal` | Optional | `boolean` | `false` | Render bars horizontally (indexAxis: 'y') |
+| `isStacked` | Optional | `boolean` | `false` | Stack bars on top of each other |
+| `legendAlign` | Optional | `"center" \| "start" \| "end"` | `"start"` | Alignment of the legend labels within their position |
+| `legendPosition` | Optional | `"left" \| "right" \| "top" \| "bottom"` | `"top"` | Position of the legend |
+| `options` | Optional | `object` | - | Chart.js options - merged with defaults |
+| `showDataLabels` | Optional | `boolean` | `false` | Show values above each bar |
+| `showLegend` | Optional | `boolean` | `true` | Show built-in Chart.js legend |
+| `tooltip` | Optional | `ChartTooltipConfig` | - | Custom HTML tooltip configuration. When provided, replaces the default Chart.js tooltip |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { BarChart } from "@tetherto/mdk-react-devkit"
+
+const data = {
+  labels: ["Jan", "Feb", "Mar"],
+  datasets: [
+    {
+      label: "Hashrate",
+      data: [120, 95, 140],
+      backgroundColor: "#59E8E8",
+    },
+  ],
+}
+
+<BarChart data={data} height={280} formatYLabel={(value) => `${value} TH/s`} />
+
+// Stacked with data labels
+<BarChart
+  data={stackedData}
+  isStacked
+  showDataLabels
+  formatDataLabel={(value) => `${value}%`}
+/>
+```
+
+## Notes
+
+- Bar datasets automatically receive a vertical gradient fill derived from `backgroundColor`. Pass `backgroundColor` as a function to opt out.
+- For mixed bar + line charts pass the dataset `type: 'line'` inside `data.datasets` and use `data` typed as `any`
+- `showDataLabels` adds `chartjs-plugin-datalabels`; it adds 20 px of top padding to prevent label clipping

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

@@ -0,0 +1,35 @@
+/**
+ * Runnable example for BarChart.
+ */
+import { BarChart } from '@tetherto/mdk-react-devkit'
+
+const groupedData = {
+  labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+  datasets: [
+    {
+      label: 'Foundry EU',
+      data: [42, 38, 45, 50, 47, 30, 35],
+      backgroundColor: '#F7931A',
+    },
+    {
+      label: 'AntPool',
+      data: [28, 32, 29, 35, 33, 25, 27],
+      backgroundColor: '#4B9EFF',
+    },
+  ],
+}
+
+const stackedData = {
+  labels: ['Week 1', 'Week 2', 'Week 3', 'Week 4'],
+  datasets: [
+    { label: 'Accepted', data: [320, 340, 310, 360], backgroundColor: '#34C759' },
+    { label: 'Rejected', data: [12, 8, 15, 10], backgroundColor: '#FF3B30' },
+  ],
+}
+
+export const BarChartExample = () => (
+  <div className="mdk-example-col">
+    <BarChart data={groupedData} height={220} />
+    <BarChart data={stackedData} isStacked height={220} showDataLabels />
+  </div>
+)

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

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

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

@@ -0,0 +1,46 @@
+# Breadcrumbs
+
+Horizontal breadcrumb navigation. Renders an ordered trail of links / buttons /
+plain labels with an optional "Back" button on the left.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `items` | Required | `BreadcrumbItem[]` | - | Ordered trail; the last item is rendered as current |
+| `backClassName` | Optional | `string` | - | Class names applied to the back button |
+| `backLabel` | Optional | `string` | `"Back"` | Label for the back button |
+| `className` | Optional | `string` | - | Root class names |
+| `itemClassName` | Optional | `string` | - | Class names applied to each item |
+| `onBackClick` | Optional | `VoidFunction` | - | Callback fired when the back button is clicked |
+| `separator` | Optional | `React.ReactNode` | `"/"` | Custom separator between items |
+| `showBack` | Optional | `boolean` | `false` | Show a leading "Back" button |
+
+### `BreadcrumbItem`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `string` | - | Text shown for the crumb |
+| `href` | Optional | `string` | - | Renders the crumb as a link; takes precedence over `onClick` |
+| `onClick` | Optional | `VoidFunction` | - | Renders the crumb as a button when `href` is absent; with neither, the crumb is plain text |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<Breadcrumbs
+  showBack
+  onBackClick={() => navigate(-1)}
+  items={[
+    { label: "Dashboard", href: "/" },
+    { label: "Devices", onClick: () => navigate("/devices") },
+    { label: "Miner #42" },
+  ]}
+/>
+```
+
+## Notes
+
+- The last item is rendered as the current page (`aria-current="page"`)
+- Items without `href` or `onClick` render as plain text

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

@@ -0,0 +1,16 @@
+/**
+ * Runnable example for Breadcrumbs.
+ */
+import { Breadcrumbs } from '@tetherto/mdk-react-devkit'
+
+export const BreadcrumbsExample = () => (
+  <Breadcrumbs
+    showBack
+    onBackClick={() => undefined}
+    items={[
+      { label: 'Dashboard', href: '/' },
+      { label: 'Devices', onClick: () => undefined },
+      { label: 'Miner #42' },
+    ]}
+  />
+)