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

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

@@ -0,0 +1,106 @@
+@use '../../styles/mixins' as *;
+/* ========================================
+   Breadcrumbs Component Styles
+   ======================================== */
+
+.mdk-breadcrumbs {
+  @include flex_column;
+
+  gap: 0.5rem;
+}
+
+/* Back Button */
+.mdk-breadcrumbs__back {
+  @include inline_flex_align;
+
+  all: unset;
+  gap: 0.5rem;
+  cursor: pointer;
+  font-weight: 500;
+  font-size: 0.875rem;
+  white-space: nowrap;
+  font-family: var(--font-mono);
+  transition: opacity 200ms ease;
+  color: var(--mdk-breadcrumbs-back-button-color);
+
+  &:hover {
+    opacity: 0.8;
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--mdk-color-primary);
+    outline-offset: 2px;
+    border-radius: 4px;
+  }
+
+  > span {
+    line-height: 1;
+  }
+}
+
+.mdk-breadcrumbs__back-icon {
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+  display: block;
+}
+
+/* Breadcrumb List */
+.mdk-breadcrumbs__list {
+  @include flex_align;
+
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.mdk-breadcrumbs__item {
+  @include flex_align;
+
+  gap: 0.5rem;
+}
+
+/* Breadcrumb Links */
+.mdk-breadcrumbs__link {
+  font-size: 0.875rem;
+  text-decoration: none;
+  transition: color 200ms ease;
+  font-family: var(--font-mono);
+  color: rgb(var(--mdk-breadcrumbs-link-color));
+
+  &:hover {
+    color: var(--mdk-breadcrumbs-link-hover-color);
+  }
+
+  &:focus-visible {
+    border-radius: 2px;
+    outline-offset: 2px;
+    outline: 2px solid var(--mdk-breadcrumbs-link-hover-color);
+  }
+
+  &--button {
+    all: unset;
+    cursor: pointer;
+    font-family: var(--font-mono);
+    font-size: 0.875rem;
+    color: rgb(var(--mdk-breadcrumbs-link-color));
+
+    &:hover {
+      color: var(--mdk-breadcrumbs-link-hover-color);
+    }
+  }
+
+  &--current {
+    font-weight: bold;
+  }
+}
+
+/* Separator */
+.mdk-breadcrumbs__separator {
+  user-select: none;
+  font-size: 0.875rem;
+  font-family: var(--font-mono);
+  color: var(--mdk-breadcrumbs-separator-color);
+}

package/src/primitives/components/btc-average-price/USAGE.md

@@ -0,0 +1,32 @@
+# `BtcAveragePrice`
+
+Read-only BTC average price readout (`BTC Average Price: $97,500`) for reporting
+toolbars. The value is formatted with `formatNumber` (grouping, no decimal places).
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `label` | Optional | `string` | `"BTC Average Price"` | Label for the BTC average price |
+| `price` | Optional | `number \| null` | - | BTC price in USD; formatted with grouping and no decimal places. When `null`, `undefined`, non-finite, or negative, the value shows `-` (`FALLBACK` from format utils) |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<BtcAveragePrice price={97_500} />
+```
+
+Invalid or missing price still renders the label; the amount shows the fallback:
+
+```tsx
+<BtcAveragePrice price={null} />
+// BTC Average Price: -
+```
+
+## Notes
+
+- Styling uses the `mdk-btc-average-price` BEM block; no size or color variants
+- Use a dark toolbar background so default light text remains readable
+- `price={0}` renders `$0`

package/src/primitives/components/btc-average-price/btc-average-price.example.tsx

@@ -0,0 +1,11 @@
+/**
+ * Runnable example for BtcAveragePrice.
+ */
+import { BtcAveragePrice } from '@tetherto/mdk-react-devkit'
+
+export const BtcAveragePriceExample = () => (
+  <div className="mdk-example-col">
+    <BtcAveragePrice price={97_500} />
+    <BtcAveragePrice price={null} />
+  </div>
+)

package/src/primitives/components/btc-average-price/styles.scss

@@ -0,0 +1,22 @@
+@use '../../styles/mixins' as *;
+
+.mdk-btc-average-price {
+  @include flex_row;
+
+  gap: 8px;
+  font-size: 12px;
+  font-weight: 800;
+  white-space: nowrap;
+  align-items: center;
+  box-sizing: border-box;
+  text-transform: uppercase;
+  color: var(--mdk-color-white);
+}
+
+.mdk-btc-average-price__header {
+  color: rgb(var(--mdk-color-grey-idle));
+}
+
+.mdk-btc-average-price__value {
+  color: var(--mdk-color-primary);
+}

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

@@ -0,0 +1,37 @@
+# Button
+
+Primary action button with variants, sizes, loading state, icon placement, and
+full-width layout. Forwards refs and all native `<button>` attributes.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `contentClassName` | Optional | `string` | - | Class names applied to the inner content wrapper |
+| `disabled` | Optional | `boolean` | `false` | Disable the button |
+| `fullWidth` | Optional | `boolean` | `false` | Make the button stretch to fill its container |
+| `icon` | Optional | `React.ReactNode` | - | Icon node rendered alongside `children` |
+| `iconPosition` | Optional | `"left" \| "right"` | `"left"` | Icon placement relative to children |
+| `loading` | Optional | `boolean` | `false` | Show a spinner instead of the content and disable the button |
+| `size` | Optional | `"sm" \| "md" \| "lg"` | - | Size token (`sm`, `md`, `lg`) |
+| `type` | Optional | `"button" \| "submit" \| "reset"` | `"button"` | Native button type |
+| `variant` | Optional | `"icon" \| "link" \| "primary" \| "danger" \| "secondary" \| "tertiary" \| "nav-link" \| "outline" \| "ghost"` | `"secondary"` | Visual variant (e.g. `primary`, `secondary`, `ghost`) |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<Button variant="primary" onClick={handleSave}>Save</Button>
+<Button loading>Submitting…</Button>
+```
+
+## Data contracts
+
+`ButtonVariant` and `ComponentSize` are exported from [`core/types`](../../types/index.ts).
+
+## Notes
+
+- `aria-busy` is set when `loading` is true
+- When `loading` is true the inner spinner is the only child; `icon` and
+  `children` are hidden.

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

@@ -0,0 +1,23 @@
+/**
+ * Runnable example for Button.
+ */
+import { Button } from '@tetherto/mdk-react-devkit'
+
+export const ButtonExample = () => (
+  <div className="mdk-example-row">
+    <Button variant="primary">Primary</Button>
+    <Button variant="secondary">Secondary</Button>
+    <Button variant="primary" loading>
+      Submitting
+    </Button>
+    <Button variant="secondary" disabled>
+      Disabled
+    </Button>
+    <Button variant="primary" size="sm">
+      Small
+    </Button>
+    <Button variant="primary" size="lg">
+      Large
+    </Button>
+  </div>
+)

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

@@ -0,0 +1,181 @@
+@use '../../styles/mixins' as *;
+$animation-duration: 0.3s;
+
+$button-icon-size: 12px;
+$button-min-height-link: 18px;
+$button-min-height-common: 40px;
+$button-min-width-loading: 80px;
+$button-content-line-height: 18px;
+$button-min-height-tertiary: 30px;
+
+.mdk-button {
+  @include flex_center;
+
+  cursor: pointer;
+  box-shadow: none;
+  padding: 10px 21px;
+  border: 1px solid transparent;
+  font-family: var(--font-mono);
+  min-height: $button-min-height-common;
+  transition:
+    background-color $animation-duration ease,
+    border-color $animation-duration ease,
+    color $animation-duration ease;
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  &__content {
+    @include flex_align;
+
+    gap: 8px;
+    line-height: $button-content-line-height;
+  }
+
+  &__children {
+    @include flex_center;
+
+    letter-spacing: 0;
+    font-size: var(--button-font-size, 14px);
+    font-weight: var(--button-font-weight, 500);
+  }
+
+  &__icon {
+    @include flex_center;
+
+    svg {
+      width: $button-icon-size;
+      height: $button-icon-size;
+    }
+  }
+
+  &__loading {
+    @include flex_center;
+
+    min-width: $button-min-width-loading;
+    color: inherit;
+
+    .mdk-spinner {
+      transform: scale(0.75);
+      transform-origin: center;
+    }
+
+    .mdk-spinner__circle {
+      border-color: currentColor;
+      border-top-color: transparent;
+    }
+  }
+
+  &--size {
+    &-sm {
+      min-height: unset;
+      height: 32px;
+    }
+    &-md {
+      min-height: unset;
+      height: 40px;
+    }
+    &-lg {
+      min-height: unset;
+      height: 48px;
+    }
+  }
+
+  &--full-width {
+    width: 100%;
+  }
+
+  &--variant-primary {
+    color: rgb(var(--mdk-color-black));
+    background-color: var(--mdk-color-primary);
+  }
+
+  &--variant-secondary {
+    color: var(--mdk-color-white-7);
+    background-color: var(--mdk-button-secondary-bg);
+    border-color: var(--mdk-button-secondary-border);
+  }
+
+  &--variant-danger {
+    color: var(--mdk-color-white);
+    background-color: var(--mdk-button-danger-bg);
+  }
+
+  &--variant-tertiary {
+    padding: 5px 21px;
+    line-height: normal;
+    align-self: flex-start;
+    color: var(--mdk-color-primary);
+    min-height: $button-min-height-tertiary;
+    background-color: var(--mdk-orange-dimmer);
+
+    --button-font-size: 12px;
+    --button-font-weight: 700;
+  }
+
+  &--variant-link,
+  &--variant-nav-link {
+    border: none;
+    padding: unset;
+    min-width: unset;
+    position: relative;
+    line-height: normal;
+    max-height: fit-content;
+    background-color: transparent;
+    min-height: $button-min-height-link;
+    color: var(--mdk-color-primary);
+  }
+  &--variant-link {
+    &::after {
+      content: '';
+      position: absolute;
+      left: 0;
+      bottom: 0;
+      width: 100%;
+      height: 1px;
+      opacity: 0;
+      background-color: currentColor;
+      transition: opacity $animation-duration ease;
+    }
+  }
+
+  &--variant-icon {
+    padding: 10px 13px;
+    color: var(--mdk-color-white-7);
+    background-color: var(--mdk-button-secondary-bg);
+    border-color: var(--mdk-button-secondary-border);
+  }
+
+  &:not(:disabled):hover {
+    &.mdk-button--variant-primary {
+      background: var(--mdk-color-primary-button-hover);
+    }
+
+    &.mdk-button--variant-secondary {
+      background: var(--mdk-color-background-dark);
+      border-color: var(--mdk-button-secondary-border-hover);
+    }
+
+    &.mdk-button--variant-danger {
+      background: var(--mdk-button-danger-bg-hover);
+    }
+
+    &.mdk-button--variant-tertiary {
+      background-color: var(--mdk-color-primary);
+      color: rgb(var(--mdk-color-black));
+    }
+
+    &.mdk-button--variant-link {
+      &::after {
+        opacity: 1;
+      }
+    }
+
+    &.mdk-button--variant-icon {
+      background: var(--mdk-color-background-dark);
+      border-color: var(--mdk-button-secondary-border-hover);
+    }
+  }
+}

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

@@ -0,0 +1,31 @@
+# Card
+
+Layout card with optional `Card.Header`, `Card.Body`, and `Card.Footer` slots.
+Default children go to body. Forwards all native `<div>` attributes; pass
+`onClick` to make the whole card clickable.
+
+## Slots
+
+```tsx
+<Card>
+  <Card.Header>Title</Card.Header>
+  <Card.Body>Content</Card.Body>
+  <Card.Footer>Actions</Card.Footer>
+</Card>
+```
+
+## Props detail
+
+> **Props and the object shapes they reference are generated from this component's TypeScript types, the source of truth.** The following is supplementary (sub-component props, allowed values, `ref` methods, or passthrough props), not the full prop list.
+
+`CardProps`, `CardHeaderProps`, `CardBodyProps`, `CardFooterProps` are all
+`HTMLAttributes<HTMLDivElement>`.
+
+## Example
+
+```tsx
+<Card onClick={() => navigate("/details")}>
+  <Card.Header>Title</Card.Header>
+  Content (default children go to body)
+</Card>
+```

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

@@ -0,0 +1,21 @@
+/**
+ * Runnable example for Card.
+ */
+import { Button, Card } from '@tetherto/mdk-react-devkit'
+
+export const CardExample = () => (
+  <Card className="mdk-example-card">
+    <Card.Header>
+      <strong>Container 03</strong>
+    </Card.Header>
+    <Card.Body>
+      <p>Power: 31.5 kW</p>
+      <p>Hashrate: 102.4 TH/s</p>
+    </Card.Body>
+    <Card.Footer>
+      <Button variant="primary" size="sm">
+        Details
+      </Button>
+    </Card.Footer>
+  </Card>
+)

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

@@ -0,0 +1,73 @@
+/**
+ * Card component styles
+ */
+
+$mdk-card-cut-edge-size: 8px;
+$mdk-card-cut-before-edge-size: 7.5px;
+
+.mdk-card {
+  position: relative;
+
+  &.mdk-card--clickable {
+    cursor: pointer;
+  }
+
+  box-sizing: border-box;
+  overflow: hidden;
+  background-color: var(--mdk-color-surface);
+  border: 1px solid var(--mdk-border-default-color);
+  transition: border-color 0.4s;
+
+  /* Cut corner at top-left - creates the angled notch */
+  clip-path: polygon(
+    $mdk-card-cut-edge-size 0,
+    100% 0,
+    100% 100%,
+    0 100%,
+    0 $mdk-card-cut-edge-size
+  );
+
+  /* L-shaped top-left border accent (::before pseudo-element) - orange only on hover */
+  &::before {
+    position: absolute;
+    content: '';
+    top: 0;
+    left: 0;
+    width: 0;
+    height: 0;
+    border-top: $mdk-card-cut-before-edge-size solid var(--mdk-border-default-color);
+    border-right: $mdk-card-cut-before-edge-size solid transparent;
+    transition: border-color 0.4s;
+    z-index: 1;
+  }
+
+  @media (min-width: 768px) {
+    &:hover {
+      border-color: var(--mdk-color-primary);
+
+      &::before {
+        border-top-color: var(--mdk-color-primary);
+      }
+    }
+  }
+
+  &__header {
+    padding: 16px;
+
+    &:not(:last-child) {
+      border-bottom: 1px solid var(--mdk-color-white-transparent);
+    }
+  }
+
+  &__body {
+    padding: 16px;
+
+    &:not(:last-child) {
+      border-bottom: 1px solid var(--mdk-color-white-transparent);
+    }
+  }
+
+  &__footer {
+    padding: 16px;
+  }
+}

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

@@ -0,0 +1,77 @@
+# Cascader
+
+A two-panel hierarchical selection component. The left panel lists categories; the right panel shows their children. Supports single and multiple selection modes and a flat search view.
+
+<!-- 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 | `CascaderOption[]` | - | Hierarchical options to display in the cascader Parent options with children appear in the left panel Child options appear in the right panel when parent is selected |
+| `className` | Optional | `string` | - | Custom className for the root cascader element |
+| `disabled` | Optional | `boolean` | `false` | Disable the entire cascader (input and all options) |
+| `dropdownClassName` | Optional | `string` | - | Custom className for the dropdown panels container |
+| `multiple` | Optional | `boolean` | `false` | Enable multiple selection mode - true: Shows checkboxes, allows multiple selections, displays selected items as tags - false: Shows radio buttons, allows single selection |
+| `onChange` | Optional | `((value: CascaderValue \| CascaderValue[] \| null) => void)` | - | Callback when selection changes - For single select: receives CascaderValue or null - For multiple select: receives CascaderValue[] or null |
+| `placeholder` | Optional | `string` | `"Select..."` | Placeholder text shown in the input when no selections are made |
+| `value` | Optional | `CascaderValue \| CascaderValue[]` | - | Current selected value(s) - For single select: CascaderValue (e.g., ['category', 'option']) - For multiple select: CascaderValue[] (e.g., [['cat1', 'opt1'], ['cat2', 'opt2']]) |
+
+### `CascaderOption`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `string` | - | Display label for the option |
+| `value` | Required | `string \| number \| boolean` | - | Unique value for the option |
+| `children` | Optional | `CascaderOption[]` | - | Child options (creates a nested category) |
+| `disabled` | Optional | `boolean` | - | Whether the option is disabled |
+<!-- END GENERATED: props -->
+
+## Props detail
+
+> **Props and the object shapes they reference are generated from this component's TypeScript types, the source of truth.** The following is supplementary (sub-component props, allowed values, `ref` methods, or passthrough props), not the full prop list.
+
+### Types
+
+- `CascaderValue` — `(string | number | boolean)[]` — path from parent to leaf (e.g. `['electronics', 'phones']`)
+
+## Example
+
+```tsx
+import { Cascader } from "@tetherto/mdk-react-devkit"
+
+const options = [
+  {
+    value: "status",
+    label: "Status",
+    children: [
+      { value: "active", label: "Active" },
+      { value: "offline", label: "Offline" },
+    ],
+  },
+]
+
+// Single select
+const [value, setValue] = useState<CascaderValue>(["status", "active"])
+
+<Cascader
+  options={options}
+  value={value}
+  onChange={(value) => setValue(value as CascaderValue)}
+/>
+
+// Multi-select
+const [values, setValues] = useState<CascaderValue[]>([])
+
+<Cascader
+  options={options}
+  value={values}
+  onChange={(value) => setValues(value as CascaderValue[])}
+  multiple
+  placeholder="Filter by status..."
+/>
+```
+
+## Notes
+
+- Typing in the input switches from the two-panel view to a flat search results list
+- In `multiple` mode, clicking a category header checkbox selects/deselects all its non-disabled children; partial selections show an indeterminate state

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

@@ -0,0 +1,52 @@
+/**
+ * Runnable example for Cascader.
+ */
+import { useState } from 'react'
+import { Cascader } from '@tetherto/mdk-react-devkit'
+import type { CascaderValue } from '@tetherto/mdk-react-devkit'
+
+const poolOptions = [
+  {
+    value: 'foundry',
+    label: 'Foundry',
+    children: [
+      { value: 'eu-primary', label: 'EU Primary' },
+      { value: 'us-east', label: 'US East' },
+      { value: 'asia', label: 'Asia Pacific' },
+    ],
+  },
+  {
+    value: 'antpool',
+    label: 'AntPool',
+    children: [
+      { value: 'btc', label: 'BTC' },
+      { value: 'ltc', label: 'LTC' },
+    ],
+  },
+]
+
+export const CascaderExample = () => {
+  const [single, setSingle] = useState<CascaderValue>(['foundry', 'eu-primary'])
+  const [multi, setMulti] = useState<CascaderValue[]>([
+    ['foundry', 'eu-primary'],
+    ['antpool', 'btc'],
+  ])
+
+  return (
+    <div className="mdk-example-col">
+      <Cascader
+        options={poolOptions}
+        value={single}
+        onChange={(value) => setSingle(value as CascaderValue)}
+        placeholder="Select pool..."
+      />
+      <Cascader
+        options={poolOptions}
+        value={multi}
+        onChange={(value) => setMulti(value as CascaderValue[])}
+        multiple
+        placeholder="Select pools..."
+      />
+    </div>
+  )
+}