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

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

@@ -0,0 +1,165 @@
+# Form
+
+Form primitives built on react-hook-form. Use with a `useForm()` instance.
+
+<!-- BEGIN GENERATED: props — do not edit; npm run generate:usage-proptables (source: component JSDoc/types via registry.json) -->
+## Props
+
+### `Form` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `children` | Required | `React.ReactNode` | - | - |
+| `form` | Required | `UseFormReturn<TFieldValues>` | - | - |
+
+### `FormCascader` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `options` | Required | `CascaderOption[]` | - | - |
+| `cascaderProps` | Optional | `Omit<CascaderProps & React.RefAttributes<HTMLDivElement>, "onChange" \| "value" \| "options" \| "placeholder">` | - | - |
+| `description` | Optional | `string` | - | - |
+| `label` | Optional | `string` | - | - |
+| `multiple` | Optional | `boolean` | - | - |
+| `placeholder` | Optional | `string` | - | - |
+
+### `FormCheckbox` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `checkboxProps` | Optional | `({ checked?: CheckedState; defaultChecked?: CheckedState; disabled?: boolean; size?: CheckboxSize; color?: ComponentColor; radius?: BorderRadius; className?: string; indicatorClassName?: string; onCheckedChange?: ((checked: CheckedState) =>… /* see source */` | - | - |
+| `description` | Optional | `string` | - | - |
+| `label` | Optional | `string` | - | - |
+| `layout` | Optional | `"row" \| "column"` | - | - |
+| `placeholder` | Optional | `string` | - | - |
+
+### `FormDatePicker` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `datePickerProps` | Optional | `object` | - | - |
+| `description` | Optional | `string` | - | - |
+| `label` | Optional | `string` | - | - |
+| `placeholder` | Optional | `string` | - | - |
+
+### `FormInput` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `description` | Optional | `string` | - | - |
+| `inputProps` | Optional | `Omit<Omit<InputProps, "ref"> & React.RefAttributes<HTMLInputElement>, "type" \| "variant">` | - | - |
+| `label` | Optional | `string` | - | - |
+| `placeholder` | Optional | `string` | - | - |
+| `type` | Optional | `React.HTMLInputTypeAttribute` | - | - |
+| `variant` | Optional | `"search" \| "default"` | - | - |
+
+### `FormLabel` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `htmlFor` | Optional | `string` | - | Id of the input being labelled |
+
+### `FormRadioGroup` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `options` | Required | `FormRadioOption[]` | - | - |
+| `description` | Optional | `string` | - | - |
+| `label` | Optional | `string` | - | - |
+| `orientation` | Optional | `"horizontal" \| "vertical"` | - | - |
+| `placeholder` | Optional | `string` | - | - |
+| `radioGroupProps` | Optional | `object` | - | - |
+
+### `FormSelect` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `options` | Required | `FormSelectOption[]` | - | - |
+| `description` | Optional | `string` | - | - |
+| `label` | Optional | `string` | - | - |
+| `placeholder` | Optional | `string` | - | - |
+| `selectProps` | Optional | `object` | - | - |
+
+### `FormSwitch` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `description` | Optional | `string` | - | - |
+| `label` | Optional | `string` | - | - |
+| `layout` | Optional | `"row" \| "column"` | - | - |
+| `placeholder` | Optional | `string` | - | - |
+| `switchProps` | Optional | `object` | - | - |
+
+### `FormTagInput` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `allowCustomTags` | Optional | `boolean` | - | - |
+| `description` | Optional | `string` | - | - |
+| `label` | Optional | `string` | - | - |
+| `options` | Optional | `TagInputOption[]` | - | - |
+| `placeholder` | Optional | `string` | - | - |
+| `tagInputProps` | Optional | `object` | - | - |
+| `variant` | Optional | `"search" \| "default"` | - | - |
+
+### `FormTextArea` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `description` | Optional | `string` | - | - |
+| `label` | Optional | `string` | - | - |
+| `placeholder` | Optional | `string` | - | - |
+| `textAreaProps` | Optional | `(Omit<TextAreaProps, "ref"> & React.RefAttributes<HTMLTextAreaElement>)` | - | - |
+
+### `FormRadioOption`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `string` | - | Text of the radio's `<label>` |
+| `value` | Required | `string` | - | Value written to the form field when chosen; also the React key and part of the input `id`, so keep it unique |
+| `disabled` | Optional | `boolean` | - | Shows the radio but prevents choosing it |
+
+### `FormSelectOption`
+
+| Field | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `label` | Required | `string` | - | Text shown in the dropdown |
+| `value` | Required | `string` | - | Value written to the form field when chosen; also the React key, so keep it unique |
+| `disabled` | Optional | `boolean` | - | Shows the option but prevents choosing it |
+<!-- END GENERATED: props -->
+
+## Pieces
+
+- `Form` — wraps a `<form>` and provides `FormProvider` context.
+- `FormField` — wraps react-hook-form's `Controller` and provides field context.
+- `FormItem` — layout wrapper that generates IDs for accessibility linking.
+- `FormLabel`, `FormControl`, `FormDescription`, `FormMessage` — slots.
+
+## Example
+
+```tsx
+const schema = z.object({ email: z.string().email() });
+const form = useForm({ resolver: zodResolver(schema), defaultValues: { email: "" } });
+
+<Form form={form} onSubmit={form.handleSubmit(onSubmit)}>
+  <FormField
+    control={form.control}
+    name="email"
+    render={({ field }) => (
+      <FormItem>
+        <FormLabel>Email</FormLabel>
+        <FormControl><Input {...field} /></FormControl>
+        <FormMessage />
+      </FormItem>
+    )}
+  />
+  <Button type="submit">Submit</Button>
+</Form>
+```
+
+## Notes
+
+- Pre-built field helpers (`FormInput`, `FormSelect`, `FormCheckbox`,
+  `FormDatePicker`, `FormCascader`, etc.) live in [`form-fields.tsx`](./form-fields.tsx).
+- See the directory's [`README.md`](./README.md) and [`QUICK_REFERENCE.md`](./QUICK_REFERENCE.md) for the full
+  pattern catalog.

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

@@ -0,0 +1,70 @@
+/**
+ * Runnable example for Form (react-hook-form + zod).
+ */
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useForm } from 'react-hook-form'
+import { z } from 'zod'
+
+import {
+  Button,
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+  Input,
+} from '@tetherto/mdk-react-devkit'
+
+const schema = z.object({
+  name: z.string().min(2, 'At least 2 characters'),
+  email: z.string().email('Must be a valid email'),
+})
+
+type FormValues = z.infer<typeof schema>
+
+export const FormExample = () => {
+  const form = useForm<FormValues>({
+    resolver: zodResolver(schema),
+    defaultValues: { name: '', email: '' },
+  })
+
+  const onSubmit = (values: FormValues) => {
+    // oxlint-disable-next-line no-console
+    console.log('submit', values)
+  }
+
+  return (
+    <Form form={form} onSubmit={form.handleSubmit(onSubmit)}>
+      <FormField
+        control={form.control}
+        name="name"
+        render={({ field }) => (
+          <FormItem>
+            <FormLabel>Name</FormLabel>
+            <FormControl>
+              <Input placeholder="Operator name" {...field} />
+            </FormControl>
+            <FormMessage />
+          </FormItem>
+        )}
+      />
+      <FormField
+        control={form.control}
+        name="email"
+        render={({ field }) => (
+          <FormItem>
+            <FormLabel>Email</FormLabel>
+            <FormControl>
+              <Input placeholder="ops@example.com" {...field} />
+            </FormControl>
+            <FormMessage />
+          </FormItem>
+        )}
+      />
+      <Button type="submit" variant="primary">
+        Submit
+      </Button>
+    </Form>
+  )
+}

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

@@ -0,0 +1,58 @@
+@use '../../styles/mixins' as *;
+/**
+ * Form Component Styles
+ */
+
+.mdk-form {
+  @include flex_column;
+
+  gap: 1.5rem;
+}
+
+.mdk-form-item {
+  @include flex_column;
+
+  gap: 0.5rem;
+  
+  // Prevent layout shift when errors appear/disappear
+  min-height: fit-content;
+}
+
+.mdk-form-label {
+  &--error {
+    color: rgb(var(--mdk-color-error, #ef4444));
+  }
+}
+
+.mdk-form-description {
+  margin: 0;
+  font-family: var(--font-mono);
+  font-size: 0.75rem;
+  line-height: 1.25rem;
+  color: var(--mdk-input-placeholder-color, #999999);
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+  max-width: 100%;
+}
+
+.mdk-form-message {
+  margin: 0;
+  font-family: var(--font-mono);
+  font-size: 0.75rem;
+  line-height: 1.25rem;
+  color: rgb(var(--mdk-color-error, #ef4444));
+  word-wrap: break-word;
+  word-break: break-word;
+  overflow-wrap: break-word;
+  max-width: 100%;
+  
+  // Reserve space to prevent layout shift when errors appear
+  min-height: 1.25rem;
+  
+  // When empty, take up space but be invisible (prevents layout shift)
+  &--empty {
+    visibility: hidden;
+    opacity: 0;
+    pointer-events: none;
+  }
+}

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

@@ -0,0 +1,47 @@
+# `GaugeChart`
+
+A gauge / speedometer chart drawn as pure inline SVG (no third-party runtime
+dependency). Accepts a `percent` value between 0 and 1 and displays it as a
+coloured arc.
+
+<!-- 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 |
+|------|--------|----------------|---------|-------------|
+| `percent` | Required | `number` | - | Value between 0 and 1 (e.g. 0.75 = 75%). Values outside the range are clamped |
+| `arcsLength` | Optional | `number[]` | - | Custom arc-segment proportions (auto-normalised), overriding `nrOfLevels`. e.g. `[0.7, 0.3]` for a progress-style gauge whose first arc is the fill |
+| `arcWidth` | Optional | `number` | `0.2` | Arc thickness as a fraction of the gauge radius (0–1) |
+| `className` | Optional | `string` | - | Additional class for the root `div` |
+| `colors` | Optional | `string[]` | `[COLOR.GREEN, COLOR.RED]` | Arc colours in HEX format |
+| `formatTextValue` | Optional | `((percent: number) => string)` | - | Format the center label from the clamped fraction (0–1) |
+| `height` | Optional | `string \| number` | `200` | Chart height in pixels or any CSS length (e.g. `'200px'` or `'50%'`) |
+| `hideNeedle` | Optional | `boolean` | `false` | Hide the needle + hub (e.g. for a progress-style gauge) |
+| `hideText` | Optional | `boolean` | `false` | Hide the percentage text rendered inside the gauge |
+| `id` | Optional | `string` | `"mdk-gauge-chart"` | Stable id used for the gauge's accessibility labels |
+| `maxWidth` | Optional | `number` | - | Maximum width in pixels |
+| `needleColor` | Optional | `string` | `COLOR.STEEL_GRAY` | Needle + hub colour |
+| `nrOfLevels` | Optional | `number` | `3` | Number of arc segments. Ignored when `arcsLength` is provided |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { GaugeChart } from "@tetherto/mdk-react-devkit"
+
+<GaugeChart percent={0.75} />
+
+<GaugeChart
+  percent={0.4}
+  colors={["#34C759", "#FF9500", "#FF3B30"]}
+  nrOfLevels={3}
+  hideText
+  height={150}
+/>
+```
+
+## Notes
+
+- `percent` is automatically clamped to `[0, 1]`
+- When rendering multiple gauges on the same page, provide a unique `id` for each instance so their SVG accessibility labels stay distinct
+- For a progress-style gauge (single fill arc, no needle) pass `arcsLength={[percent, 1 - percent]}` with two `colors` and `hideNeedle`

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

@@ -0,0 +1,25 @@
+/**
+ * Runnable example for GaugeChart.
+ */
+import { GaugeChart } from '@tetherto/mdk-react-devkit'
+
+export const GaugeChartExample = () => (
+  <div className="mdk-example-row">
+    <GaugeChart percent={0.72} id="gauge-hash-rate" />
+    <GaugeChart
+      percent={0.45}
+      id="gauge-efficiency"
+      colors={['#34C759', '#FF9500', '#FF3B30']}
+      nrOfLevels={5}
+    />
+    <GaugeChart percent={0.95} id="gauge-uptime" hideText height={160} />
+    <GaugeChart
+      percent={0.68}
+      id="gauge-progress"
+      arcsLength={[0.68, 0.32]}
+      colors={['#009393', '#00939330']}
+      hideNeedle
+      formatTextValue={(p) => `${Math.round(p * 100)}%`}
+    />
+  </div>
+)

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

@@ -0,0 +1,11 @@
+.mdk-gauge-chart {
+  position: relative;
+  width: 100%;
+  margin-inline: auto;
+
+  svg {
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+}

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

@@ -0,0 +1,61 @@
+# Heatmap
+
+A generic grid of value-coloured cells on a low→high gradient, plus a matching
+`HeatmapLegend`. Presentational and domain-agnostic — pass a row-major matrix of
+cells and an optional `[min, max]` range (auto-derived otherwise).
+
+Use `renderCell` to overlay domain content (e.g. PDU socket borders, selection,
+tooltips) without forking the primitive; the grid still owns each cell's
+background colour.
+
+<!-- BEGIN GENERATED: props — do not edit; npm run generate:usage-proptables (source: component JSDoc/types via registry.json) -->
+## Props
+
+### `Heatmap` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `data` | Required | `HeatmapCell[][]` | - | Rows of cells (row-major). Rows may be ragged |
+| `ariaLabel` | Optional | `string` | `"Heatmap"` | Accessible label for the grid |
+| `className` | Optional | `string` | - | Additional class for the root element |
+| `colors` | Optional | `readonly string[]` | `HEATMAP_GRADIENT` | Gradient stops low→high. Defaults to the cold→hot `HEATMAP_GRADIENT` |
+| `emptyColor` | Optional | `string` | `#000000` | Colour used for `null` cells |
+| `max` | Optional | `number` | `auto` | Range ceiling (maps to the last gradient stop); auto-derived from the finite values when omitted |
+| `min` | Optional | `number` | `auto` | Range floor (maps to the first gradient stop); auto-derived from the finite values when omitted |
+| `renderCell` | Optional | `((cell: HeatmapCell, context: HeatmapCellContext) => React.ReactNode)` | - | Override the cell's inner content — e.g. to overlay socket borders, selection, or tooltips for a PDU grid. The primitive still owns the cell's background colour (passed via `context.color`) |
+| `showValues` | Optional | `boolean` | `false` | Render each cell's value/label as text |
+
+### `HeatmapLegend` props
+
+| Prop | Status | Type / Options | Default | Description |
+|------|--------|----------------|---------|-------------|
+| `max` | Required | `string \| number` | - | Value (or pre-formatted label) at the high end of the scale |
+| `min` | Required | `string \| number` | - | Value (or pre-formatted label) at the low end of the scale |
+| `className` | Optional | `string` | - | Additional class for the root element |
+| `colors` | Optional | `readonly string[]` | `HEATMAP_GRADIENT` | Gradient stops low→high |
+| `label` | Optional | `string` | - | Heading above the gradient bar (e.g. "Temperature") |
+| `unit` | Optional | `string` | - | Unit suffix appended to `min`/`max` |
+<!-- END GENERATED: props -->
+
+## Example
+
+```tsx
+import { Heatmap, HeatmapLegend } from "@tetherto/mdk-react-devkit"
+
+<Heatmap
+  data={[
+    [{ value: 20 }, { value: 45 }],
+    [{ value: 70 }, { value: null }],
+  ]}
+  showValues
+/>
+<HeatmapLegend label="Temperature" min={20} max={85} unit="°C" />
+```
+
+## Notes
+
+- The colour scale is exported as `getHeatmapColor(value, min, max, stops?)` and
+  the default palette as `HEATMAP_GRADIENT` (cold→hot: blue → green → yellow →
+  red) from `@tetherto/mdk-react-devkit`.
+- `null` values render `emptyColor` and no text
+- Values outside `[min, max]` are clamped to the end stops

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

@@ -0,0 +1,17 @@
+/**
+ * Runnable example for Heatmap + HeatmapLegend.
+ */
+import { Heatmap, HeatmapLegend } from "@tetherto/mdk-react-devkit"
+
+const rows = [
+  [{ value: 20 }, { value: 35 }, { value: 50 }, { value: 42 }],
+  [{ value: 60 }, { value: 72 }, { value: null }, { value: 55 }],
+  [{ value: 44 }, { value: 81 }, { value: 66 }, { value: 30 }],
+]
+
+export const HeatmapExample = () => (
+  <div className="mdk-example-row">
+    <Heatmap data={rows} showValues />
+    <HeatmapLegend label="Temperature" min={20} max={81} unit="°C" />
+  </div>
+)

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

@@ -0,0 +1,48 @@
+@use "@primitives/styles/mixins" as *;
+
+.mdk-heatmap {
+  display: grid;
+  gap: 2px;
+  width: 100%;
+
+  &__cell {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    aspect-ratio: 1 / 1;
+    min-width: 0;
+    border-radius: 2px;
+    font-size: 10px;
+    line-height: 1;
+  }
+
+  &__value {
+    padding: 2px;
+    color: var(--mdk-color-white);
+    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.6);
+    white-space: nowrap;
+  }
+}
+
+.mdk-heatmap-legend {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+
+  &__label {
+    font-size: 12px;
+    font-weight: 600;
+  }
+
+  &__bar {
+    height: 8px;
+    border-radius: 4px;
+  }
+
+  &__scale {
+    display: flex;
+    justify-content: space-between;
+    font-size: 11px;
+    opacity: 0.7;
+  }
+}

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

@@ -0,0 +1,76 @@
+# Icons
+
+A collection of domain-specific SVG icon components plus the `createIcon` factory for authoring new icons. All icons share a consistent `IconProps` interface and are built with `React.forwardRef`.
+
+<!-- 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 | `undefined` | - | - |
+| `color` | Optional | `string` | `"currentColor"` | Only affects single-color icons (default: 'currentColor') |
+| `isOpen` | Optional | `boolean` | - | - |
+| `size` | Optional | `string \| number` | - | Sets both width and height |
+<!-- END GENERATED: props -->
+
+## `IconProps` 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                    |
+| -------- | -------- | ------------------ | ---------------- | ------------------------------ |
+| `size`   | Optional | `number \| string` | —                | Sets both `width` and `height` |
+| `color`  | Optional | `string`           | `'currentColor'` | Fill/stroke color (only affects single-color icons) |
+| `width`  | Optional | `number \| string` | icon default     | Override width independently   |
+| `height` | Optional | `number \| string` | icon default     | Override height independently  |
+
+All other `SVGAttributes<SVGElement>` props are forwarded to the `<svg>` element.
+
+## Available Icons
+
+Sidebar navigation: `DashboardNavIcon`, `AlertsNavIcon`, `FarmsNavIcon`, `ExplorerNavIcon`, `FinancialsNavIcon`, `InventoryNavIcon`, `MinersOverviewNavIcon`, `OperationsNavIcon`, `PoolManagerNavIcon`, `ReportingNavIcon`, `SettingsNavIcon`, `UserManagementNavIcon`, `CabinetWidgetNavIcon`, `ContainerWidgetsNavIcon`
+
+Status / alarm: `ErrorStatusIcon`, `OfflineStatusIcon`, `SleepStatusIcon`, `MiningStatusIcon`, `FluidAlarmIcon`, `OfflineAlarmIcon`, `OtherAlarmIcon`, `PressureAlarmIcon`, `TemperatureAlarmIcon`, `AlertTriangleIcon`
+
+Miner card / stats: `HashrateCardIcon`, `HashrateStatIcon`, `MinersStatIcon`, `BtcCardIcon`, `EfficiencyIcon`, `FrequencyIcon`, `FanIcon`, `PowerIcon`, `ConsumptionIcon`, `ModeIcon`, `TemperatureIndicatorIcon`, `TemperatureCelsiusIcon`
+
+Weather: `CloudyIcon`, `PartlyCloudyIcon`, `RainThunderIcon`, `RainyIcon`, `SnowyIcon`, `SunnyIcon`, `TemperatureWeatherIcon`
+
+Navigation / UI: `ArrowIcon`, `RightArrowIcon`, `RightNavigateIcon`, `MenuIcon`, `PinIcon`, `UnPinIcon`, `ExportIcon`, `ScaleControlIcon`, `NotificationBellIcon`, `SettingsHeaderIcon`, `SignOutIcon`, `LiveIcon`
+
+Misc: `ActionsTickIcon`, `CommentIcon`, `CommentIconCommon`, `CoolingDropIcon`, `DecreaseIcon`, `IncreaseIcon`, `FarmAlertIcon`, `FarmStarIcon`, `GoogleIcon`, `MinerExplorerIcon`, `MinerOverviewIcon`, `SiteOverviewIcon`, `UserAvatarIcon`, `VolumeOffIcon`, `VolumeOnIcon`, `ProfitArrowIcon`, `ProductionDataIcon`, `PoolsIcon`
+
+## `createIcon` factory
+
+Use `createIcon` to define new SVG icons that automatically follow the `IconProps` interface.
+
+### `CreateIconOptions`
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `displayName` | `string` | yes | Component display name |
+| `viewBox` | `string` | yes | SVG `viewBox` |
+| `defaultWidth` | `number` | no | Default width (defaults to `24`) |
+| `defaultHeight` | `number` | no | Default height (defaults to `24`) |
+| `multiColor` | `boolean` | no | When `true`, disables single-color fill |
+| `path` | `ReactNode \| ((props: { color: string }) => ReactNode)` | yes | SVG paths |
+
+## Example
+
+```tsx
+import { DashboardNavIcon, ArrowIcon, createIcon } from "@tetherto/mdk-react-devkit"
+
+// Using a built-in icon
+<DashboardNavIcon size={20} />
+<ArrowIcon color="#FF9500" width={16} height={16} />
+
+// Creating a custom icon
+const StarIcon = createIcon({
+  displayName: "StarIcon",
+  viewBox: "0 0 24 24",
+  path: <path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z" fill="currentColor" />,
+})
+
+<StarIcon size={24} color="gold" />
+```

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

@@ -0,0 +1,85 @@
+/**
+ * Runnable example for Icons — a representative selection of exported icon components.
+ */
+import {
+  AlertTriangleIcon,
+  ArrowIcon,
+  DashboardNavIcon,
+  FanIcon,
+  HashrateCardIcon,
+  NotificationBellIcon,
+  PowerIcon,
+  SunnyIcon,
+} from '@tetherto/mdk-react-devkit'
+
+const IconRow = ({ children }: { children: React.ReactNode }) => (
+  <div style={{ display: 'flex', alignItems: 'center', gap: 16, flexWrap: 'wrap' }}>{children}</div>
+)
+
+const IconSample = ({ label, children }: { label: string; children: React.ReactNode }) => (
+  <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 6 }}>
+    {children}
+    <span style={{ fontSize: 11, color: 'var(--mdk-color-text-secondary, #888)' }}>{label}</span>
+  </div>
+)
+
+export const IconsExample = () => (
+  <div className="mdk-example-row" style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+    {/* Default size (24px) */}
+    <IconRow>
+      <IconSample label="DashboardNavIcon">
+        <DashboardNavIcon />
+      </IconSample>
+      <IconSample label="AlertTriangleIcon">
+        <AlertTriangleIcon />
+      </IconSample>
+      <IconSample label="HashrateCardIcon">
+        <HashrateCardIcon />
+      </IconSample>
+      <IconSample label="FanIcon">
+        <FanIcon />
+      </IconSample>
+      <IconSample label="SunnyIcon">
+        <SunnyIcon />
+      </IconSample>
+      <IconSample label="ArrowIcon">
+        <ArrowIcon />
+      </IconSample>
+      <IconSample label="NotificationBellIcon">
+        <NotificationBellIcon />
+      </IconSample>
+      <IconSample label="PowerIcon">
+        <PowerIcon />
+      </IconSample>
+    </IconRow>
+
+    {/* Custom sizes */}
+    <IconRow>
+      <IconSample label="size=16">
+        <DashboardNavIcon size={16} />
+      </IconSample>
+      <IconSample label="size=24">
+        <DashboardNavIcon size={24} />
+      </IconSample>
+      <IconSample label="size=32">
+        <DashboardNavIcon size={32} />
+      </IconSample>
+    </IconRow>
+
+    {/* Custom colours */}
+    <IconRow>
+      <IconSample label="default color">
+        <AlertTriangleIcon size={24} />
+      </IconSample>
+      <IconSample label="color=#FF9500">
+        <AlertTriangleIcon size={24} color="#FF9500" />
+      </IconSample>
+      <IconSample label="color=#4ADE80">
+        <AlertTriangleIcon size={24} color="#4ADE80" />
+      </IconSample>
+      <IconSample label="color=#F87171">
+        <AlertTriangleIcon size={24} color="#F87171" />
+      </IconSample>
+    </IconRow>
+  </div>
+)