@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

package/src/domain/components/active-incidents-card/active-incidents-card.example.tsx

@@ -0,0 +1,41 @@
+/**
+ * Runnable example for ActiveIncidentsCard.
+ */
+import { ActiveIncidentsCard, type TIncidentRowProps } from '@tetherto/mdk-react-devkit'
+
+const mockItems: TIncidentRowProps[] = [
+  {
+    id: '1',
+    severity: 'critical',
+    title: 'Miner 0xA1 offline',
+    body: 'No telemetry received in 2 min.',
+    subtitle: '2 min ago',
+  },
+  {
+    id: '2',
+    severity: 'high',
+    title: 'Container 03 temp >78°C',
+    body: 'Sustained above warning threshold.',
+    subtitle: '12 min ago',
+  },
+  {
+    id: '3',
+    severity: 'medium',
+    title: 'Pool latency elevated',
+    body: 'Round-trip 220ms (baseline 80ms).',
+    subtitle: '1 h ago',
+  },
+]
+
+export const ActiveIncidentsCardExample = () => {
+  return (
+    <ActiveIncidentsCard
+      label="Active Alerts"
+      items={mockItems}
+      onItemClick={(id) => {
+        // oxlint-disable-next-line no-console
+        console.log(`open alert ${id}`)
+      }}
+    />
+  )
+}

package/src/domain/components/active-incidents-card/styles.scss

@@ -0,0 +1,152 @@
+@use '@primitives/styles/mixins' as *;
+
+$_prefix: 'mdk-active-incidents-card';
+
+.#{$_prefix} {
+  @include flex_column;
+
+  margin: 0;
+  border-radius: 0;
+  padding: 10px 5px;
+  box-sizing: border-box;
+  background-color: var(--mdk-color-surface);
+  border: 1px solid var(--mdk-dialog-border-color);
+
+  &__header {
+    padding: 5px;
+    padding-left: 10px;
+    border-bottom: 1px solid var(--mdk-dialog-border-color);
+  }
+
+  &__label {
+    font-size: 16px;
+    font-weight: 400;
+    line-height: 22px;
+    font-style: normal;
+    text-transform: uppercase;
+    color: var(--mdk-color-white);
+  }
+
+  &__list {
+    height: 100%;
+    overflow-y: auto;
+    max-height: 450px;
+    padding: 15px 10px;
+    padding-bottom: 10px;
+
+    &::-webkit-scrollbar {
+      width: 4px;
+      background-color: transparent;
+    }
+
+    &::-webkit-scrollbar-track {
+      background-color: var(--mdk-color-background-dark);
+    }
+
+    &::-webkit-scrollbar-thumb {
+      background-color: var(--mdk-color-primary);
+      border-radius: 3px;
+
+      &:hover {
+        background-color: var(--mdk-color-primary-hover);
+      }
+    }
+  }
+
+  &__virtual-spacer {
+    position: relative;
+    width: 100%;
+  }
+
+  &__virtual-row {
+    position: absolute;
+    inset-inline: 0;
+    top: 0;
+  }
+
+  &__row {
+    @include flex_row_align_start;
+
+    &--clickable {
+      cursor: pointer;
+    }
+  }
+
+  &__row-content {
+    @include flex_row_align_start;
+
+    width: 100%;
+    cursor: pointer;
+  }
+
+  &__row-data {
+    @include flex_column;
+
+    flex: 1;
+    gap: 2px;
+  }
+
+  &__row-title {
+    font-size: 12px;
+    font-weight: 500;
+    color: var(--mdk-color-soft-gray);
+    font-family: 'JetBrains Mono', monospace, sans-serif;
+  }
+
+  &__row-subtitle {
+    font-size: 12px;
+    padding: 4px 0;
+    max-width: 100%;
+    color: var(--mdk-color-text-muted);
+  }
+
+  &__row-body {
+    font-size: 12px;
+    color: var(--mdk-color-text-muted-warm);
+  }
+
+  &__dot {
+    width: 12px;
+    height: 12px;
+    flex-shrink: 0;
+    margin-top: 4px;
+    border-radius: 50%;
+    margin-right: 12px;
+
+    &--critical {
+      background-color: var(--mdk-color-severity-critical);
+    }
+
+    &--high {
+      background-color: var(--mdk-color-severity-high);
+    }
+
+    &--medium {
+      background-color: var(--mdk-color-severity-medium);
+    }
+  }
+
+  &__arrow {
+    @include flex_center;
+
+    font-size: 28px;
+    padding-left: 16px;
+    color: var(--mdk-button-secondary-text);
+  }
+
+  &__empty {
+    @include flex_column_center;
+
+    padding: 20px;
+    font-size: 12px;
+    min-height: 190px;
+    color: var(--mdk-color-text-disabled);
+  }
+
+  &__skeleton-container {
+    @include flex_column;
+
+    gap: 14px;
+    padding: 10px;
+  }
+}

package/src/domain/components/alarm/USAGE.md

@@ -0,0 +1,52 @@
+# Alarm
+
+Mining-domain feedback components for rendering alarm timelines and alert details.
+
+## Components
+
+### `AlarmContents`
+
+Body region of an alarm card. Renders a scrollable list of `AlarmRow` entries from a `TimelineItemData` array, or an `EmptyState` when no data is present.
+
+#### Props detail
+
+| Prop         | Status   | Type / Options | Default | Description                  |
+| ------------ | -------- | ------------------------------- | ------- | ---------------------------- |
+| `alarmsData` | Required | `TimelineItemData[] \| unknown` | —       | Alert entries to render. Falls back to `EmptyState` when empty or falsy. |
+| `onNavigate` | Required | `(path: string) => void`        | —       | Navigation callback forwarded to each `AlarmRow` |
+
+### `AlarmRow`
+
+Single alarm-feed row with a severity dot, timestamp, source device label, and the alert message.
+
+#### Props detail
+
+| Prop         | Status   | Type / Options | Default | Description                                                      |
+| ------------ | -------- | ------------------------ | ------- | ---------------------------------------------------------------- |
+| `data`       | Required | `TimelineItemData`       | —       | The alarm entry to render                                        |
+| `onNavigate` | Required | `(path: string) => void` | —       | Called when the row is clicked (routes to the alarm detail page) |
+
+## Types
+
+```ts
+type AlarmItemData = {
+  title: string
+  subtitle: string
+  body: string        // pipe-separated segments rendered as separate lines
+  uuid?: string       // used for routing on click
+  status: string      // controls severity color and icon
+  [key: string]: unknown
+}
+
+type TimelineItemData = {
+  item: AlarmItemData
+  dot: ReactNode
+  children: ReactNode
+}
+```
+
+## Notes
+
+- Category: `feedback` | Domain: `mining-operations` | Capability: `incident-alerts` | Tier: `agent-ready`
+- Severity color is driven by `status` via `ALERT_COLOR_MAP` (defined in [`alarm-row-constants.tsx`](./alarm-row/alarm-row-constants.tsx))
+- `AlarmContents` renders a plain `ReactNode` fallback when `alarmsData` is not an array

package/src/domain/components/alarm/alarm-contents/USAGE.md

@@ -0,0 +1,32 @@
+# `AlarmContents`
+
+Renders the body region of an alarm card as a scrollable list of `AlarmRow` entries from a `TimelineItemData` array. Shows an `EmptyState` placeholder when the data is empty or falsy.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `alarmsData` | Required | `unknown` | - | Alert entries to render. Falls back to `EmptyState` when empty or falsy |
+| `onNavigate` | Required | `(path: string) => void` | - | Navigation callback forwarded to each `AlarmRow` for click-through routing |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { AlarmContents } from "@tetherto/mdk-react-devkit";
+
+const alarms = [
+  {
+    item: { title: "Miner offline", subtitle: "2 min ago", body: "No telemetry.", uuid: "a1", status: "critical" },
+    dot: null,
+    children: null,
+  },
+];
+
+<AlarmContents alarmsData={alarms} onNavigate={(path) => console.log(path)} />
+```
+
+## Notes
+
+- Accepts non-array values via the `unknown` union type: these are rendered as a `ReactNode` fallback, enabling progressive disclosure patterns

package/src/domain/components/alarm/alarm-contents/alarm-contents.example.tsx

@@ -0,0 +1,37 @@
+import { AlarmContents } from '@tetherto/mdk-react-devkit'
+
+const mockAlarms = [
+  {
+    item: {
+      title: 'Miner 0xA1 offline',
+      subtitle: '2 min ago',
+      body: 'No telemetry received in 2 min.|Check network connection.',
+      uuid: 'alarm-001',
+      status: 'critical',
+    },
+    dot: null,
+    children: null,
+  },
+  {
+    item: {
+      title: 'Container 03 temp >78°C',
+      subtitle: '12 min ago',
+      body: 'Sustained above warning threshold.|Fan speed at maximum.',
+      uuid: 'alarm-002',
+      status: 'warning',
+    },
+    dot: null,
+    children: null,
+  },
+]
+
+export const AlarmContentsExample = () => (
+  <div className="mdk-example-row">
+    <AlarmContents
+      alarmsData={mockAlarms}
+      onNavigate={(path) => {
+        console.warn(`navigate to ${path}`)
+      }}
+    />
+  </div>
+)

package/src/domain/components/alarm/alarm-contents/alarm-contents.scss

@@ -0,0 +1,17 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-alarm-contents {
+  max-height: 250px;
+  overflow-x: hidden;
+
+  &__list {
+    @include flex_column;
+
+    max-height: 250px;
+    overflow-y: auto;
+  }
+
+  &__fallback {
+    width: 100%;
+  }
+}

package/src/domain/components/alarm/alarm-row/USAGE.md

@@ -0,0 +1,45 @@
+# `AlarmRow`
+
+Single alarm-feed row with a severity dot, timestamp, source device label, and the alert message body. Clicking the row triggers `onNavigate` to route to the alarm detail page.
+
+<!-- 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 | `TimelineItemData` | - | The alarm entry to render |
+| `onNavigate` | Required | `(path: string) => void` | - | Called when the row is clicked; receives the alarm `uuid` as the path segment |
+
+### `TimelineItemData`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `children` | Required | `React.ReactNode` | - | Prebuilt `LogItem` node, built by the caller; not rendered by `AlarmRow` |
+| `dot` | Required | `React.ReactNode` | - | Timeline marker (e.g. `LogDot`), built by the caller; not rendered by `AlarmRow` |
+| `item` | Required | `AlarmItemData` | - | The alarm rendered by the row: `title`, `subtitle`, `body` (split on `\|` into lines), `status` (`Critical`, `High` or `Medium` sets the color and icon) and `uuid` (click target `/alerts/<uuid>`) |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { AlarmRow } from "@tetherto/mdk-react-devkit";
+
+const alarm = {
+  item: {
+    title: "Miner offline",
+    subtitle: "2 min ago",
+    body: "No telemetry received.|Check network.",
+    uuid: "a1",
+    status: "critical",
+  },
+  dot: null,
+  children: null,
+};
+
+<AlarmRow data={alarm} onNavigate={(path) => console.log(path)} />
+```
+
+## Notes
+
+- Severity color is driven by `item.status` via `ALERT_COLOR_MAP`; supported values match the alert severity palette (`critical`, `warning`, `info`, etc.)
+- The `body` string is split on `|` and each segment is rendered as a separate line

package/src/domain/components/alarm/alarm-row/alarm-row.example.tsx

@@ -0,0 +1,24 @@
+import { AlarmRow } from '@tetherto/mdk-react-devkit'
+
+const mockAlarm = {
+  item: {
+    title: 'Container 03 temp >78°C',
+    subtitle: '12 min ago',
+    body: 'Sustained above warning threshold.|Fan speed at maximum.',
+    uuid: 'alarm-002',
+    status: 'warning',
+  },
+  dot: null,
+  children: null,
+}
+
+export const AlarmRowExample = () => (
+  <div className="mdk-example-row">
+    <AlarmRow
+      data={mockAlarm}
+      onNavigate={(path) => {
+        console.warn(`navigate to ${path}`)
+      }}
+    />
+  </div>
+)

package/src/domain/components/alarm/alarm-row/alarm-row.scss

@@ -0,0 +1,74 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-alarm-row {
+  box-sizing: border-box;
+  padding-right: 8px;
+
+  &:not(:last-child) {
+    padding-bottom: 8px;
+  }
+
+  &__container {
+    @include flex_column;
+
+    gap: 8px;
+    padding: 10px;
+    border: 1px solid var(--mdk-alarm-color);
+    cursor: pointer;
+    background-color: color-mix(in srgb, var(--mdk-alarm-color, transparent) 10%, transparent);
+    border-color: color-mix(
+      in srgb,
+      var(--mdk-alarm-color, var(--mdk-color-white)) 20%,
+      transparent
+    );
+  }
+
+  &__title-row {
+    @include flex_align;
+
+    gap: 8px;
+  }
+
+  &__title {
+    font-size: 16px;
+    line-height: 16px;
+    word-break: break-word;
+    color: var(--mdk-alarm-color, var(--mdk-color-white));
+  }
+
+  &__subtitle {
+    font-size: 14px;
+    color: var(--mdk-color-text-disabled);
+  }
+
+  &__body {
+    font-size: 12px;
+    color: var(--mdk-color-white-alpha-04);
+  }
+
+  &__icon {
+    @include inline_flex_align;
+
+    justify-content: center;
+    color: var(--mdk-alarm-color, var(--mdk-color-white));
+
+    &--critical {
+      height: 14px;
+      width: 14px;
+    }
+
+    &--high {
+      &::before {
+        content: '!';
+        font-weight: bold;
+      }
+    }
+
+    &--dot {
+      border-radius: 50%;
+      width: 10px;
+      height: 10px;
+      flex-shrink: 0;
+    }
+  }
+}

package/src/domain/components/alarm/alarm.example.tsx

@@ -0,0 +1,52 @@
+/**
+ * Runnable example for AlarmContents and AlarmRow.
+ */
+import { AlarmContents } from '@tetherto/mdk-react-devkit'
+
+const mockAlarms = [
+  {
+    item: {
+      title: 'Miner 0xA1 offline',
+      subtitle: '2 min ago',
+      body: 'No telemetry received in 2 min.|Check network connection.',
+      uuid: 'alarm-001',
+      status: 'critical',
+    },
+    dot: null,
+    children: null,
+  },
+  {
+    item: {
+      title: 'Container 03 temp >78°C',
+      subtitle: '12 min ago',
+      body: 'Sustained above warning threshold.|Fan speed at maximum.',
+      uuid: 'alarm-002',
+      status: 'warning',
+    },
+    dot: null,
+    children: null,
+  },
+  {
+    item: {
+      title: 'Pool latency elevated',
+      subtitle: '1 h ago',
+      body: 'Round-trip 220ms (baseline 80ms).',
+      uuid: 'alarm-003',
+      status: 'info',
+    },
+    dot: null,
+    children: null,
+  },
+]
+
+export const AlarmExample = () => (
+  <div className="mdk-example-row">
+    <AlarmContents
+      alarmsData={mockAlarms}
+      onNavigate={(path) => {
+        // oxlint-disable-next-line no-console
+        console.log(`navigate to ${path}`)
+      }}
+    />
+  </div>
+)

package/src/domain/components/alerts/USAGE.md

@@ -0,0 +1,37 @@
+# `AlertsTable` family — `CurrentAlerts` and `HistoricalAlerts`
+
+The MDK doesn't ship a single "AlertsTable" component. The agent-first design
+document uses the name as a category — there are two concrete components:
+
+- `CurrentAlerts` — sortable, searchable data table of currently active alerts
+  derived from a raw `Device[]` payload. Plays an audible beep when a
+  critical alert is present (gated by user confirmation).
+- `HistoricalAlerts` — sortable data table of historical alerts within a
+  controlled date range, with an embedded `DateRangePicker`
+
+Both render a `DataTable` with shared columns from [`alerts-table-columns.tsx`](./alerts-table-columns.tsx).
+
+## Minimal example
+
+```tsx
+<HistoricalAlerts
+  alerts={alerts}
+  localFilters={localFilters}
+  filterTags={filterTags}
+  dateRange={range}
+  onDateRangeChange={setRange}
+/>
+```
+
+## Data contracts
+
+- `AlertRecord` — `@tetherto/mdk-react-devkit` / [`domain/types/alerts`](../../types/alerts.ts)
+- `AlertLocalFilters` — same package, [`domain/alerts/alerts-types`](./alerts-types.ts)
+- `Device` — [`foundation/types/device`](../../types/device.ts)
+
+## Notes
+
+- Both components call `useTimezoneFormatter` from
+  `@tetherto/mdk-react-adapter`; wrap your app in `<MdkProvider>` so the
+  timezone store is reachable
+- The columns are shared, so `getRowId` returns the alert's `uuid` in both

package/src/domain/components/alerts/alerts-panel.scss

@@ -0,0 +1,36 @@
+/* Current + Historical sections render as bordered cards:
+ * title, filters, and the table all live inside one panel.
+ *
+ * Kept as a plain block (not flex): the inner DataTable owns its own
+ * horizontal scroll via `overflow-x` on its content section, and a flex
+ * context would stretch it to content width instead of letting it scroll.
+ * `min-width: 0` lets the card shrink inside the flex page column. */
+.mdk-alerts-current,
+.mdk-alerts-historical {
+  min-width: 0;
+  padding: 20px 24px;
+  background: var(--mdk-color-surface-elevated, #191714);
+  border: 1px solid var(--mdk-table-border, #ffffff1a);
+
+  /* The alerts tables are wide (≈1440px of columns). Keep them horizontally
+   * scrollable even in the empty / loading state — the DataTable otherwise
+   * sets `overflow-x: hidden` when there are no rows, which clips the
+   * trailing columns (Severity → Created → Actions) and makes them
+   * unreachable. */
+  .mdk-table__content-section--no-overflow {
+    overflow-x: auto;
+  }
+
+  /* Scrollbar thumb in the primary colour. */
+  .mdk-table__content-section {
+    &::-webkit-scrollbar-thumb {
+      background-color: var(--mdk-color-primary);
+    }
+  }
+
+  /* The default empty-state icon is 128px — too large inside the card. */
+  .mdk-table__empty-body svg {
+    width: 64px;
+    height: 64px;
+  }
+}

package/src/domain/components/alerts/alerts-table-columns.scss

@@ -0,0 +1,13 @@
+/**
+ * Alerts table cell styles — when a search chip matched only hidden tokens
+ * (uuid, ip-/mac-/sn-/firmware- tags) the "matched on" hint surfaces as a
+ * tooltip on the device code; the dotted underline marks the affordance.
+ */
+
+@layer mdk {
+  .mdk-alerts-code-cell--matched {
+    cursor: help;
+    text-decoration: underline dotted;
+    text-underline-offset: 3px;
+  }
+}

package/src/domain/components/alerts/alerts-table-title/USAGE.md

@@ -0,0 +1,21 @@
+# `AlertsTableTitle`
+
+Title strip for an alerts table section with a heading and an optional count badge.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `title` | Required | `React.ReactNode` | - | Section heading |
+| `className` | Optional | `string` | - | Additional CSS class |
+| `subtitle` | Optional | `React.ReactNode` | - | Optional subtitle or count badge |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { AlertsTableTitle } from "@tetherto/mdk-react-devkit";
+
+<AlertsTableTitle title="Active Alerts" subtitle="12 total" />
+```

package/src/domain/components/alerts/alerts-table-title/alerts-table-title.example.tsx

@@ -0,0 +1,8 @@
+import { AlertsTableTitle } from '@tetherto/mdk-react-devkit'
+
+export const AlertsTableTitleExample = () => (
+  <div className="mdk-example-row">
+    <AlertsTableTitle title="Active Alerts" subtitle="12 total" />
+    <AlertsTableTitle title="History" />
+  </div>
+)

package/src/domain/components/alerts/alerts-table-title/alerts-table-title.scss

@@ -0,0 +1,16 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-alerts-table-title {
+  @include flex_column;
+
+  gap: 10px;
+
+  &__title {
+    font-size: 16px;
+    font-weight: 600;
+  }
+
+  &__subtitle {
+    width: 100%;
+  }
+}