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

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

@@ -0,0 +1,37 @@
+# Indicator
+
+A colored pill/badge used to display statuses, counts, or labels. Supports color variants, sizes, vertical stacking, and an optional click handler.
+
+<!-- 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` | - | Children content (can include text, icons, multiple elements) |
+| `className` | Optional | `string` | - | Custom className for the root element |
+| `color` | Optional | `"red" \| "gray" \| "blue" \| "yellow" \| "green" \| "purple" \| "amber" \| "slate"` | `"gray"` | Color variant of the indicator |
+| `onClick` | Optional | `(VoidFunction & React.MouseEventHandler<HTMLDivElement>)` | - | Click handler |
+| `size` | Optional | `"sm" \| "md" \| "lg"` | `"md"` | Size variant of the indicator |
+| `vertical` | Optional | `boolean` | `false` | When true, adds extra spacing between child elements and stacks them vertically. Useful for displaying multiple pieces of information (e.g. status + count) in a clear way |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { Indicator, INDICATOR_COLORS } from "@tetherto/mdk-react-devkit"
+
+// Status badge
+<Indicator color="green" size="lg">Running</Indicator>
+
+// With icon and count
+<Indicator color={INDICATOR_COLORS.AMBER}>
+  <span>Pending</span>
+  <span>12</span>
+</Indicator>
+
+// Clickable with vertical layout
+<Indicator color="blue" vertical onClick={() => navigate("/alerts")}>
+  <span>Alerts</span>
+  <span>5</span>
+</Indicator>
+```

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

@@ -0,0 +1,38 @@
+/**
+ * Runnable example for Indicator.
+ */
+import { Indicator } from '@tetherto/mdk-react-devkit'
+
+export const IndicatorExample = () => (
+  <div className="mdk-example-col">
+    <div className="mdk-example-row">
+      <Indicator color="green">Online</Indicator>
+      <Indicator color="red">Offline</Indicator>
+      <Indicator color="amber">Maintenance</Indicator>
+      <Indicator color="gray">Unknown</Indicator>
+    </div>
+
+    <div className="mdk-example-row">
+      <Indicator color="green" size="sm">
+        Running
+      </Indicator>
+      <Indicator color="blue" size="md">
+        Syncing
+      </Indicator>
+      <Indicator color="purple" size="lg">
+        Overclocked
+      </Indicator>
+    </div>
+
+    <div className="mdk-example-row">
+      <Indicator color="green" vertical>
+        <span>Running</span>
+        <span>142</span>
+      </Indicator>
+      <Indicator color="red" vertical>
+        <span>Offline</span>
+        <span>23</span>
+      </Indicator>
+    </div>
+  </div>
+)

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

@@ -0,0 +1,132 @@
+@use '../../styles/mixins' as *;
+.mdk-indicator {
+  @include inline_flex_align;
+
+  justify-content: center;
+  gap: 8px;
+  font-family: var(--font-mono);
+  font-weight: 500;
+  transition: opacity 0.2s;
+  text-transform: capitalize;
+  white-space: nowrap;
+
+  /* Direct children spacing */
+  > span + span {
+    margin-left: 4px;
+  }
+
+  > span + svg {
+    margin-left: 4px;
+  }
+
+  /* Size Variants */
+  &--sm {
+    font-size: 12px;
+    padding: 0.25rem 0.5rem;
+    line-height: 1rem;
+    gap: 6px;
+
+    svg {
+      width: 12px;
+      height: 12px;
+    }
+  }
+
+  &--md {
+    font-size: 14px;
+    padding: 0.375rem 0.75rem;
+    line-height: 1.25rem;
+    gap: 8px;
+
+    svg {
+      width: 14px;
+      height: 14px;
+    }
+  }
+
+  &--lg {
+    font-size: 16px;
+    padding: 0.5rem 1rem;
+    line-height: 1.5rem;
+    gap: 10px;
+
+    svg {
+      width: 16px;
+      height: 16px;
+    }
+  }
+
+  /* Icon styling */
+  svg {
+    flex-shrink: 0;
+    opacity: 0.8;
+    transition:
+      opacity 0.2s,
+      transform 0.2s;
+  }
+
+  /* Color Variants */
+  &--red {
+    background-color: rgba(var(--mdk-color-error), 0.1);
+    color: rgb(var(--mdk-color-error));
+  }
+
+  &--gray {
+    background-color: rgba(var(--mdk-color-dark-grey), 0.1);
+    color: rgb(var(--mdk-color-dark-grey));
+  }
+
+  &--blue {
+    background-color: rgba(var(--mdk-color-sleep-blue), 0.1);
+    color: rgb(var(--mdk-color-sleep-blue));
+  }
+
+  &--yellow {
+    background-color: rgba(var(--mdk-color-low-yellow), 0.1);
+    color: rgb(var(--mdk-color-low-yellow));
+  }
+
+  &--green {
+    background-color: rgba(var(--mdk-color-success), 0.1);
+    color: rgb(var(--mdk-color-success));
+  }
+
+  &--purple {
+    background-color: rgba(var(--mdk-color-purple-high), 0.1);
+    color: rgb(var(--mdk-color-purple-high));
+  }
+
+  &--amber {
+    background-color: rgba(var(--mdk-color-orange-warning), 0.1);
+    color: rgb(var(--mdk-color-orange-warning));
+  }
+
+  &--slate {
+    background-color: rgba(var(--mdk-color-grey-idle), 0.1);
+    color: rgb(var(--mdk-color-grey-idle));
+  }
+
+  /* Clickable State */
+  &--clickable {
+    cursor: pointer;
+    user-select: none;
+
+    &:hover {
+      opacity: 0.8;
+
+      svg {
+        opacity: 1;
+        transform: translateY(2px);
+      }
+    }
+
+    &:active {
+      opacity: 0.9;
+      transform: scale(0.98);
+    }
+  }
+
+  &--vertical {
+    @include flex_column_align_center;
+  }
+}

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

@@ -0,0 +1,27 @@
+# Input
+
+Text input with label support, prefix/suffix slots, sizes, error state, and
+a search-icon variant.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `error` | Optional | `string` | - | Validation error message. When provided, displays error styling (red border) and the message below the input |
+| `id` | Optional | `string` | `auto-generated` | HTML id for the input. Required when using label for accessibility |
+| `label` | Optional | `string` | - | Optional label displayed above the input |
+| `prefix` | Optional | `React.ReactNode` | - | Prefix element displayed before the input (left side) |
+| `size` | Optional | `"default" \| "medium"` | `"default"` | Size of the input - `default`: padding 10px 12px, icon 16px - `medium`: padding 6px 12px, icon 12px |
+| `suffix` | Optional | `React.ReactNode` | - | Suffix element displayed after the input (right side) |
+| `variant` | Optional | `"search" \| "default"` | `"default"` | Variant of the input - `default`: Standard text input - `search`: Input with magnifying glass icon on the right |
+| `wrapperClassName` | Optional | `string` | - | Custom className for the root wrapper |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<Input label="MAC Address" placeholder="Enter MAC address" id="mac" />
+<Input variant="search" placeholder="Search" />
+<Input prefix="$" suffix="USD" placeholder="0.00" />
+```

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

@@ -0,0 +1,23 @@
+/**
+ * Runnable example for Input.
+ */
+import { useState } from 'react'
+import { Input } from '@tetherto/mdk-react-devkit'
+
+export const InputExample = () => {
+  const [value, setValue] = useState('')
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16, maxWidth: 320 }}>
+      <Input
+        id="mac"
+        label="MAC address"
+        placeholder="AA:BB:CC:00:00:01"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+      <Input variant="search" placeholder="Search miners" />
+      <Input prefix="$" suffix="USD" placeholder="0.00" />
+      <Input label="Invalid" error="Must be a hex string" defaultValue="abc" />
+    </div>
+  )
+}

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

@@ -0,0 +1,160 @@
+@use '../../styles/mixins' as *;
+$input-default-padding: 9px 12px;
+$input-medium-padding: 6px 12px;
+
+.mdk-input-root {
+  @include flex_column;
+
+  gap: 0.5rem;
+  width: 100%;
+  min-width: 0;
+}
+
+.mdk-input__label {
+  color: var(--mdk-color-white);
+  font-size: var(--mdk-font-size, 14px);
+  line-height: var(--mdk-line-height, 22px);
+}
+
+.mdk-input__wrapper {
+  @include flex_align;
+
+  position: relative;
+  width: 100%;
+  min-width: 0;
+
+  &--search {
+    .mdk-input {
+      padding-right: 2.5rem;
+    }
+  }
+
+  &--has-prefix {
+    .mdk-input {
+      padding-left: 2.5rem;
+    }
+  }
+
+  &--has-suffix {
+    .mdk-input {
+      padding-right: 2.5rem;
+    }
+  }
+
+  &--has-prefix.mdk-input__wrapper--has-suffix {
+    .mdk-input {
+      padding-inline: 2.5rem;
+    }
+  }
+
+  &--disabled {
+    cursor: not-allowed;
+    opacity: 0.7;
+  }
+
+  &--error {
+    .mdk-input {
+      border-color: rgb(var(--mdk-color-error));
+    }
+
+    .mdk-input:hover:not(:disabled):not(:focus),
+    .mdk-input:focus {
+      border-color: rgb(var(--mdk-color-error));
+    }
+  }
+}
+
+.mdk-input__error {
+  color: rgb(var(--mdk-color-error));
+  font-size: var(--mdk-font-size, 14px);
+  line-height: var(--mdk-line-height, 22px);
+}
+
+.mdk-input__prefix,
+.mdk-input__suffix,
+.mdk-input__icon {
+  @include flex_center;
+
+  position: absolute;
+  pointer-events: none;
+  font-size: var(--mdk-font-size, 14px);
+  line-height: var(--mdk-line-height, 22px);
+  color: var(--mdk-input-placeholder-color);
+}
+
+.mdk-input__icon {
+  width: 16px;
+  height: 16px;
+}
+
+.mdk-input__prefix {
+  left: 0.75rem;
+}
+
+.mdk-input__suffix,
+.mdk-input__icon {
+  right: 0.75rem;
+}
+
+.mdk-input {
+  @include flex_align;
+
+  width: 100%;
+  outline: none;
+  font-size: 14px;
+  transition:
+    border-color 0.2s,
+    background-color 0.2s;
+  border-radius: 0;
+  line-height: 20px;
+  font-family: inherit;
+  border: 1px solid transparent;
+  padding: $input-default-padding;
+  color: var(--mdk-color-text-disabled);
+  background-color: var(--mdk-color-white-transparent);
+
+  &[aria-invalid='true'] {
+    border-color: rgb(var(--mdk-color-error));
+  }
+
+  &--size-medium {
+    padding: $input-medium-padding;
+  }
+
+  &::placeholder {
+    color: var(--mdk-input-placeholder-color);
+  }
+
+  &:hover:not(:disabled):not(:focus) {
+    border-color: var(--mdk-color-white-alpha-04d);
+    background-color: var(--mdk-color-white-alpha-026);
+  }
+
+  &:focus {
+    border-color: var(--mdk-color-primary);
+    background-color: var(--mdk-color-white-2);
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+  }
+
+  /* Hide number input spinner arrows */
+  &[type='number']::-webkit-outer-spin-button,
+  &[type='number']::-webkit-inner-spin-button {
+    -webkit-appearance: none;
+    margin: 0;
+  }
+
+  &[type='number'] {
+    -moz-appearance: textfield;
+    appearance: textfield;
+  }
+}
+
+.mdk-input__wrapper--size-medium {
+  .mdk-input__icon {
+    width: 14px;
+    height: 14px;
+  }
+}

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

@@ -0,0 +1,24 @@
+# Label
+
+Accessible `<label>` element for form fields. Built on Radix UI Label so that
+clicks anywhere on the label focus the associated input.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `htmlFor` | Optional | `string` | - | Id of the input being labelled |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<Label htmlFor="email">Email</Label>
+<Input id="email" type="email" />
+```
+
+## Notes
+
+- Pair with `Input`, `Select`, `Checkbox`, `Switch`, etc. via `htmlFor`
+- Inside an MDK `<Form>` use `<FormLabel>` instead — it auto-links to the field

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

@@ -0,0 +1,13 @@
+/**
+ * Runnable example for Label.
+ */
+import { Input, Label } from '@tetherto/mdk-react-devkit'
+
+export const LabelExample = () => {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, maxWidth: 320 }}>
+      <Label htmlFor="email">Email</Label>
+      <Input id="email" type="email" placeholder="you@example.com" />
+    </div>
+  )
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Label Component Styles
+ */
+
+.mdk-label {
+  font-family: var(--font-mono);
+  font-size: 0.875rem;
+  font-weight: 500;
+  line-height: 1;
+
+  &:has(+ :disabled) {
+    cursor: not-allowed;
+    opacity: 0.7;
+  }
+}

package/src/primitives/components/labeled-card/USAGE.md

@@ -0,0 +1,47 @@
+# `LabeledCard`
+
+A generic card container with a header label, optional navigation link, and configurable layout modifiers.
+
+<!-- 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` | - | Card body content |
+| `className` | Optional | `string` | - | Additional class for the root element |
+| `getNavigateOptions` | Optional | `(label: string) => Partial<{ href: string; target: string }>` | - | Returns a link `href`/`target` for the label when provided |
+| `hasNoBorder` | Optional | `boolean` | `false` | Removes the card border |
+| `hasNoMargin` | Optional | `boolean` | `false` | Removes default margin |
+| `hasNoWrap` | Optional | `boolean` | `false` | Prevents content from wrapping |
+| `isDark` | Optional | `boolean` | `false` | Applies a dark background modifier |
+| `isFullHeight` | Optional | `boolean` | `false` | Stretches the card to full container height |
+| `isFullWidth` | Optional | `boolean` | `false` | Stretches the card to full container width |
+| `isRelative` | Optional | `boolean` | `false` | Sets `position: relative` on the container |
+| `isScrollable` | Optional | `boolean` | `false` | Enables vertical scroll on the card body |
+| `label` | Optional | `React.ReactNode` | - | Header content shown above the card body |
+| `labelTooltip` | Optional | `React.ReactNode` | - | Tooltip shown when hovering the label, e.g. to explain what a count includes |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { LabeledCard } from "@tetherto/mdk-react-devkit"
+
+<LabeledCard label="Device Overview" isFullWidth>
+  <p>Content goes here.</p>
+</LabeledCard>
+
+// With a navigation link and a tooltip on the label
+<LabeledCard
+  label="Miners with error"
+  labelTooltip="Excludes minor errors that don't affect hashrate"
+  getNavigateOptions={(label) => ({ href: "/miners?filter=error" })}
+>
+  <MinerList />
+</LabeledCard>
+```
+
+## Notes
+
+- `labelTooltip` wraps the label in a tooltip; any label can have one
+- `getNavigateOptions` only activates when `label` is a plain string

package/src/primitives/components/labeled-card/labeled-card.example.tsx

@@ -0,0 +1,50 @@
+/**
+ * Runnable example for LabeledCard.
+ */
+import { LabeledCard } from '@tetherto/mdk-react-devkit'
+
+const Placeholder = ({ text }: { text: string }) => (
+  <div
+    style={{
+      padding: '12px 16px',
+      background: 'var(--mdk-color-surface-secondary, #1a1a2e)',
+      borderRadius: 4,
+      color: 'var(--mdk-color-text-secondary, #888)',
+      fontSize: 13,
+    }}
+  >
+    {text}
+  </div>
+)
+
+export const LabeledCardExample = () => (
+  <div className="mdk-example-row" style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+    {/* Basic */}
+    <LabeledCard label="Device Overview">
+      <Placeholder text="Device stats here" />
+    </LabeledCard>
+
+    {/* Full width */}
+    <LabeledCard label="Farm Summary" isFullWidth>
+      <Placeholder text="Full-width card body" />
+    </LabeledCard>
+
+    {/* Dark variant */}
+    <LabeledCard label="Metrics" isDark>
+      <Placeholder text="Dark card body" />
+    </LabeledCard>
+
+    {/* No border */}
+    <LabeledCard label="Borderless" hasNoBorder>
+      <Placeholder text="Card without a border" />
+    </LabeledCard>
+
+    {/* With navigation link on the label */}
+    <LabeledCard
+      label="Pool Statistics"
+      getNavigateOptions={() => ({ href: '#pool-stats', target: '_self' })}
+    >
+      <Placeholder text="Click the label to navigate" />
+    </LabeledCard>
+  </div>
+)

package/src/primitives/components/labeled-card/styles.scss

@@ -0,0 +1,114 @@
+@use '../../styles/mixins' as *;
+
+/**
+ * LabeledCard component styles
+ */
+
+$transsition-duration: 0.3s;
+$labeled-card-cut-edge-size: 8px;
+$labeled-card-cut-before-edge-size: 7.5px;
+
+.mdk-labeled-card {
+  @include flex_column;
+
+  position: relative;
+  overflow: hidden;
+  box-sizing: border-box;
+  transition: border-color $transsition-duration;
+  background-color: var(--mdk-color-surface);
+  border: 1px solid var(--mdk-border-default-color);
+
+  clip-path: polygon(
+    $labeled-card-cut-edge-size 0,
+    100% 0,
+    100% 100%,
+    0 100%,
+    0 $labeled-card-cut-edge-size
+  );
+
+  &::before {
+    position: absolute;
+    content: '';
+    top: 0;
+    left: 0;
+    width: 0;
+    height: 0;
+    z-index: 1;
+    transition: border-color $transsition-duration;
+    border-right: $labeled-card-cut-before-edge-size solid transparent;
+    border-top: $labeled-card-cut-before-edge-size solid var(--mdk-border-default-color);
+  }
+
+  @media (min-width: 768px) {
+    &:hover {
+      border-color: var(--mdk-color-primary);
+
+      &::before {
+        border-top-color: var(--mdk-color-primary);
+      }
+    }
+  }
+
+  &--full-width {
+    width: 100%;
+  }
+
+  &--full-height {
+    height: 100%;
+  }
+
+  &--dark {
+    background-color: var(--mdk-color-dark);
+  }
+
+  &--no-wrap {
+    white-space: nowrap;
+  }
+
+  &--no-margin {
+    margin: 0;
+  }
+
+  &--no-border {
+    border: none;
+
+    &::before {
+      display: none;
+    }
+  }
+
+  &--scrollable {
+    overflow: auto;
+  }
+
+  &--relative {
+    position: relative;
+  }
+
+  &__header {
+    padding: 12px;
+    border-bottom: 1px solid var(--mdk-border-default-color);
+  }
+
+  &__title {
+    font-size: 14px;
+    font-weight: 500;
+    text-decoration: none;
+    font-family: var(--font-mono);
+    color: var(--mdk-color-white);
+  }
+
+  &__link {
+    color: inherit;
+    text-decoration: none;
+
+    &:hover {
+      color: var(--mdk-color-primary);
+    }
+  }
+
+  &__body {
+    flex: 1;
+    overflow: hidden;
+  }
+}