@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

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

@@ -0,0 +1,52 @@
+# `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).
+
+> Sibling component: [`HistoricalAlerts`](../historical-alerts/USAGE.md).
+> Both render the same `DataTable` columns from [`alerts-table-columns.tsx`](../alerts-table-columns.tsx).
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `filterTags` | Required | `string[]` | - | Search tags (controlled) |
+| `localFilters` | Required | `AlertLocalFilters` | - | Filters controlled outside (typically by URL severity param) |
+| `onFilterTagsChange` | Required | `(tags: string[]) => void` | - | Setter for the tags above |
+| `onLocalFiltersChange` | Required | `(filters: AlertLocalFilters) => void` | - | Setter for the filters above |
+| `className` | Optional | `string` | - | Additional class names |
+| `devices` | Optional | `Device[]` | - | Devices carrying alerts (`last.alerts`), as a flat list. Unwrapping any backend envelope is the data layer's job, not this component's |
+| `isDemoMode` | Optional | `boolean` | `false` | Skip sound entirely (e.g. in demo/preview environments), including the one-time "sound notifications" confirmation modal |
+| `isLoading` | Optional | `boolean` | `false` | Show DataTable loading overlay |
+| `isSoundEnabled` | Optional | `boolean` | `false` | Whether sound notifications are enabled in user preferences (e.g. theme slice) |
+| `onAlertClick` | Optional | `((id?: string \| undefined, uuid?: string \| undefined) => void)` | - | Click handler when the user opens an alert (right arrow icon in the row) |
+| `selectedAlertId` | Optional | `string` | - | Optional id used to focus on a single alert (deep-link from URL) |
+| `typeFiltersForSite` | Optional | `CascaderOption[]` | - | Optional site-specific overrides for the type filter |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+<CurrentAlerts
+  devices={devices}
+  localFilters={localFilters}
+  onLocalFiltersChange={setLocalFilters}
+  filterTags={tags}
+  onFilterTagsChange={setTags}
+  onAlertClick={(id) => openDetail(id)}
+/>
+```
+
+## Data contracts
+
+- `AlertRecord` — `@tetherto/mdk-react-devkit` / [`domain/types/alerts`](../../../types/alerts.ts)
+- `AlertLocalFilters` — same package, [`foundation/components/alerts/alerts-types`](../alerts-types.ts)
+- `Device` — [`foundation/types/device`](../../../types/device.ts)
+
+## Notes
+
+- Calls `useTimezoneFormatter` from `@tetherto/mdk-react-adapter`; wrap your
+  app in `<MdkProvider>` so the timezone store is reachable
+- `getRowId` returns the alert `uuid`

package/src/domain/components/alerts/current-alerts/alert-confirmation-modal/USAGE.md

@@ -0,0 +1,23 @@
+# `AlertConfirmationModal`
+
+Confirmation dialog that appears before acknowledging or clearing one or more alerts. Prevents accidental bulk-clear actions.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `isOpen` | Required | `boolean` | - | Controls dialog visibility |
+| `onOk` | Required | `VoidFunction` | - | Called when the user confirms the action |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { AlertConfirmationModal } from "@tetherto/mdk-react-devkit";
+
+<AlertConfirmationModal
+  isOpen={isOpen}
+  onOk={() => { clearAlerts(); setIsOpen(false); }}
+/>
+```

package/src/domain/components/alerts/current-alerts/alert-confirmation-modal/alert-confirmation-modal.example.tsx

@@ -0,0 +1,18 @@
+import { useState } from 'react'
+import { AlertConfirmationModal } from '@tetherto/mdk-react-devkit'
+
+export const AlertConfirmationModalExample = () => {
+  const [open, setOpen] = useState(false)
+  return (
+    <div className="mdk-example-row">
+      <button onClick={() => setOpen(true)}>Clear All Alerts</button>
+      <AlertConfirmationModal
+        isOpen={open}
+        onOk={() => {
+          console.warn('confirmed')
+          setOpen(false)
+        }}
+      />
+    </div>
+  )
+}

package/src/domain/components/alerts/current-alerts/alert-confirmation-modal/alert-confirmation-modal.scss

@@ -0,0 +1,14 @@
+.mdk-alerts-confirmation-modal {
+  max-width: 480px;
+
+  &__body {
+    padding: 16px 0;
+    line-height: 1.5;
+  }
+
+  &__footer {
+    display: flex;
+    justify-content: flex-end;
+    gap: 8px;
+  }
+}

package/src/domain/components/alerts/current-alerts/current-alerts.example.tsx

@@ -0,0 +1,50 @@
+/**
+ * Runnable example for CurrentAlerts.
+ */
+import { useState } from 'react'
+import { CurrentAlerts } from '@tetherto/mdk-react-devkit'
+
+// The component derives its rows from a raw `devices` payload (`device.last.alerts`).
+// We use `any` casts on the mock to avoid duplicating the long `Device` type here —
+// the production code expects a `Device[][]` from the Gateway API.
+const mockDevices = [
+  [
+    {
+      id: 'miner-A1',
+      last: {
+        alerts: [
+          {
+            id: '1',
+            uuid: 'alrt-1',
+            severity: 'critical',
+            name: 'miner_offline',
+            description: 'Miner 0xA1 has stopped reporting.',
+            code: '001',
+            createdAt: Date.now() - 2 * 60 * 1000,
+          },
+        ],
+      },
+    },
+  ],
+]
+
+export const CurrentAlertsExample = () => {
+  const [filterTags, setFilterTags] = useState<string[]>([])
+  const [localFilters, setLocalFilters] = useState({})
+
+  return (
+    <CurrentAlerts
+      devices={mockDevices as never}
+      isLoading={false}
+      localFilters={localFilters}
+      onLocalFiltersChange={setLocalFilters}
+      filterTags={filterTags}
+      onFilterTagsChange={setFilterTags}
+      onAlertClick={(id) => {
+        // oxlint-disable-next-line no-console
+        console.log(`open alert ${id}`)
+      }}
+      isDemoMode
+    />
+  )
+}

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

@@ -0,0 +1,52 @@
+# `HistoricalAlerts`
+
+Sortable data table of historical alerts within a controlled date range, with
+an embedded `DateRangePicker`.
+
+> Sibling component: [`CurrentAlerts`](../current-alerts/USAGE.md). Both
+> render the same `DataTable` columns from [`alerts-table-columns.tsx`](../alerts-table-columns.tsx).
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `dateRange` | Required | `HistoricalAlertsRange` | - | Selected date range for the historical query (controlled) |
+| `filterTags` | Required | `string[]` | - | Shared with `CurrentAlerts` |
+| `localFilters` | Required | `AlertLocalFilters` | - | Filters and search tags coming from the parent (typically shared with `CurrentAlerts`) |
+| `onDateRangeChange` | Required | `(range: HistoricalAlertsRange) => void` | - | Setter for the date range |
+| `alerts` | Optional | `AlertRecord[]` | `[]` | Pre-fetched historical alerts log entries (each with a `thing` device payload) |
+| `className` | Optional | `string` | - | Additional class names |
+| `isLoading` | Optional | `boolean` | `false` | Show DataTable loading overlay |
+| `onAlertClick` | Optional | `((id?: string \| undefined, uuid?: string \| undefined) => void)` | - | Called when the user opens an alert |
+
+### `HistoricalAlertsRange`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `end` | Required | `number` | - | Range end, epoch ms; seeds the picker's `to` date |
+| `start` | Required | `number` | - | Range start, epoch ms; seeds the picker's `from` date |
+<!-- END GENERATED: props -->
+
+## 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, [`foundation/components/alerts/alerts-types`](../alerts-types.ts)
+
+## Notes
+
+- Calls `useTimezoneFormatter` from `@tetherto/mdk-react-adapter`; wrap your
+  app in `<MdkProvider>` so the timezone store is reachable
+- `getRowId` returns the alert `uuid`

package/src/domain/components/alerts/historical-alerts/historical-alerts.example.tsx

@@ -0,0 +1,54 @@
+/**
+ * Runnable example for HistoricalAlerts.
+ *
+ * Wrap the page in `<MdkProvider>` so the `useTimezoneFormatter` hook used by
+ * the table can read the timezone store.
+ */
+import { useState } from 'react'
+import type { AlertRecord } from '@tetherto/mdk-react-devkit'
+import { HistoricalAlerts } from '@tetherto/mdk-react-devkit'
+
+const NOW = Date.now()
+const DAY = 24 * 60 * 60 * 1000
+
+const mockAlerts: AlertRecord[] = [
+  {
+    id: '1',
+    uuid: 'alrt-1',
+    severity: 'critical',
+    name: 'miner_offline',
+    description: 'Miner 0xA1 has stopped reporting.',
+    code: '001',
+    createdAt: NOW - 2 * DAY,
+    thing: { id: 'miner-A1' },
+  },
+  {
+    id: '2',
+    uuid: 'alrt-2',
+    severity: 'warning',
+    name: 'temp_high',
+    description: 'Container 03 exceeded 78°C.',
+    code: '002',
+    createdAt: NOW - 5 * DAY,
+    thing: { id: 'container-03' },
+  },
+]
+
+export const HistoricalAlertsExample = () => {
+  const [range, setRange] = useState({ start: NOW - 7 * DAY, end: NOW })
+
+  return (
+    <HistoricalAlerts
+      alerts={mockAlerts}
+      isLoading={false}
+      localFilters={{}}
+      filterTags={[]}
+      dateRange={range}
+      onDateRangeChange={setRange}
+      onAlertClick={(id) => {
+        // oxlint-disable-next-line no-console
+        console.log(`open alert ${id}`)
+      }}
+    />
+  )
+}

package/src/domain/components/alerts/tag-filter-bar/USAGE.md

@@ -0,0 +1,30 @@
+# `TagFilterBar`
+
+Cascader-based filter bar for the alerts table. Lets operators filter by tags, alert type, severity, and other site-specific dimensions.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `filterTags` | Required | `string[]` | - | Active tag filter values |
+| `localFilters` | Required | `AlertLocalFilters` | - | Current local filter state |
+| `onLocalFiltersChange` | Required | `(filters: AlertLocalFilters) => void` | - | Called when any local filter changes |
+| `onSearchTagsChange` | Required | `(tags: string[]) => void` | - | Called when tag filter changes |
+| `className` | Optional | `string` | - | Additional CSS class |
+| `placeholder` | Optional | `string` | - | Search input placeholder |
+| `typeFiltersForSite` | Optional | `CascaderOption[]` | - | Site-specific overrides for the "type" filter children. If provided, the "Type" filter group will use these instead of the defaults |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+import { TagFilterBar } from "@tetherto/mdk-react-devkit";
+
+<TagFilterBar
+  filterTags={[]}
+  localFilters={{}}
+  onSearchTagsChange={(tags) => setTags(tags)}
+  onLocalFiltersChange={(f) => setFilters(f)}
+/>
+```

package/src/domain/components/alerts/tag-filter-bar/tag-filter-bar.example.tsx

@@ -0,0 +1,12 @@
+import { TagFilterBar } from '@tetherto/mdk-react-devkit'
+
+export const TagFilterBarExample = () => (
+  <div className="mdk-example-row">
+    <TagFilterBar
+      filterTags={[]}
+      localFilters={{} as never}
+      onSearchTagsChange={(tags) => console.warn('tags', tags)}
+      onLocalFiltersChange={(f) => console.warn('filters', f)}
+    />
+  </div>
+)

package/src/domain/components/alerts/tag-filter-bar/tag-filter-bar.scss

@@ -0,0 +1,20 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-alerts-tag-filter-bar {
+  @include flex_column;
+
+  flex: 1;
+  gap: 12px;
+  align-items: stretch;
+  margin-bottom: 20px;
+
+  @media (min-width: 900px) {
+    @include flex_row;
+    @include flex_align;
+  }
+
+  &__search {
+    flex: 1;
+    width: 100%;
+  }
+}

package/src/domain/components/auth/require-auth/USAGE.md

@@ -0,0 +1,47 @@
+# RequireAuth
+
+Route guard that reads the session token from the headless `authStore` (via
+`useAuth`) and renders children only when a token is present. Router-agnostic
+— pass any node (typically `<Navigate />`) as the `fallback`.
+
+Also exports `consumeLastVisitedPath()` so the sign-in page can return the
+user to wherever they were redirected from.
+
+<!-- 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` | Required | `React.ReactNode` | - | Rendered when a token is present |
+| `fallback` | Required | `React.ReactNode` | - | Rendered when no token is present — typically `<Navigate to="/signin" />` |
+| `rememberPath` | Optional | `boolean` | `true` | When true (default), the current location is persisted to sessionStorage before rendering the fallback so the sign-in flow can return there |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { Navigate, Route, Routes } from 'react-router'
+import { RequireAuth, consumeLastVisitedPath } from '@tetherto/mdk-react-devkit'
+
+const Router = () => (
+  <Routes>
+    <Route
+      path='/dashboard'
+      element={
+        <RequireAuth fallback={<Navigate to='/signin' replace />}>
+          <Dashboard />
+        </RequireAuth>
+      }
+    />
+  </Routes>
+)
+
+const SignIn = () => {
+  const token = useAuthToken()
+  if (token) {
+    const next = consumeLastVisitedPath() ?? '/dashboard'
+    return <Navigate to={next} replace />
+  }
+  return <SignInGoogleButton />
+}
+```

package/src/domain/components/auth/require-auth/require-auth.example.tsx

@@ -0,0 +1,16 @@
+/**
+ * Runnable example for RequireAuth.
+ *
+ * Wraps the application content in an auth guard. When `authStore.token` is
+ * null, renders the fallback (typically a `<Navigate />` to `/signin`).
+ */
+import { RequireAuth } from '@tetherto/mdk-react-devkit'
+
+const PretendDashboard = () => <div>Authenticated dashboard content</div>
+const PretendRedirect = () => <div>Redirecting to sign in…</div>
+
+export const RequireAuthExample = () => (
+  <RequireAuth fallback={<PretendRedirect />}>
+    <PretendDashboard />
+  </RequireAuth>
+)

package/src/domain/components/auth/sign-in-google-button/USAGE.md

@@ -0,0 +1,50 @@
+# SignInGoogleButton
+
+Single-button Google OAuth sign-in trigger. Defaults to a full-page redirect
+to `${oauthBaseUrl}/oauth/google`. The backend issues a JWT and redirects
+back with `?authToken=…`, which `useAuthToken` then persists into the
+session store.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `oauthBaseUrl` | Required | `string` | - | Base URL of the OAuth backend (no trailing slash). Click navigates to `${oauthBaseUrl}/oauth/google` |
+| `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 |
+| `label` | Optional | `string` | `"Sign in with Google"` | Override the visible button label |
+| `loading` | Optional | `boolean` | `false` | Show a spinner instead of the content and disable the button |
+| `onClick` | Optional | `(() => void)` | `redirect` | Override the click behaviour entirely. When set, `oauthBaseUrl` is ignored |
+| `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 -->
+
+## 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.
+
+| Prop           | Status   | Type / Options | Default | Description                            |
+| -------------- | -------- | ------------- | ------- | -------------------------------------- |
+| ...rest        | Optional | `ButtonProps` | —       | Forwarded to the underlying `<Button>` |
+
+## Example
+
+```tsx
+<SignInGoogleButton oauthBaseUrl={import.meta.env.VITE_OAUTH_BASE_URL} />
+```
+
+## Notes
+
+- Uses `window.location.href` (full-page navigation) rather than client-side
+  routing so the OAuth callback URL is treated as an external load
+- The backend side is an identity plugin you supply — MDK ships no OAuth
+  implementation. It serves the `/oauth/google` start endpoint this button
+  navigates to, and redirects back to the frontend with `?authToken=<jwt>`.
+  For local dev that is typically a callback of
+  `http://localhost:3000/oauth/google/callback` returning to
+  `http://localhost:3030`.

package/src/domain/components/auth/sign-in-google-button/sign-in-google-button.example.tsx

@@ -0,0 +1,11 @@
+/**
+ * Runnable example for SignInGoogleButton.
+ *
+ * Triggers a full-page redirect to the OAuth backend. In a real app you'd
+ * read `oauthBaseUrl` from `import.meta.env.VITE_OAUTH_BASE_URL`.
+ */
+import { SignInGoogleButton } from '@tetherto/mdk-react-devkit'
+
+export const SignInGoogleButtonExample = () => (
+  <SignInGoogleButton oauthBaseUrl="http://localhost:3000" />
+)

package/src/domain/components/composite/metric-card/USAGE.md

@@ -0,0 +1,36 @@
+# `MetricCard`
+
+Compact card displaying a labelled metric value with an optional unit suffix.
+Supports highlighted (orange accent) and transparent-color display states,
+making it suitable for pool-performance dashboards, financial summary rows, and
+inline KPI strips where visual weight needs to be controlled.
+
+<!-- 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` | Required | `string` | - | Text label shown above the value |
+| `unit` | Required | `string` | - | Unit suffix appended after the value (e.g. `"TH/s"`, `"W"`, `"USD"`) |
+| `value` | Required | `string \| number \| null` | - | Metric value to display |
+| `bgColor` | Optional | `string` | `BLACK_ALPHA_05` | Custom background color (CSS color string) |
+| `className` | Optional | `string` | - | Additional class names appended to the root element |
+| `isHighlighted` | Optional | `boolean` | `false` | Renders the value in orange to draw attention |
+| `isTransparentColor` | Optional | `boolean` | `false` | Renders the value in a low-opacity white for de-emphasized display |
+| `isValueMedium` | Optional | `boolean` | `false` | Applies a medium-weight variant to the value typography |
+| `noMinWidth` | Optional | `boolean` | `false` | Removes the default minimum width so the card shrinks to content |
+| `showDashForZero` | Optional | `boolean` | `false` | Displays `—` instead of `0` when value is zero |
+<!-- END GENERATED: props -->
+
+## Minimal example
+
+```tsx
+<MetricCard label="Hashrate" unit="TH/s" value={102.4} />
+```
+
+## Notes
+
+- When `value` is `null` the component renders the FALLBACK placeholder (`—`) from `@primitives`
+- `showDashForZero` and `null` values both render the same FALLBACK string
+- `isHighlighted` takes precedence over `isTransparentColor` for color resolution
+- The background color is applied via a `--mdk-metric-card-bg` CSS custom property, allowing it to be overridden at the `@layer app` level

package/src/domain/components/composite/metric-card/metric-card.example.tsx

@@ -0,0 +1,14 @@
+/**
+ * Runnable example for MetricCard.
+ */
+import { MetricCard } from '@tetherto/mdk-react-devkit'
+
+export const MetricCardExample = () => (
+  <div className="mdk-example-row">
+    <MetricCard label="Hashrate" unit="TH/s" value={102.4} />
+    <MetricCard label="Power" unit="W" value={3200} isHighlighted />
+    <MetricCard label="Efficiency" unit="J/TH" value={31.2} isValueMedium />
+    <MetricCard label="Revenue" unit="USD" value={0} showDashForZero />
+    <MetricCard label="Temperature" unit="°C" value={null} />
+  </div>
+)

package/src/domain/components/composite/metric-card/styles.scss

@@ -0,0 +1,35 @@
+@use '@primitives/styles/mixins' as *;
+
+.mdk-metric-card {
+  @include flex_column;
+
+  flex: 1;
+  padding: 20px;
+  min-width: 200px;
+  box-sizing: border-box;
+  background-color: var(--mdk-metric-card-bg);
+
+  &--no-min-width {
+    min-width: unset;
+  }
+
+  &__label {
+    margin-bottom: 8px;
+    font-size: 12px;
+    font-weight: 400;
+    line-height: normal;
+    color: var(--mdk-color-text-disabled);
+  }
+
+  &__value {
+    font-size: 25px;
+    font-weight: 700;
+    line-height: normal;
+    white-space: nowrap;
+    font-family: var(--font-mono);
+
+    &--medium {
+      font-size: 20px;
+    }
+  }
+}

package/src/domain/components/dashboard/dashboard-date-range-picker/USAGE.md

@@ -0,0 +1,43 @@
+# `DashboardDateRangePicker`
+
+Dashboard wrapper around the core `DateRangePicker`. It speaks
+`{ start, end }` epoch-millisecond timestamps, so a page can pass the range
+straight to its history queries without any `Date <-> number` plumbing.
+
+<!-- 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 | `(next: DashboardDateRange) => void` | - | Fires with the next `{ start, end }` window when the user applies a range |
+| `value` | Required | `DashboardDateRange` | - | Current range as `{ start, end }` epoch-millisecond timestamps |
+| `className` | Optional | `string` | - | Optional class hook |
+| `dateFormat` | Optional | `string` | `"dd/MM/yyyy"` | Display format. Defaults to `dd/MM/yyyy` |
+| `disabled` | Optional | `boolean` | `false` | Disable the trigger |
+
+### `DashboardDateRange`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `end` | Required | `number` | - | Window end, milliseconds since epoch |
+| `start` | Required | `number` | - | Window start, milliseconds since epoch |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { useState } from "react"
+import { DashboardDateRangePicker } from "@tetherto/mdk-react-devkit"
+
+const [range, setRange] = useState({ start: Date.now() - DAY_MS, end: Date.now() })
+
+<DashboardDateRangePicker value={range} onChange={setRange} />
+```
+
+## Notes
+
+- The wrapper ignores partial selections — `onChange` only fires once the
+  user has picked both `from` and `to` and clicked **Apply Range** in the
+  core picker
+- The popover, presets, and styling all come from the core
+  `DateRangePicker`. This wrapper exists only to adapt the value shape

package/src/domain/components/dashboard/dashboard-date-range-picker/dashboard-date-range-picker.example.tsx

@@ -0,0 +1,18 @@
+/**
+ * Runnable example for DashboardDateRangePicker.
+ *
+ * Demonstrates the `{ start, end }` epoch-millisecond shape the picker
+ * reads and emits. The page owns the range and passes it to its queries.
+ */
+import { DashboardDateRangePicker } from '@tetherto/mdk-react-devkit'
+import { useState } from 'react'
+
+export const DashboardDateRangePickerExample = () => {
+  const now = Date.now()
+  const [range, setRange] = useState({
+    start: now - 24 * 60 * 60 * 1000,
+    end: now,
+  })
+
+  return <DashboardDateRangePicker value={range} onChange={setRange} />
+}

package/src/domain/components/dashboard/dashboard-date-range-picker/dashboard-date-range-picker.scss

@@ -0,0 +1,31 @@
+@use "@primitives/styles/mixins" as *;
+
+@layer mdk {
+  /* The dashboard trigger needs a wider cap than the core default (245px)
+   * because formatted ranges like "May 20, 2026 - May 21, 2026" overflow
+   * at 245px. The compound selector outranks the bare core rule so this
+   * wins regardless of stylesheet load order. We also force the inner
+   * text span to shrink within the button so it ellipses instead of
+   * bleeding past the right border. */
+  .mdk-date-picker__trigger.mdk-dashboard-date-range-picker__trigger {
+    overflow: hidden;
+    min-width: 0;
+    max-width: min(20rem, calc(100% - 1rem));
+
+    .mdk-date-picker__text {
+      flex: 1 1 auto;
+      min-width: 0;
+      overflow: hidden;
+      white-space: nowrap;
+      text-overflow: ellipsis;
+    }
+  }
+
+  /* Cap the popover so it never overflows the viewport, even on narrow
+   * windows where Radix's avoidCollisions cannot fit a two-month grid. */
+  .mdk-popover__content.mdk-dashboard-date-range-picker__modal {
+    max-width: min(720px, calc(100vw - 2rem));
+    max-height: calc(100vh - 6rem);
+    overflow: auto;
+  }
+}