@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

package/src/primitives/components/lazy-tab-wrapper/USAGE.md

@@ -0,0 +1,42 @@
+# `LazyTabWrapper`
+
+Wraps a lazily loaded component in `React.Suspense`, displaying a fallback spinner while the module loads. Typed generically so the `data` prop is type-safe.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `Component` | Required | `React.ComponentType<{ data?: T }>` | - | Lazy-loaded component to render |
+| `data` | Optional | `T` | - | Data to pass to the component |
+| `fallback` | Optional | `React.ReactNode` | `<Spinner />` | Custom fallback component while loading |
+| `spinnerType` | Optional | `"circle" \| "square"` | `"circle"` | Spinner type when using default fallback |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { lazy } from "react"
+import { LazyTabWrapper } from "@tetherto/mdk-react-devkit"
+
+const DetailsTab = lazy(() => import("./DetailsTab"))
+
+<LazyTabWrapper Component={DetailsTab} data={deviceData} />
+
+// Custom fallback
+<LazyTabWrapper
+  Component={SettingsTab}
+  data={settings}
+  fallback={<MyCustomLoader />}
+/>
+
+// With typed data
+interface DeviceData { id: string; name: string }
+
+<LazyTabWrapper<DeviceData> Component={DeviceTab} data={device} />
+```
+
+## Notes
+
+- The wrapped component must accept a `{ data?: T }` prop signature
+- For components with no data prop, `T` defaults to `Record<string, unknown>` so `data` is still optional

package/src/primitives/components/lazy-tab-wrapper/lazy-tab-wrapper.example.tsx

@@ -0,0 +1,44 @@
+/**
+ * Runnable example for LazyTabWrapper.
+ */
+import { type ComponentType, lazy } from 'react'
+import { LazyTabWrapper } from '@tetherto/mdk-react-devkit'
+
+// Simulate a lazily-loaded tab component using a pre-resolved promise so the
+// example renders immediately without an actual dynamic import.
+const StaticTab: ComponentType<{ data?: { title: string } }> = ({ data }) => (
+  <div
+    style={{
+      padding: '16px',
+      background: 'var(--mdk-color-surface-secondary, #1a1a2e)',
+      borderRadius: 4,
+      color: 'var(--mdk-color-text-primary, #fff)',
+      fontSize: 13,
+    }}
+  >
+    {data?.title ?? 'Tab content loaded'}
+  </div>
+)
+
+// Wrap in lazy() to satisfy the Suspense contract used by LazyTabWrapper.
+const LazyStaticTab = lazy(() => Promise.resolve({ default: StaticTab }))
+
+export const LazyTabWrapperExample = () => (
+  <div className="mdk-example-row" style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+    {/* Default spinner fallback */}
+    <LazyTabWrapper
+      Component={LazyStaticTab}
+      data={{ title: 'Details Tab (default spinner fallback)' }}
+    />
+
+    {/* Custom fallback */}
+    <LazyTabWrapper
+      Component={LazyStaticTab}
+      data={{ title: 'Settings Tab (custom fallback)' }}
+      fallback={<div style={{ padding: 16, color: '#888', fontSize: 13 }}>Loading settings…</div>}
+    />
+
+    {/* No data prop */}
+    <LazyTabWrapper Component={LazyStaticTab} />
+  </div>
+)

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

@@ -0,0 +1,68 @@
+# `LineChart`
+
+Time-series line chart built on `lightweight-charts`. Supports multi-series
+data, custom tooltips, vertical / horizontal crosshair labels, manual zoom,
+point markers, fixed-timezone formatting, and auto-scaling.
+
+For most use cases prefer wrapping in `ChartContainer` or `LineChartCard` so
+you get title, legend, range selector, and loading / empty states for free.
+
+<!-- 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 | `LineChartData` | - | Data of the chart |
+| `backgroundColor` | Optional | `string` | - | Background color of the chart |
+| `beginAtZero` | Optional | `boolean` | - | Starts the value axis at 0 |
+| `chartRef` | Optional | `React.MutableRefObject<IChartApi \| null>` | - | Mutable ref to hold the LightWeightCharts reference |
+| `customDateFormat` | Optional | `string` | - | Custom date format |
+| `customLabel` | Optional | `string` | - | TODO: Doc |
+| `disableAutoRange` | Optional | `boolean` | - | Disable automatically determining range |
+| `fadedBackground` | Optional | `boolean` | - | Use a faded background |
+| `fixedTimezone` | Optional | `string` | - | Applies offset if provided, otherwise timestamps are assumed to already be in local time. Otherwise, use browser's current timezone offset for consistent time display |
+| `height` | Optional | `number` | `240` | Controls the height of the chart |
+| `horizontalLineLabelVisible` | Optional | `boolean` | - | Show horizontal line at mouse position |
+| `priceFormatter` | Optional | `((value: number) => string)` | - | Callback to format ticks on y axis |
+| `roundPrecision` | Optional | `number` | - | The number of decimals to show |
+| `shouldResetZoom` | Optional | `boolean` | - | Wether to Reset Zoom |
+| `showDateInTooltip` | Optional | `boolean` | - | Show date line in tooltip |
+| `showPointMarkers` | Optional | `boolean` | - | Show a marker on the line |
+| `skipMinWidth` | Optional | `boolean` | - | Do not enforce a min width |
+| `skipRound` | Optional | `boolean` | - | Prevent rounding of values |
+| `timeline` | Optional | `string` | - | TODO: DOC |
+| `uniformDistribution` | Optional | `boolean` | - | Changes horizontal scale marks generation. With this flag equal to true, marks of the same weight are either all drawn or none are drawn at all |
+| `unit` | Optional | `string` | `""` | The unit to display with values |
+| `verticalLineLabelVisible` | Optional | `boolean` | - | Show vertical line at mouse position |
+| `yTicksFormatter` | Optional | `((value: number) => string)` | - | Callback to format ticks on y axis. If `priceFormatter` is given. It would be used instead |
+
+### `LineChartData`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `datasets` | Required | `LineDataset[]` | - | One line series per entry; `visible: false` hides a series without removing it |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+<LineChart
+  data={{ datasets: [{ label: "Hashrate", borderColor: "#4f9ef5", data: points }] }}
+  height={320}
+  unit="TH/s"
+/>
+```
+
+## Data contracts
+
+```ts
+type LineDataPoint = { x: number; y: number | null | undefined };
+type LineDataset = {
+  label?: string;
+  visible?: boolean;
+  borderColor: string;
+  borderWidth?: number;
+  data: LineDataPoint[];
+};
+type LineChartData = { datasets: LineDataset[] };
+```

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

@@ -0,0 +1,27 @@
+/**
+ * Runnable example for LineChart.
+ */
+import { LineChart } from '@tetherto/mdk-react-devkit'
+
+const NOW = Date.now()
+const MIN = 60 * 1000
+
+const points = Array.from({ length: 90 }, (_, i) => ({
+  x: NOW - (90 - i) * MIN,
+  y: 50 + Math.sin(i / 8) * 6 + Math.random() * 1.2,
+}))
+
+const data = {
+  datasets: [
+    {
+      label: 'Hashrate',
+      borderColor: '#4f9ef5',
+      borderWidth: 2,
+      data: points,
+    },
+  ],
+}
+
+export const LineChartExample = () => {
+  return <LineChart data={data} height={320} unit="TH/s" />
+}

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

@@ -0,0 +1,29 @@
+$_prefix: mdk-lw-line-chart;
+
+.#{$_prefix}-wrapper {
+  width: 100%;
+  min-width: 0;
+
+  &-outer {
+    position: relative;
+  }
+
+  .#{$_prefix}-tooltip {
+    min-width: 270px;
+    position: absolute;
+    background: var(--mdk-color-dark-black);
+    color: var(--mdk-color-light-grey);
+    font-size: 12px;
+    font-weight: normal;
+    padding: 13px;
+    border-top-left-radius: 16px;
+    pointer-events: none;
+    top: 0;
+    left: 0;
+    z-index: 10;
+
+    &--no-min-width {
+      min-width: 'unset';
+    }
+  }
+}

package/src/primitives/components/list-view-filter/USAGE.md

@@ -0,0 +1,58 @@
+# `ListViewFilter`
+
+A filter button that opens a popover containing a multi-select `Cascader`. Displays an active filter count badge on the button.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `onChange` | Required | `(selections: CascaderValue[]) => void` | - | Callback when filters change |
+| `options` | Required | `CascaderOption[]` | - | Cascader options for filtering |
+| `className` | Optional | `string` | - | Custom className for the filter button |
+| `filterKey` | Optional | `string` | `"default"` | Optional key to force re-mounting the Cascader when filters change Useful if you want to reset the internal state of the Cascader when filters change |
+| `localFilters` | Optional | `LocalFilters` | - | Current filter values as key-value pairs Example: { type: 'Antminer S19XP H', status: ['active', 'pending'] } |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { ListViewFilter } from "@tetherto/mdk-react-devkit"
+import type { CascaderValue } from "@tetherto/mdk-react-devkit"
+
+const filterOptions = [
+  {
+    value: "type",
+    label: "Type",
+    children: [
+      { value: "Antminer S19XP", label: "Antminer S19XP" },
+      { value: "Avalon A1346", label: "Avalon A1346" },
+    ],
+  },
+  {
+    value: "status",
+    label: "Status",
+    children: [
+      { value: "active", label: "Active" },
+      { value: "offline", label: "Offline" },
+    ],
+  },
+]
+
+const [filters, setFilters] = useState<LocalFilters>({})
+
+const handleChange = (selections: CascaderValue[]) => {
+  // Convert to LocalFilters format for your state
+}
+
+<ListViewFilter
+  options={filterOptions}
+  localFilters={filters}
+  onChange={handleChange}
+/>
+```
+
+## Notes
+
+- `ListViewFilter` always operates in `multiple` mode on the underlying `Cascader`
+- The badge count reflects the number of currently active filter selections. It is hidden when count is 0.

package/src/primitives/components/list-view-filter/list-view-filter.example.tsx

@@ -0,0 +1,80 @@
+/**
+ * Runnable example for ListViewFilter.
+ */
+import { useState } from 'react'
+import { ListViewFilter } from '@tetherto/mdk-react-devkit'
+import type { CascaderValue, LocalFilters } from '@tetherto/mdk-react-devkit'
+
+const FILTER_OPTIONS = [
+  {
+    value: 'type',
+    label: 'Type',
+    children: [
+      { value: 'Antminer S19XP', label: 'Antminer S19XP' },
+      { value: 'Avalon A1346', label: 'Avalon A1346' },
+      { value: 'Whatsminer M50', label: 'Whatsminer M50' },
+    ],
+  },
+  {
+    value: 'status',
+    label: 'Status',
+    children: [
+      { value: 'active', label: 'Active' },
+      { value: 'offline', label: 'Offline' },
+      { value: 'sleeping', label: 'Sleeping' },
+    ],
+  },
+  {
+    value: 'location',
+    label: 'Location',
+    children: [
+      { value: 'row-a', label: 'Row A' },
+      { value: 'row-b', label: 'Row B' },
+    ],
+  },
+]
+
+function selectionToFilters(selections: CascaderValue[]): LocalFilters {
+  const result: Record<string, string[]> = {}
+  for (const [key, value] of selections as [string, string][]) {
+    if (!result[key]) result[key] = []
+    result[key].push(value)
+  }
+  return result
+}
+
+export const ListViewFilterExample = () => {
+  const [filters, setFilters] = useState<LocalFilters>({})
+
+  const handleChange = (selections: CascaderValue[]) => {
+    setFilters(selectionToFilters(selections))
+  }
+
+  let activeCount = 0
+  for (const v of Object.values(filters)) {
+    activeCount += Array.isArray(v) ? (v as unknown[]).length : 1
+  }
+
+  return (
+    <div className="mdk-example-row" style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        <ListViewFilter options={FILTER_OPTIONS} localFilters={filters} onChange={handleChange} />
+        <span style={{ fontSize: 13, color: 'var(--mdk-color-text-secondary, #888)' }}>
+          {activeCount > 0 ? `${activeCount} filter(s) active` : 'No filters active'}
+        </span>
+      </div>
+
+      {/* Pre-seeded with one filter */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        <ListViewFilter
+          options={FILTER_OPTIONS}
+          localFilters={{ status: ['active'] }}
+          onChange={() => undefined}
+        />
+        <span style={{ fontSize: 13, color: 'var(--mdk-color-text-secondary, #888)' }}>
+          Pre-seeded: status=active
+        </span>
+      </div>
+    </div>
+  )
+}

package/src/primitives/components/list-view-filter/styles.scss

@@ -0,0 +1,54 @@
+@use '../../styles/mixins' as *;
+.mdk-list-view-filter {
+  position: relative;
+  display: inline-block;
+
+  &__trigger {
+    @include inline_flex_align;
+
+    position: relative;
+
+    .mdk-button {
+      transition:
+        color,
+        border-color 200ms ease;
+
+      &:hover {
+        color: var(--mdk-color-primary-hover-light);
+        border-color: var(--mdk-color-primary-hover-light);
+      }
+
+      &__label {
+        gap: 8px;
+        padding: 0 15px;
+      }
+    }
+  }
+
+  &__dropdown {
+    padding: 0;
+    background-color: var(--mdk-color-obsidian);
+    border: unset;
+  }
+
+  &__header {
+    padding: 12px;
+    background-color: var(--mdk-color-obsidian);
+  }
+
+  &__content {
+    padding: 0;
+  }
+
+  .mdk-cascader {
+    border: none;
+    background: transparent;
+    &__panels {
+      border: none;
+    }
+
+    .mdk-tag-input__wrapper {
+      width: 100%;
+    }
+  }
+}

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

@@ -0,0 +1,41 @@
+# Loader
+
+A pulsing dots loading animation. Use it as an inline loading indicator or inside chart/card overlay slots.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `className` | Optional | `string` | - | Custom className for the root element |
+| `color` | Optional | `"red" \| "gray" \| "blue" \| "amber" \| "orange"` | `"orange"` | Color variant of the loader |
+| `count` | Optional | `3 \| 5 \| 7` | `5` | Number of dots to display |
+| `inline` | Optional | `boolean` | `false` | Render as an inline activity indicator instead of a block loading state. The default reserves a fixed 200px so a panel standing in for absent content does not collapse and then jump. Inline, that height is wrong: it strands the dots ~100px below the thing they belong to and centers them against surrounding text, which reads as frozen |
+| `size` | Optional | `number` | `10` | Size of each dot in pixels |
+<!-- END GENERATED: props -->
+
+## Block or inline — pick deliberately
+
+The default is a **block** loading state: a fixed 200px tall box with the dots centered, so a
+panel standing in for content that has not arrived does not collapse and then jump when it
+does. That is what every `isLoading ? <Loader /> : …` call site wants.
+
+**Pass `inline` for an indicator inside a flow of content** — a chat transcript, a row, next to
+a label. Without it the 200px applies there too, stranding the dots ~100px below the thing they
+belong to and centring them against left-aligned text, which reads as a frozen UI rather than a
+working one.
+
+## Example
+
+```tsx
+import { Loader } from "@tetherto/mdk-react-devkit"
+
+// Block: standing in for content that has not arrived
+<Loader />
+
+// Smaller with fewer dots
+<Loader size={8} count={3} color="blue" />
+
+// Inline: something is happening, in place
+<Loader inline size={6} count={3} />
+```

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

@@ -0,0 +1,20 @@
+/**
+ * Runnable example for Loader.
+ */
+import { Loader } from '@tetherto/mdk-react-devkit'
+
+export const LoaderExample = () => (
+  <div className="mdk-example-col">
+    <div className="mdk-example-row">
+      <Loader />
+      <Loader color="blue" />
+      <Loader color="gray" />
+    </div>
+
+    <div className="mdk-example-row">
+      <Loader count={3} size={8} color="orange" />
+      <Loader count={5} size={10} color="amber" />
+      <Loader count={7} size={12} color="red" />
+    </div>
+  </div>
+)

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

@@ -0,0 +1,67 @@
+@use '../../styles/mixins' as *;
+
+/* Loader container.
+ *
+ * The 200px is a *block* loading state: it reserves the space the content will occupy so a
+ * panel does not collapse and then jump when data lands. Every `isLoading ? <Loader/>` call
+ * site depends on it, which is why it stays the default. */
+.mdk-loader {
+  @include flex_center;
+  height: 200px;
+}
+
+/* Inline: an activity indicator sitting in a flow of content, not standing in for it.
+ *
+ * The block height is actively wrong here. Centring 8px dots inside 200px puts them ~100px
+ * below whatever they belong to, with dead space between — which reads as a frozen UI rather
+ * than a working one. Seen in the agent transcript, where the dots landed 103px under the
+ * speaker label and horizontally centered against left-aligned messages. */
+.mdk-loader--inline {
+  @include flex_center_justify_start;
+
+  height: auto;
+}
+
+/* Dot element */
+.mdk-loader__dot {
+  display: inline-block;
+  transform: scale(2);
+  animation: mdk-loader-pulse 1s linear infinite;
+}
+
+/* Color variants - inactive state */
+.mdk-loader__dot--orange {
+  --active-color: var(--mdk-color-primary);
+  background-color: rgb(var(--mdk-color-soft-apricot));
+}
+
+.mdk-loader__dot--red {
+  background-color: rgb(var(--mdk-color-soft-red));
+  --active-color: rgb(var(--mdk-color-error));
+}
+
+.mdk-loader__dot--gray {
+  background-color: rgb(var(--mdk-color-soft-gray));
+  --active-color: rgb(var(--mdk-color-grey-idle));
+}
+
+.mdk-loader__dot--blue {
+  background-color: rgb(var(--mdk-color-soft-blue));
+  --active-color: rgb(var(--mdk-color-sleep-blue));
+}
+
+/* `amber` is offered by LoaderProps and was the one variant with no rule, so it rendered a
+ * dot with no background at all — an invisible loader, the same class of bug as the inline
+ * height above. */
+.mdk-loader__dot--amber {
+  background-color: rgb(var(--mdk-color-soft-amber));
+  --active-color: var(--mdk-color-warning);
+}
+
+/* Pulse animation */
+@keyframes mdk-loader-pulse {
+  50% {
+    background-color: var(--active-color);
+    transform: scale(1);
+  }
+}

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

@@ -0,0 +1,103 @@
+# Logs
+
+A set of components for displaying paginated incident and activity log lists inside a labeled card.
+
+<!-- BEGIN GENERATED: props — do not edit; npm run generate:usage-proptables (source: component JSDoc/types via registry.json) -->
+## Props
+
+### `LogActivityIcon` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `status` | Required | `string` | - | - |
+
+### `LogDot` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `status` | Required | `string` | - | Severity string for color mapping |
+| `type` | Required | `string` | - | `'Incidents'` renders a colored circle; `'Activity'` renders an activity icon |
+
+### `LogItem` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `data` | Required | `LogData` | - | - |
+| `onLogClicked` | Optional | `((uuid: string) => void)` | - | - |
+
+### `LogRow` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `log` | Required | `LogData` | - | Log entry data |
+| `type` | Required | `string` | - | Log type (controls dot appearance) |
+| `onLogClicked` | Optional | `((uuid: string) => void)` | - | Click handler |
+| `style` | Optional | `React.CSSProperties` | - | Inline style for the row container |
+
+### `LogsCard` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `emptyMessage` | Optional | `string` | `"No active incidents"` | Message shown when `logsData` is empty |
+| `isDark` | Optional | `boolean` | `false` | Applies dark card theme |
+| `isLoading` | Optional | `boolean` | `false` | Shows skeleton rows while loading |
+| `label` | Optional | `string` | - | Card header label |
+| `logsData` | Optional | `LogData[]` | `[]` | Array of log entries to display |
+| `onLogClicked` | Optional | `(uuid: string) => void` | - | Fired with the log UUID when a row is clicked |
+| `pagination` | Optional | `LogPagination` | - | Pagination config; hides pagination when on page 1 or data is empty |
+| `skeletonRows` | Optional | `number` | `4` | Number of skeleton rows shown during loading |
+| `type` | Optional | `string` | - | Log type (`'Incidents'` or `'Activity'`); controls the `LogDot` appearance |
+
+### `LogData`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `body` | Required | `string` | - | Body text; `\|`-separated values are split into separate lines |
+| `status` | Required | `string` | - | Severity / status string (`'Critical'`, `'High'`, `'Medium'`, activity status, etc.) |
+| `subtitle` | Required | `string` | - | Secondary text (truncated with `title` tooltip) |
+| `title` | Required | `string` | - | Primary text |
+| `uuid` | Required | `string` | - | Unique identifier |
+
+### `LogPagination`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `current` | Required | `number` | - | Current page number |
+| `handlePaginationChange` | Required | `(page: number) => void` | - | Fired when the user changes the page |
+| `pageSize` | Required | `number` | - | Items per page |
+| `total` | Required | `number` | - | Total number of items |
+<!-- END GENERATED: props -->
+
+## Exports
+
+| Name | Description |
+| ---- | ----------- |
+| `LogsCard` | High-level card containing a list of `LogRow` items, skeleton loading state, empty state, and optional pagination |
+| `LogRow` | A single log entry row (status dot + item content) |
+| `LogItem` | The content area of a log entry (title, subtitle, body, and optional navigate arrow) |
+| `LogDot` | Status indicator dot rendered to the left of a `LogItem` — appearance varies by `type` |
+
+## Example
+
+```tsx
+import { LogsCard } from "@tetherto/mdk-react-devkit"
+
+<LogsCard
+  label="Recent Incidents"
+  type="Incidents"
+  logsData={incidents}
+  isLoading={loading}
+  onLogClicked={(uuid) => navigate(`/incidents/${uuid}`)}
+  pagination={{
+    current: page,
+    total: totalCount,
+    pageSize: 10,
+    handlePaginationChange: setPage,
+  }}
+/>
+```
+
+## Notes
+
+- `LOG_TYPES` constants (`'Incidents'`, `'Activity'`) are exported from [`constants.tsx`](./constants.tsx)
+- Severity colors map `'Critical'` → red, `'High'` → high-severity style, `'Medium'` → medium-severity style