npm - mgv-backoffice - Versions diffs - 1.42.0 → 1.43.0 - Mend

mgv-backoffice 1.42.0 → 1.43.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +2000 -1999
package/dist/components/BaseDropdown.vue.d.ts +8 -0
package/dist/ui-lib.css +1 -1
package/dist/ui-lib.js +16 -11
package/dist/ui-lib.umd.cjs +1 -1
package/package.json +1 -1
package/src/components/BaseDropdown.test.ts +102 -87
package/src/components/BaseDropdown.vue +188 -172

package/README.md CHANGED Viewed

@@ -1,1999 +1,2000 @@
-# mgv-backoffice
-Shared Vue 3 UI component library built with TypeScript and Tailwind CSS.
-## Installation
-```bash
-npm install mgv-backoffice
-```
-### Peer Dependencies
-These must be installed in your project:
-```bash
-npm install vue@^3.5.0 vue-router@^5.0.0 @heroicons/vue@^2.0.0
-```
-> `vue-router` 5.x is required (peer range `^5.0.0`) — it's what the library is
-> developed and tested against. Upgrade from Router 4 before installing this library.
-### Import Styles
-Include the library's stylesheet in your app entry point:
-```ts
-import 'mgv-backoffice/dist/style.css'
-```
-### Tailwind Safelist
-If your project uses Tailwind, import the safelist so dynamic classes used by this library are generated correctly:
-```js
-// In your Tailwind config
-import safelist from 'mgv-backoffice/tailwind.safelist'
-```
-Or include the pre-built CSS safelist:
-```css
-@import 'mgv-backoffice/tailwind.safelist.css';
-```
-> Maintainers: `tailwind.safelist.js` is the single source of truth.
-> `tailwind.safelist.css` is generated from it via `npm run safelist`
-> (runs automatically before `npm run build`) — don't edit it by hand.
----
-## Components
-### BaseAlert
-Inline notice panel with color-coded variants (error / warning / success /
-info), theme-aware via the shared `isDark` ref. The optional default slot
-renders body content under the title, and `compact` gives a slim text-xs
-variant for in-form warnings.
-**Props:**
-| Prop      | Type        | Default            | Description              |
-| --------- | ----------- | ------------------ | ------------------------ |
-| `title`   | `String`    | `''`               | Bold headline (optional when the slot carries the message). |
-| `color`   | `AlertEnum` | `AlertEnum.ERROR`  | Alert color variant.     |
-| `compact` | `Boolean`   | `false`            | Slim variant: text-xs, smaller icon/padding. |
-**Slots:** default — body content rendered under the title.
-**Example:**
-```vue
-<template>
-  <BaseAlert title="Operation successful" :color="AlertEnum.SUCCESS" />
-  <BaseAlert title="Proxying is active." :color="AlertEnum.WARNING">
-    <p class="mt-0.5 text-xs opacity-90">The canned response below is ignored.</p>
-  </BaseAlert>
-  <BaseAlert compact :color="AlertEnum.WARNING">
-    Chunked dribble is ignored while Fault Simulation is active.
-  </BaseAlert>
-</template>
-<script setup lang="ts">
-import { BaseAlert, AlertEnum } from 'mgv-backoffice'
-</script>
-```
----
-### BaseBadge
-Colored status badge/pill. Renders nothing when the default slot is empty;
-an omitted or unrecognized `color` falls back to the red palette.
-**Props:**
-| Prop    | Type     | Default | Description                       |
-| ------- | -------- | ------- | --------------------------------- |
-| `color` | `String` | —       | Color variant (use `ColorsEnums`) |
-**Slots:** `default` — badge label content.
-**Example:**
-```vue
-<template>
-  <BaseBadge :color="ColorsEnums.GREEN">Active</BaseBadge>
-  <BaseBadge :color="ColorsEnums.RED">Inactive</BaseBadge>
-</template>
-<script setup lang="ts">
-import { BaseBadge, ColorsEnums } from 'mgv-backoffice'
-</script>
-```
----
-### BaseBreadcrumb
-Breadcrumb navigation. Provide items manually or pass a URL path for
-auto-generation; with neither prop it auto-generates from
-`window.location.pathname`. A "Home" crumb linking to `/` is always prepended.
-**Props:**
-| Prop    | Type            | Default     | Description                                |
-| ------- | --------------- | ----------- | ------------------------------------------ |
-| `items` | `BreadCrumb[]`  | `undefined` | Manual breadcrumb entries                  |
-| `path`  | `String`        | `undefined` | URL path for auto-generated breadcrumbs    |
-**BreadCrumb type:**
-```ts
-interface BreadCrumb {
-  name: string
-  url: string
-}
-```
-**Example:**
-```vue
-<template>
-  <!-- Manual -->
-  <BaseBreadcrumb :items="[
-    { name: 'Home', url: '/' },
-    { name: 'Users', url: '/users' },
-    { name: 'Profile', url: '/users/1' }
-  ]" />
-  <!-- Auto-generated from path -->
-  <BaseBreadcrumb path="/users/settings/profile" />
-</template>
-<script setup lang="ts">
-import { BaseBreadcrumb } from 'mgv-backoffice'
-import type { BreadCrumb } from 'mgv-backoffice'
-</script>
-```
----
-### BaseButton
-Button with color, size, loading state, and Vue Router integration.
-**Props:**
-| Prop          | Type                                | Default               | Description                          |
-| ------------- | ----------------------------------- | --------------------- | ------------------------------------ |
-| `description` | `String`                            | **required**          | Button label text                    |
-| `color`       | `String`                            | `BaseButtonEnum.GREEN` | Color variant (`BLUE`/`WHITE`/`DARK`/`GREEN`/`EMERALD`/`RED`/`YELLOW`/`PURPLE`/`SKY`/`GRAY`/`AMBER`) |
-| `outline`     | `Boolean`                           | `false`               | Outlined/secondary style — transparent fill, coloured text + border, tinted hover (theme-aware) |
-| `ghost`       | `Boolean`                           | `false`               | Ghost/borderless style — no border or fill, coloured text + tinted hover (theme-aware). For compact toolbar/action buttons |
-| `to`          | `String`                            | —                     | Vue Router path (renders `<router-link>`) |
-| `type`        | `'button' \| 'submit' \| 'reset'`  | `'button'`            | HTML button type                     |
-| `iconLeft`    | `Boolean`                           | `false`               | Render the slot icon before the label |
-| `isRounded`   | `Boolean`                           | —                     | Fully rounded corners                |
-| `isDisable`   | `Boolean`                           | —                     | Disabled state                       |
-| `size`        | `String`                            | —                     | Size variant (use `BaseButtonSizeEnum`) |
-| `isLoading`   | `Boolean`                           | —                     | Show loading spinner                 |
-**Slots:** `default`
-**Example:**
-```vue
-<template>
-  <BaseButton description="Submit" :color="BaseButtonEnum.GREEN" type="submit" />
-  <BaseButton description="Go to Users" :to="'/users'" />
-  <BaseButton description="Saving..." :isLoading="true" :isDisable="true" />
-  <BaseButton
-    description="Delete"
-    :color="BaseButtonEnum.RED"
-    :size="BaseButtonSizeEnum.SMALL"
-  />
-  <!-- Outlined / secondary -->
-  <BaseButton description="Import" :color="BaseButtonEnum.EMERALD" outline iconLeft>
-    <ArrowUpTrayIcon class="w-4 h-4 mr-1.5" />
-  </BaseButton>
-  <!-- Ghost / borderless toolbar action -->
-  <BaseButton description="Logs" :color="BaseButtonEnum.SKY" ghost iconLeft :size="BaseButtonSizeEnum.SMALL">
-    <ClipboardDocumentListIcon class="w-4 h-4 mr-1.5" />
-  </BaseButton>
-</template>
-<script setup lang="ts">
-import { BaseButton, BaseButtonEnum, BaseButtonSizeEnum } from 'mgv-backoffice'
-</script>
-```
----
-### BaseLine
-Horizontal divider with style variants.
-**Props:**
-| Prop   | Type     | Default         | Description       |
-| ------ | -------- | --------------- | ----------------- |
-| `mode` | `String` | `LineEnum.BASE` | Divider style     |
-**Example:**
-```vue
-<template>
-  <BaseLine />
-  <BaseLine :mode="LineEnum.SQUARE" />
-</template>
-<script setup lang="ts">
-import { BaseLine, LineEnum } from 'mgv-backoffice'
-</script>
-```
----
-### BaseLogo
-SVG brand logo component.
-**Props:**
-| Prop   | Type     | Default                | Description  |
-| ------ | -------- | ---------------------- | ------------ |
-| `size` | `String` | `BaseLogoEnum.MEDIUM`  | Logo size    |
-**Example:**
-```vue
-<template>
-  <BaseLogo :size="BaseLogoEnum.LARGE" />
-</template>
-<script setup lang="ts">
-import { BaseLogo, BaseLogoEnum } from 'mgv-backoffice'
-</script>
-```
----
-### BaseModal
-> ⚠️ **Deprecated.** Prefer [`BaseConfirmModal`](#baseconfirmmodal) for confirm/cancel
-> flows or [`BaseModalShell`](#basemodalshell) for custom dialogs — they support dark
-> mode, teleport to `<body>`, and slot-based composition. Kept for backward
-> compatibility.
-Confirmation dialog with support for delete and success modes. `DELETE` mode renders
-the confirm/cancel pair; any other mode renders the title, optional `description`,
-the default slot, and a single OK button that emits `closeModal`.
-**Props:**
-| Prop          | Type     | Default     | Description                         |
-| ------------- | -------- | ----------- |-------------------------------------|
-| `title`       | `String` | **required**| Modal heading                       |
-| `description` | `String` | —           | Body text                           |
-| `to`          | `String` | `"/"`       | Unused — declared for backward compatibility only; confirm just emits `confirmModal`, no navigation happens |
-| `mode`        | `String` | `'SUCCESS'` | Modal variant (use `BaseModalEnum`) |
-**Events:**
-| Event          | Description                     |
-| -------------- | ------------------------------- |
-| `closeModal`   | Emitted when modal is dismissed (cancel/OK button, backdrop click, or Escape) |
-| `confirmModal` | Emitted on confirm action       |
-**Example:**
-```vue
-<template>
-  <BaseModal
-    title="Delete this item?"
-    description="This action cannot be undone."
-    :mode="BaseModalEnum.DELETE"
-    @closeModal="showModal = false"
-    @confirmModal="handleDelete"
-  />
-</template>
-<script setup lang="ts">
-import { ref } from 'vue'
-import { BaseModal, BaseModalEnum } from 'mgv-backoffice'
-const showModal = ref(true)
-const handleDelete = () => { /* ... */ }
-</script>
-```
----
-### BaseRow
-Card-like content container with border and shadow.
-**Props:**
-| Prop      | Type     | Default   | Description            |
-| --------- | -------- | --------- | ---------------------- |
-| `bgColor` | `String` | `"bg-white"` | Background color — a full Tailwind class (e.g. `"bg-slate-50"`), not a bare color name |
-**Slots:** `default` — row content.
-**Example:**
-```vue
-<template>
-  <BaseRow>
-    <p>Card content goes here</p>
-  </BaseRow>
-</template>
-<script setup lang="ts">
-import { BaseRow } from 'mgv-backoffice'
-</script>
-```
----
-### BaseSpinner
-Animated loading spinner — a neutral ring with a coloured leading arc.
-**Props:**
-| Prop    | Type                                                                       | Default  | Description                                                  |
-|---------|----------------------------------------------------------------------------|----------|-------------------------------------------------------------|
-| `size`  | `'sm' \| 'md' \| 'lg' \| 'xl'`                                              | `'sm'`   | Diameter + ring thickness — 16 / 24 / 32 / 48px.            |
-| `color` | `'blue' \| 'emerald' \| 'sky' \| 'indigo' \| 'teal' \| 'purple' \| 'red' \| 'amber'` | `'emerald'` | Colour of the spinning arc. The track stays neutral gray.   |
-With no props it renders a 16px emerald spinner. For page loaders use `size="xl"` centered, e.g. `<div class="flex justify-center py-12"><BaseSpinner size="xl" /></div>`.
-**Example:**
-```vue
-<template>
-  <!-- legacy default -->
-  <BaseSpinner />
-  <!-- larger, themed -->
-  <BaseSpinner size="lg" color="emerald" />
-</template>
-<script setup lang="ts">
-import { BaseSpinner } from 'mgv-backoffice'
-</script>
-```
----
-### BaseToast
-Toast notification with positioning and auto-dismiss.
-**Props:**
-| Prop           | Type             | Default   | Description                                |
-| -------------- | ---------------- | --------- | ------------------------------------------ |
-| `mode`         | `BaseToastEnum`  | **required** | Toast variant (SUCCESS, WARNING, ERROR) |
-| `description`  | `String`         | **required** | Message text                            |
-| `hasCloseIcon` | `Boolean`        | `true`    | Show close button                          |
-| `positioning`  | `String`         | `PositioningEnum.TOP_RIGHT` | Screen position (use `PositioningEnum`) |
-| `duration`     | `Number`         | `5000`    | Auto-dismiss delay in milliseconds         |
-**Example:**
-```vue
-<template>
-  <BaseToast
-    :mode="BaseToastEnum.SUCCESS"
-    description="Changes saved successfully!"
-    :positioning="PositioningEnum.TOP_RIGHT"
-  />
-</template>
-<script setup lang="ts">
-import { BaseToast, BaseToastEnum, PositioningEnum } from 'mgv-backoffice'
-</script>
-```
----
-### ColoredSquares
-Colored square indicator with randomized pastel accent.
-**Props:**
-| Prop    | Type     | Default | Description                       |
-| ------- | -------- | ------- | --------------------------------- |
-| `color` | `String` | —       | Color variant (use `ColorsEnums`) |
-**Slots:** `default` — label content.
-**Example:**
-```vue
-<template>
-  <ColoredSquares :color="ColorsEnums.BLUE">Category A</ColoredSquares>
-</template>
-<script setup lang="ts">
-import { ColoredSquares, ColorsEnums } from 'mgv-backoffice'
-</script>
-```
----
-### EarningsCard
-Earnings summary card with formatted currency display. Supports a signed P&L
-mode that renders a red loss theme (and a downward trend glyph) for negative
-amounts.
-**Props:**
-| Prop       | Type     | Default                 | Description          |
-| ---------- | -------- |-------------------------|----------------------|
-| `title`    | `String` | `'TOTAL EARNINGS'`      | Card heading         |
-| `amount`   | `Number` | `0`                     | Monetary value (a stringified number is coerced) |
-| `subtitle` | `String` | `'Lifetime commission'` | Subheading text      |
-| `badge`    | `String` | `''`                    | Optional badge label |
-| `currency` | `String` | `'$'`                   | Currency symbol      |
-| `decimals` | `Number` | `2`                     | Fraction digits shown for the amount |
-| `accent`   | `'orange' \| 'emerald' \| 'red'` | `'orange'` | Card theme. `emerald` tints it green; `red` is the loss theme. |
-| `signed`   | `Boolean` | `false`                | Treat `amount` as a signed P&L figure: a negative value automatically switches to the `red` loss theme and flips the trend glyph to point **down**; a non-negative value keeps the chosen `accent` and the upward glyph. |
-| `compact`  | `Boolean` | `false`                | Dense variant for dashboards that tile many cards on one row: tighter padding, smaller type, trend glyph shrunk into the top-right corner. Don't combine with `badge` — both occupy the top-right corner. |
-**Example:**
-```vue
-<template>
-  <!-- Always-positive total: original behaviour. -->
-  <EarningsCard
-    title="Monthly Revenue"
-    :amount="12500"
-    subtitle="April 2026"
-    currency="€"
-  />
-  <!-- Signed P&L: renders red + a down arrow when the amount is negative. -->
-  <EarningsCard
-    title="TOTAL P&L"
-    :amount="-128.4"
-    subtitle="Realised + unrealised"
-    accent="emerald"
-    signed
-  />
-</template>
-<script setup lang="ts">
-import { EarningsCard } from 'mgv-backoffice'
-</script>
-```
----
-### EuroAmount
-Formatted euro currency display with conditional color coding.
-**Props:**
-| Prop           | Type      | Default | Description                                     |
-| -------------- | --------- | ------- |-------------------------------------------------|
-| `amount`       | `Number`  | —       | Value to display                                |
-| `beforeAmount` | `Number`  | `null`  | Previous value: red if `amount < beforeAmount`, green if `amount >= beforeAmount`. When omitted, a non-negative amount renders neutral (never green); a negative amount is always red. |
-| `showCurrency` | `Boolean` | `true`  | Show euro symbol                                |
-**Example:**
-```vue
-<template>
-  <!-- Shows green (amount > beforeAmount) -->
-  <EuroAmount :amount="1500" :beforeAmount="1200" />
-  <!-- Shows red (negative) -->
-  <EuroAmount :amount="-300" />
-  <!-- Without currency symbol -->
-  <EuroAmount :amount="800" :showCurrency="false" />
-</template>
-<script setup lang="ts">
-import { EuroAmount } from 'mgv-backoffice'
-</script>
-```
----
-### Pagination
-Page navigation with smart ellipsis for large page counts.
-**Props:**
-| Prop           | Type     | Default | Description             |
-| -------------- | -------- | ------- | ----------------------- |
-| `totalItems`   | `Number` | **required** | Total number of items   |
-| `itemsPerPage` | `Number` | `20`    | Items shown per page    |
-**Events:**
-| Event          | Payload  | Description                      |
-| -------------- | -------- |----------------------------------|
-| `page-changed` | `Number` | Emitted with the new page number |
-**Example:**
-```vue
-<template>
-  <Pagination
-    :totalItems="200"
-    :itemsPerPage="10"
-    @page-changed="onPageChange"
-  />
-</template>
-<script setup lang="ts">
-import { Pagination } from 'mgv-backoffice'
-const onPageChange = (page: number) => {
-  console.log('Page:', page)
-}
-</script>
-```
----
-### TrendArrow
-Up/down trend indicator displayed as a colored badge.
-**Props:**
-| Prop     | Type     | Default | Description                                          |
-| -------- | -------- | ------- |------------------------------------------------------|
-| `number` | `Number` | —       | Positive = green arrow up, negative = red arrow down, zero = neutral gray dash |
-| `icon`   | `String` | —       | Optional suffix appended after the number (e.g. `"%"`) |
-**Example:**
-```vue
-<template>
-  <TrendArrow :number="12.5" />   <!-- Green up arrow -->
-  <TrendArrow :number="-3.2" />   <!-- Red down arrow -->
-  <TrendArrow :number="0" />      <!-- Neutral gray dash -->
-</template>
-<script setup lang="ts">
-import { TrendArrow } from 'mgv-backoffice'
-</script>
-```
----
-## Enums
-All enums are importable directly from the package:
-```ts
-import {
-  AlertEnum,
-  BaseBadgeEnum,
-  BaseButtonEnum,
-  BaseButtonSizeEnum,
-  BaseLogoEnum,
-  BaseModalEnum,
-  BaseToastEnum,
-  ColorsEnums,
-  LineEnum,
-  PositioningEnum
-} from 'mgv-backoffice'
-```
-| Enum                 | Values                                                        |
-| -------------------- |---------------------------------------------------------------|
-| `AlertEnum`          | `WARNING`, `ERROR`, `SUCCESS`, `INFO`                         |
-| `BaseBadgeEnum`      | `WIN`, `LOSE`                                                 |
-| `BaseButtonEnum`     | `RED`, `BLUE`, `WHITE`, `DARK`, `GREEN`, `EMERALD`, `YELLOW`, `PURPLE`, `SKY`, `GRAY`, `AMBER` |
-| `BaseButtonSizeEnum` | `EXTRA_SMALL`, `SMALL`, `BASE`, `LARGE`, `EXTRA_LARGE`        |
-| `BaseLogoEnum`       | `SMALL`, `MEDIUM`, `LARGE` (`BaseLoginEnum` is a deprecated alias) |
-| `BaseModalEnum`      | `DELETE`, `SUCCESS`                                           |
-| `BaseToastEnum`      | `SUCCESS`, `WARNING`, `ERROR`                                 |
-| `ColorsEnums`        | `NONE`, `RED`, `YELLOW`, `BLACK`, `GRAY`, `GREEN`, `BLUE`     |
-| `LineEnum`           | `BASE`, `BASE_SHORTER`, `SQUARE`                              |
-| `PositioningEnum`    | `TOP_LEFT`, `TOP_RIGHT`, `BOTTOM_LEFT`, `BOTTOM_RIGHT`        |
----
-## Types
-```ts
-import type { BreadCrumb, DropdownOption, PnL, PnLInputs } from 'mgv-backoffice'
-```
-| Type             | Shape                                  |
-| ---------------- | -------------------------------------- |
-| `BreadCrumb`     | `{ name: string; url: string }`        |
-| `DropdownOption` | `{ value: string \| number; label: string; title?: string; disabled?: boolean }` |
-| `PnLInputs`      | `{ buyPrice; lastPrice; filledQty }` (each `number \| string \| null \| undefined`) |
-| `PnL`            | `{ pnlUsd: number \| null; pnlPct: number \| null }` |
-The other exported types — `NavItem`, `NavSection`, `EntityPickerItem`,
-`LoginCredentials`, `NotificationItem`, `SegmentedOption`, `TableColumn`,
-`SpecField`, `SpecFieldType`, `SpecFieldValue`, `StatBreakdownItem`,
-`PillPickerItem`, `DistributionBar`, `CredentialsView`, `CredentialsUpdate` —
-are documented in their component's section.
----
-## Utilities
-```ts
-import { getBaseColor, getBaseColorOf } from 'mgv-backoffice'
-```
-| Function         | Signature                          | Returns                             |
-| ---------------- | ---------------------------------- | ----------------------------------- |
-| `getBaseColor`   | `(c: AlertEnum) => string`         | Tailwind color name for alert type  |
-| `getBaseColorOf` | `(c: ColorsEnums) => string`       | Tailwind color name for color enum  |
-### HTTP colours
-```ts
-import {
-  methodBadgeSolid,
-  methodBadgeBright,
-  methodBadgeTinted,
-  statusBadgeSolid,
-  statusBadgeTinted,
-  statusBadgeSoft,
-} from 'mgv-backoffice'
-```
-Tailwind class helpers for HTTP method and status code badges. `Solid` variants
-return saturated `bg-*-600` classes for use on neutral surfaces; `Bright` /
-`Tinted` variants return softer combinations suitable for cards. `statusBadgeTinted`
-takes `(status, isDark)` to adapt between themes.
-`methodBadgeTinted(method, isDark)` gives each method its own hue on a soft
-tinted surface (`bg-*-500/15` dark / `bg-*-100` light; GET blue, POST emerald,
-PUT amber, DELETE red, PATCH purple, HEAD sky) — the card-chip palette used by
-WireMate's mock/stub cards. `statusBadgeSoft(status, isDark)` is its status
-companion keyed by status class (emerald 2xx / sky 3xx / amber 4xx / red 5xx).
-### Key/value row validators
-```ts
-import { rowKeyMissing, rowValueMissing } from 'mgv-backoffice'
-import type { KeyValueRowLike } from 'mgv-backoffice'
-```
-| Function          | Signature                                                              | Returns |
-| ----------------- | ---------------------------------------------------------------------- | ------- |
-| `rowValueMissing` | `(row: { key?, value?, matcherType? }) => boolean`                     | `true` when the row has a key but no value. |
-| `rowKeyMissing`   | `(row: { key?, value?, matcherType? }) => boolean`                     | `true` when the row has a value but no key. |
-Consistency checks for dynamic key/value grids (header lists, query params,
-metadata rows). Rows with `matcherType: 'absent'` are exempt — an absent
-matcher intentionally carries no value.
-### Input validators
-```ts
-import { isValidAbsoluteUrl, isValidJson, isValidXml, isValidBase64 } from 'mgv-backoffice'
-```
-Pure, dependency-free form-input validators. The payload validators treat
-empty/whitespace-only input as **valid** — required-ness is a separate rule
-from well-formedness; `isValidAbsoluteUrl` validates a value that must exist,
-so empty is invalid there.
-| Function             | Signature                    | Returns |
-| -------------------- | ---------------------------- | ------- |
-| `isValidAbsoluteUrl` | `(value: string) => boolean` | `true` for an absolute `http://` / `https://` URL (other schemes rejected). |
-| `isValidJson`        | `(str: string) => boolean`   | `true` when empty or parseable as JSON. |
-| `isValidXml`         | `(str: string) => boolean`   | `true` when empty or well-formed XML (DOMParser `<parsererror>` check; browser-only). |
-| `isValidBase64`      | `(str: string) => boolean`   | `true` when empty or well-formed base64 (whitespace stripped, length/alphabet checked, then `atob` as the final authority). |
-### HTML sanitizer
-```ts
-import { sanitizeHtml, isSafeHref } from 'mgv-backoffice'
-```
-| Function       | Signature                                       | Returns |
-| -------------- | ----------------------------------------------- | ------- |
-| `sanitizeHtml` | `(raw: string \| undefined \| null) => string`  | Allow-list–sanitised HTML safe for `v-html`. |
-| `isSafeHref`   | `(value: string) => boolean`                    | `true` if the href uses a safe scheme (http/https/mailto/tel, root-relative, or anchor) or is empty/whitespace-only. |
-Allow-list sanitizer for strings bound into `v-html`. Keeps a small set of
-formatting tags (`a`, `b`/`strong`, `i`/`em`, `code`, `pre`, `p`, `ul`/`ol`/`li`,
-`span`, `div`, `br`), strips all other elements (unwrapping to text, or dropping
-content entirely for `script`/`style`/`iframe`/etc.), removes every attribute
-except `href`/`title` on anchors, keeps only allow-listed hrefs (http/https/
-mailto/tel, root-relative `/`, anchors `#`, or empty — every other scheme such
-as `javascript:`, `data:`, `ftp:` is stripped), and hardens surviving links with
-`rel="noopener noreferrer" target="_blank"`. Browser-only (uses `DOMParser`).
-```ts
-sanitizeHtml('<p>Hi<script>alert(1)<\/script></p>') // '<p>Hi</p>'
-```
-### Display formatters
-```ts
-import {
-  fmtNumber,
-  fmtDate,
-  fmtDateTime,
-  fmtDateShort,
-  fmtPrice,
-  fmtPct,
-  fmtUsd,
-  // …plus fmtDateTimeMs, fmtCalendarDate, fmtCalendarDateTime,
-  // fmtMsAsSeconds, fmtBytes, fmtDuration, formatJson, stringifyValue
-} from 'mgv-backoffice'
-```
-Locale-aware, pure, dependency-free formatters for tables, logs and charts.
-`fmtNumber`, `fmtDate`, `fmtCalendarDate`, `fmtCalendarDateTime` and
-`fmtDuration` handle missing/non-finite input gracefully (rendering an
-em-dash) so raw API values can be passed without pre-sanitising; the
-epoch/numeric formatters (`fmtDateTime`, `fmtDateShort`, `fmtDateTimeMs`,
-`fmtPrice`, `fmtPct`, `fmtUsd`) expect valid input and will render
-`"Invalid Date"` / `"NaN"` otherwise.
-| Function       | Signature                                                       | Returns |
-| -------------- | --------------------------------------------------------------- | ------- |
-| `fmtNumber`    | `(n: number \| string \| null \| undefined, digits = 4) => string` | Fixed-fraction number; em-dash for null/undefined/non-finite. Accepts numeric strings. |
-| `fmtDate`      | `(s: string \| number \| null \| undefined) => string`          | Locale date-time from ISO string or epoch; em-dash on empty, raw value on parse failure. |
-| `fmtDateTime`  | `(ms: number) => string`                                        | Compact `"Mon D, HH:MM"` label from epoch-millis (chart axes/tooltips). |
-| `fmtDateTimeMs`| `(s: string \| number) => string`                               | Full 24-hour locale date-time WITH the millisecond fraction — for dense feeds where same-second rows must stay distinguishable. |
-| `fmtDateShort` | `(ms: number) => string`                                        | Short `"Mon D"` calendar label from epoch-millis. |
-| `fmtCalendarDate` | `(s: string \| number \| null \| undefined) => string`       | `"Mon D, YYYY"` en-US calendar label; em-dash on empty, raw value on parse failure. |
-| `fmtCalendarDateTime` | `(s: string \| number \| null \| undefined) => string`   | `"Mon D, YYYY, HH:MM"` en-US calendar label with time of day. |
-| `fmtMsAsSeconds` | `(ms: number \| null \| undefined) => string`                 | `"= 1.50 s"` magnitude hint for millisecond inputs (3 decimals below 1 s); `''` for non-positive input. |
-| `fmtBytes`     | `(bytes: number \| null \| undefined) => string`                | `"512 B"` / `"1.5 KB"` / `"2.0 MB"`; `''` for zero/falsy input. |
-| `fmtDuration`  | `(ms: number \| null \| undefined, maxUnits = 2) => string`     | Compact day/hour/minute duration, e.g. `"3d 5h"` / `"5h 12m"` / `"12m"`. Zero-value leading units are dropped; `maxUnits` caps how many units render. Em-dash for null/undefined/non-finite. |
-| `fmtPrice`     | `(n: number) => string`                                         | Price with precision that scales to magnitude (more decimals for sub-cent values). |
-| `fmtPct`       | `(n: number, digits = 2) => string`                             | Percentage with explicit sign, e.g. `"+2.50%"`. |
-| `fmtUsd`       | `(v: number) => string`                                         | Signed USD amount with leading sign, e.g. `"+$5.00"`. |
-| `formatJson`   | `(content: string) => string`                                   | Pretty-prints parseable JSON with 2-space indentation; returns anything else verbatim. |
-| `stringifyValue` | `(value: unknown) => string`                                  | Display string for an unknown value: strings pass through, null/undefined → `''`, everything else JSON-serialized (`String()` fallback). |
-### Spec-form helpers
-```ts
-import { buildSpecParams, firstInvalidNumericSpec } from 'mgv-backoffice'
-```
-Value-map helpers for spec-driven forms (the state behind `BaseSpecFields`).
-A spec whose `default` is `null` is treated as OPTIONAL — blank means "knob
-disabled" and passes validation.
-| Function                 | Signature | Returns |
-| ------------------------ | --------- | ------- |
-| `buildSpecParams`        | `(specs: SpecField[] \| undefined, existing: Record<string, SpecFieldValue>) => Record<string, SpecFieldValue>` | Value map seeded from each spec's `default`, keeping non-null overlapping values the caller already has (an existing `null` is re-seeded from the spec's `default`). |
-| `firstInvalidNumericSpec`| `(specs: SpecField[] \| undefined, params: Record<string, SpecFieldValue>) => string \| null` | Label of the first blank / NaN numeric field, or `null` when all numerics are valid. |
-### Profit & loss
-```ts
-import { computePnL } from 'mgv-backoffice'
-import type { PnL, PnLInputs } from 'mgv-backoffice'
-```
-| Function     | Signature                       | Returns |
-| ------------ | ------------------------------- | ------- |
-| `computePnL` | `(row: PnLInputs) => PnL`       | Unrealised mark-to-market PnL in absolute USD and percent. Returns `{ pnlUsd: null, pnlPct: null }` when any input is missing, non-finite, or `buyPrice <= 0` / `lastPrice <= 0`. |
-```ts
-interface PnLInputs {
-  buyPrice: number | string | null | undefined
-  lastPrice: number | string | null | undefined
-  filledQty: number | string | null | undefined
-}
-interface PnL {
-  pnlUsd: number | null
-  pnlPct: number | null
-}
-```
-```ts
-computePnL({ buyPrice: 100, lastPrice: 110, filledQty: 5 })
-// { pnlUsd: 50, pnlPct: 10 }
-```
----
-## Layout & shells (Tier 2 — full backoffice chrome)
-### BaseAppLayout
-Root layout: dark/light page background, skip link, `<main>`-with-inert wrapper.
-The `<main>` content offset tracks the sidebar width automatically —
-`lg:ml-60` when expanded, `lg:ml-16` when collapsed (via `useSidebarCollapse()`) —
-and adds `pt-14 lg:pt-0` for the mobile top bar while the sidebar is shown.
-**Props:**
-| Prop | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
-| `showSidebar` | `Boolean` | `true` | Render the `sidebar` slot. Set false for full-bleed pages. |
-| `skipLinkLabel` | `String` | `'Skip to main content'` | Label for the accessibility skip link. |
-**Slots:** `sidebar`, `default` (page content).
-```vue
-<BaseAppLayout :show-sidebar="route.name !== 'presentation'">
-  <template #sidebar><AppSidebar /></template>
-  <RouterView />
-</BaseAppLayout>
-```
-### BaseSidebar
-Responsive sidebar with desktop fixed-positioning and mobile off-canvas
-behavior, focus management, optional theme toggle, a desktop collapse
-toggle (icon-only rail), an optional notifications bell, and configurable
-nav sections.
-**Props:**
-| Prop | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
-| `sections` | `NavSection[]` | **required** | Grouped nav items. |
-| `homeRouteName` | `String` | `'home'` | Route name for the logo / "go home" click. |
-| `appName` | `String` | `''` | Optional app name in the footer. |
-| `version` | `String` | `''` | Optional version string in the footer. |
-| `showThemeToggle` | `Boolean` | `true` | Toggle the dark/light switch in the footer. |
-| `collapsible` | `Boolean` | `true` | Show the desktop collapse toggle that shrinks the sidebar to an icon-only rail. |
-| `showNotifications` | `Boolean` | `false` | Show the notifications bell (with unread badge) that toggles `BaseNotificationPanel`. |
-> **Collapse state** is shared via `useSidebarCollapse()` (and persisted to
-> localStorage) so `BaseAppLayout` can shrink the content offset from
-> `lg:ml-60` to `lg:ml-16` in step with the rail. Collapsing only affects
-> desktop (`lg+`); on mobile the sidebar stays a full off-canvas panel.
-> **Notifications:** set `:show-notifications="true"` to render the bell,
-> then drop a [`BaseNotificationPanel`](#basenotificationpanel) in your app.
-> Both share state through `useNotifications()`, so the unread badge and the
-> panel stay in sync.
-**Slots:**
-| Slot     | Slot props | Description |
-| -------- | ---------- | ----------- |
-| `logo`   | `{ size }` | Brand logo. Receives a `size` hint (28px in mobile bar, 52px in expanded sidebar, 36px in the collapsed rail). |
-| `status` | —          | Footer status row (e.g. health indicator, sync state). |
-| `footer` | —          | Replaces the default `appName` + `v{version}` line. |
-**Types:**
-```ts
-import type { NavItem, NavSection } from 'mgv-backoffice'
-interface NavItem {
-  name: string       // Vue Router route name
-  label: string      // display text
-  icon: Component    // typically a Heroicon
-}
-interface NavSection {
-  title: string
-  items: NavItem[]
-}
-```
-```vue
-<BaseSidebar :sections="navSections" home-route-name="projects" app-name="WireMate UI" :version="appVersion">
-  <template #logo="{ size }"><WireMateLogo :size="size" /></template>
-  <template #status>
-    <HealthIndicator />
-  </template>
-</BaseSidebar>
-```
----
-### BaseSidebarUser
-Signed-in user block for the `BaseSidebar` `footer` slot: initials avatar,
-name and email (a link to the profile page when `to` is set) and a Logout
-button that emits `logout`.
-**Props:** `name` (required), `email`, `to` (profile route), `showLogout` (`true`),
-`logoutLabel` (`'Logout'`), `profileLabel` (`'View profile'`, tooltip).
-**Emits:** `logout`.
-```vue
-<BaseSidebar :sections="nav">
-  <template #footer>
-    <BaseSidebarUser :name="me.username" :email="me.email" :to="{ name: 'Profile' }" @logout="logOut" />
-  </template>
-</BaseSidebar>
-```
-### BaseNotificationPanel
-Left-anchored notification drawer (teleported to `<body>`, slides in from
-the left, backdrop + Escape to close). Open/close state and the list live
-in `useNotifications()`, so the sidebar bell and the panel stay in sync.
-Enable the bell on the sidebar with `:show-notifications="true"`, drop one
-`<BaseNotificationPanel />` anywhere in your app, and feed it data via the
-composable.
-**Props:**
-| Prop              | Type      | Default                        | Description |
-| ----------------- | --------- | ------------------------------ | ----------- |
-| `title`           | `String`  | `'Notifications'`              | Panel heading. |
-| `emptyText`       | `String`  | `'You have no notifications.'` | Shown when the list is empty. |
-| `showMarkAllRead` | `Boolean` | `true`                         | Render the "Mark all as read" action when there are unread items. |
-**Emits:** `select` (the clicked notification's `id`; the row is also marked read).
-```vue
-<script setup lang="ts">
-import { BaseNotificationPanel, useNotifications } from 'mgv-backoffice'
-const { setNotifications } = useNotifications()
-setNotifications([
-  { id: 1, title: 'New comment', message: 'Alice replied to your post', time: '2m ago', type: 'info' },
-  { id: 2, title: 'Build passed', time: '1h ago', read: true, type: 'success' },
-])
-</script>
-<template>
-  <BaseSidebar :sections="navSections" :show-notifications="true" />
-  <BaseNotificationPanel @select="(id) => goTo(id)" />
-</template>
-```
-```ts
-import type { NotificationItem } from 'mgv-backoffice'
-interface NotificationItem {
-  id: string | number
-  title: string
-  message?: string
-  time?: string                                   // pre-formatted by you
-  read?: boolean
-  type?: 'info' | 'success' | 'warning' | 'error' // status dot colour
-}
-```
----
-## Authentication
-### BaseGoogleSignInButton
-Google-branded "Sign in with Google" button (official multi-colour "G",
-dark-mode surface swap). Purely presentational — it runs no OAuth itself;
-listen on `click` and start your own Google Identity / Firebase / backend
-flow there.
-**Props:**
-| Prop       | Type      | Default                    | Description |
-| ---------- | --------- | -------------------------- | ----------- |
-| `label`    | `String`  | `'Sign in with Google'`    | Button text. |
-| `loading`  | `Boolean` | `false`                    | Disables and shows a spinner. |
-| `disabled` | `Boolean` | `false`                    | Disables without the spinner. |
-| `block`    | `Boolean` | `true`                     | Full-width layout. |
-**Emits:** `click` (only when not disabled/loading).
-### BaseLoginForm
-Presentational sign-in card: email + password (with show/hide), an optional
-"Remember me" checkbox, an error banner, the Google button + "or" divider,
-and `logo` / `forgot` / `footer` slots. Owns its input state and emits
-`submit` / `google-sign-in`; the app handles the actual request and feeds
-back `loading` / `error`.
-**Props:**
-| Prop            | Type      | Default     | Description |
-| --------------- | --------- | ----------- | ----------- |
-| `title`         | `String`  | `'Sign in'` | Card heading. |
-| `subtitle`      | `String`  | `''`        | Muted line under the heading. |
-| `submitLabel`   | `String`  | `'Sign in'` | Submit button text. |
-| `loading`       | `Boolean` | `false`     | Disables the form, spinner on submit. |
-| `googleLoading` | `Boolean` | `false`     | Disables the form, spinner on the Google button. |
-| `error`         | `String`  | `''`        | Error banner above the form. |
-| `showGoogle`    | `Boolean` | `true`      | Render the Google button + divider. |
-| `showRemember`  | `Boolean` | `false`     | Render the "Remember me" checkbox. |
-**Emits:** `submit` (`LoginCredentials`), `google-sign-in`.
-**Slots:** `logo`, `forgot` (next to the password label), `footer`.
-```vue
-<script setup lang="ts">
-import { BaseLoginForm } from 'mgv-backoffice'
-import type { LoginCredentials } from 'mgv-backoffice'
-async function onSubmit(creds: LoginCredentials) { /* call your API */ }
-function onGoogle() { /* start Google OAuth */ }
-</script>
-<template>
-  <BaseLoginForm
-    subtitle="Welcome back"
-    :show-remember="true"
-    @submit="onSubmit"
-    @google-sign-in="onGoogle"
-  >
-    <template #logo><MyLogo /></template>
-    <template #forgot><a href="/forgot" class="text-sm text-emerald-600">Forgot?</a></template>
-    <template #footer>No account? <a href="/signup" class="text-emerald-600">Sign up</a></template>
-  </BaseLoginForm>
-</template>
-```
----
-## Modals & sections
-### BaseModalShell
-Shared modal chrome — `Teleport` to body, backdrop, themed card, escape key,
-aria-modal. Compose this rather than building modals from scratch.
-**Props:**
-| Prop            | Type      | Default     | Description |
-| --------------- | --------- | ----------- | ----------- |
-| `title`         | `String`  | **required** | Modal heading. |
-| `icon`          | `Component` | **required** | Heroicon rendered in a tinted circular chip left of the title (the `icon` slot can override the whole chip). |
-| `iconBgClass`   | `String`  | `''`        | Background classes of the icon chip; empty falls back to the emerald tint (dark-mode aware). |
-| `iconClass`     | `String`  | `'text-emerald-600'` | Classes applied to the icon itself. |
-| `maxWidthClass` | `String`  | `'max-w-md'` | Tailwind max-w utility for the card. |
-| `manualClose`   | `Boolean` | `false`     | If true, backdrop click and Escape do NOT auto-emit `cancel`. |
-| `scrollable`    | `Boolean` | `false`     | Switch to the large-content layout: a flex column capped at `90vh` with a fixed header/footer and a scrolling body. |
-| `subtitle`      | `String`  | `''`        | Muted line under the title (scrollable layout only). |
-**Slots:** `icon`, `default`, `footer`, and (scrollable layout) `header-actions` — content on the right of the header, e.g. a close button.
-**Events:** `cancel`, `backdrop`.
-### BaseConfirmModal
-Confirmation dialog built on `BaseModalShell`. Variant chooses red (danger) or
-amber (warning) styling.
-**Props:** `title`, `message`, `confirmText`, `cancelText`, `submittingText`,
-`variant: 'danger' | 'warning'`, `submitting`. While `submitting` is true,
-backdrop clicks and Escape stop dismissing the dialog.
-**Slots:** `message` — rich markup replacing the plain `message` string;
-`default` — extra content below the message (warning banner, opt-in checkbox).
-**Events:** `confirm`, `cancel`.
-### BaseTextInputModal
-"Ask the user for a single string and confirm" dialog. Preserves typed input
-on stray backdrop clicks; Escape always cancels.
-**Props:** `title`, `message`, `initialValue`, `placeholder`, `inputLabel`,
-`confirmText`, `cancelText`, `submittingText`, `submitting`.
-**Slots:** `icon` — override the default emerald document icon.
-**Events:** `confirm(value: string)`, `cancel`.
-### BaseEntityPickerModal
-Searchable "pick one from a list" dialog. Pass `items` directly or an async
-`loader` that runs on mount.
-**Props:** `title`, `message?`, `items?: EntityPickerItem[]`,
-`loader?: () => Promise<EntityPickerItem[]>`, `excludeId?`,
-`variant: 'emerald' | 'purple' | 'blue' | 'red' | 'amber'`,
-`searchPlaceholder`, `emptyMessage`, `noMatchMessage`, `confirmText`,
-`cancelText`, `submittingText`, `submitting`.
-**Slots:** `icon` — override the default icon chip.
-**Events:** `confirm(itemId: string)`, `cancel`.
-```ts
-interface EntityPickerItem { id: string; label: string }
-```
-### BaseCollapsibleSection
-Section wrapper with a clickable header, optional badge, and a `default` slot
-for the body. Parent owns the `collapsed` state.
-**Props:** `title`, `collapsed`, `badge?`, `bodyClass?`.
-**Events:** `toggle`.
-### BaseNotFoundPage
-Drop-in 404 view.
-**Props:** `code` (`'404'`), `message` (`'Page not found'`),
-`homeRouteName` (`'home'`), `homeLabel` (`'Go home'`).
-### BasePageHeader
-Page-level header: icon badge + title/subtitle on the left, action
-buttons on the right. Gives top-level views a consistent header shape
-and width. The icon badge only renders when the `icon` slot is filled,
-so icon-less apps get a plain title/subtitle header.
-**Props:**
-| Prop            | Type     | Default       | Description |
-| --------------- | -------- | ------------- | ----------- |
-| `title`         | `String` | **required**  | H1 text. |
-| `subtitle`      | `String` | `''`          | Muted line below the title. |
-| `iconColor`     | `String` | `'emerald'`   | Badge + icon colour: `'emerald' \| 'sky' \| 'red' \| 'amber'`. |
-| `maxWidthClass` | `String` | `'max-w-4xl'` | Tailwind max-w utility constraining header width. Pass `''` to skip the width wrapper entirely — the header then spans its container. |
-| `align`         | `String` | `'center'`    | Vertical alignment of the title block vs the actions: `'center'` or `'end'` (actions sit on the title baseline). |
-| `marginClass`   | `String` | `'mb-8'`      | Space under the header. Pass `''` when the parent manages vertical rhythm (`space-y-*`). |
-| `accent`        | `Boolean` | `false`       | Brand-green gauge bar in front of the title (icon-less headers). |
-**Slots:**
-| Slot       | Slot props        | Description |
-| ---------- | ----------------- | ----------- |
-| `icon`     | `{ iconClass }`   | Page Heroicon. Bind `:class="iconClass"` for the theme-aware colour. Badge square renders only when this slot is filled. |
-| `subtitle` | —                 | Rich subtitle content (links, `<strong>`, interpolation); overrides the `subtitle` prop. |
-| `actions`  | —                 | Buttons rendered on the right (refresh, destructive, etc.). |
-```vue
-<template>
-  <BasePageHeader title="Request Journal" subtitle="Recent matched requests" icon-color="sky">
-    <template #icon="{ iconClass }">
-      <DocumentTextIcon class="w-5 h-5" :class="iconClass" />
-    </template>
-    <template #actions>
-      <BaseButton description="Refresh" @click="reload" />
-    </template>
-  </BasePageHeader>
-</template>
-<script setup lang="ts">
-import { BasePageHeader, BaseButton } from 'mgv-backoffice'
-import { DocumentTextIcon } from '@heroicons/vue/24/outline'
-</script>
-```
----
-### BaseToolbarButton
-Bordered toolbar button — the "Refresh / Delete All" row that sits under
-a page header. Optional leading icon (via slot) plus a label.
-**Props:**
-| Prop       | Type      | Default     | Description |
-| ---------- | --------- | ----------- | ----------- |
-| `label`    | `String`  | `''`        | Button text. Omit for an icon-only button. |
-| `variant`  | `String`  | `'neutral'` | `'neutral'` (grey), `'danger'` (solid red) or `'ghost'` (slate h-9 outline — toolbar/modal-footer buttons). |
-| `disabled` | `Boolean` | `false`     | Greys out and blocks the click. |
-| `title`    | `String`  | `undefined` | Native tooltip / a11y text. |
-| `type`     | `String`  | `'button'`  | Native button type. |
-**Slots:**
-| Slot   | Slot props      | Description |
-| ------ | --------------- | ----------- |
-| `icon` | `{ iconClass }` | Leading Heroicon. Bind `:class="iconClass"` (`w-4 h-4`); add state classes as needed. |
-**Emits:** `click` (native `MouseEvent`).
-```vue
-<template>
-  <BaseToolbarButton label="Refresh" :disabled="isLoading" title="Refresh" @click="reload">
-    <template #icon="{ iconClass }">
-      <ArrowPathIcon :class="[iconClass, { 'animate-spin': isLoading }]" />
-    </template>
-  </BaseToolbarButton>
-  <BaseToolbarButton label="Delete All" variant="danger" @click="deleteAll">
-    <template #icon="{ iconClass }">
-      <TrashIcon :class="iconClass" />
-    </template>
-  </BaseToolbarButton>
-</template>
-```
----
-### BaseActionButton
-Compact ghost action button — the colour-coded "Edit / Logs / Stub /
-Delete" actions on a card footer or action row. No border/fill at rest;
-a tinted hover background keyed to the semantic colour.
-**Props:**
-| Prop        | Type      | Default     | Description |
-| ----------- | --------- | ----------- | ----------- |
-| `label`     | `String`  | `''`        | Button text. Omit for an icon-only button. |
-| `color`     | `String`  | `'emerald'` | `'emerald' \| 'sky' \| 'indigo' \| 'teal' \| 'purple' \| 'red' \| 'amber' \| 'amberStrong'`. |
-| `disabled`  | `Boolean` | `false`     | Dims via opacity and suppresses the hover tint. |
-| `fullWidth` | `Boolean` | `false`     | Stretch to fill its flex row (`flex-1`). |
-| `title`     | `String`  | `undefined` | Native tooltip. |
-| `ariaLabel` | `String`  | `undefined` | Accessible label. |
-| `type`      | `String`  | `'button'`  | Native button type. |
-**Slots:**
-| Slot   | Slot props      | Description |
-| ------ | --------------- | ----------- |
-| `icon` | `{ iconClass }` | Leading Heroicon. Bind `:class="iconClass"` (`w-4 h-4`). |
-**Emits:** `click` (native `MouseEvent`).
-```vue
-<template>
-  <BaseActionButton label="Edit" color="emerald" full-width title="Edit this mock" @click="edit">
-    <template #icon="{ iconClass }">
-      <PencilSquareIcon :class="iconClass" />
-    </template>
-  </BaseActionButton>
-  <BaseActionButton label="Delete" color="red" @click="remove">
-    <template #icon="{ iconClass }">
-      <TrashIcon :class="iconClass" />
-    </template>
-  </BaseActionButton>
-</template>
-```
----
-### BaseCopyButton
-Copy-to-clipboard icon button with transient "copied" feedback — clicks
-write `text` to the clipboard, swap the clipboard icon for a checkmark
-for `resetMs`, then revert. Uses the async Clipboard API with a
-hidden-textarea `execCommand` fallback for insecure origins. Emits
-`copied` / `error` so the parent can fire its own toast.
-**Props:**
-| Prop        | Type      | Default   | Description |
-| ----------- | --------- | --------- | ----------- |
-| `text`      | `String`  | **required** | Value written to the clipboard. |
-| `label`     | `String`  | `''`      | Used in the tooltip / aria-label (`Copy {label}`). |
-| `variant`   | `String`  | `'ghost'` | `'ghost'` (borderless `p-1` icon) or `'bordered'` (`w-9 h-9` boxed, turns emerald while copied). |
-| `resetMs`   | `Number`  | `1500`    | How long the checkmark stays before reverting. |
-| `iconClass` | `String`  | `'w-4 h-4'` | Icon size class. |
-**Emits:** `copied`, `error(err)`.
-```vue
-<template>
-  <!-- Inline ID copy, parent fires the toast -->
-  <BaseCopyButton
-    :text="stub.id"
-    label="Stub ID"
-    @copied="showToastMessage('Stub ID copied to clipboard', BaseToastEnum.SUCCESS)"
-    @error="showToastMessage('Failed to copy stub ID', BaseToastEnum.ERROR)"
-  />
-  <!-- Boxed copy next to a read-only input -->
-  <BaseCopyButton :text="mock.id" label="Mock ID" variant="bordered" :reset-ms="2000" />
-</template>
-<script setup lang="ts">
-import { BaseCopyButton, BaseToastEnum } from 'mgv-backoffice'
-</script>
-```
----
-### BaseChipButton
-Small tinted emerald "chip" action button — the compact "+ Add" pill used
-above repeatable form rows. Label comes from the default slot.
-**Props:**
-| Prop       | Type      | Default | Description |
-| ---------- | --------- | ------- | ----------- |
-| `size`     | `String`  | `'sm'`  | `'sm'` = `px-2.5 py-1`; `'xs'` = `px-2 py-0.5` for tight corners. |
-| `disabled` | `Boolean` | `false` | Dims the chip and blocks clicks. |
-**Emits:** `click`.
-```vue
-<BaseChipButton @click="addRow(rows)">+ Add</BaseChipButton>
-<BaseChipButton size="xs" @click="addNamespace">+ Add</BaseChipButton>
-```
----
-### BaseRemoveButton
-The red "×" remove-row affordance used beside repeatable form rows. Name it
-for screen readers via `aria-label`; `title`, `disabled` and extra classes
-(`pt-1`, `self-start`, …) fall through as attrs.
-**Emits:** `click`.
-```vue
-<BaseRemoveButton :aria-label="`Remove header ${i + 1}`" @click="rows.splice(i, 1)" />
-```
----
-### BaseStatusPill
-Connection/health status pill: a colored dot (pulsing while `ok`) next to a
-short label on a tinted background.
-**Props:**
-| Prop     | Type     | Default | Description |
-| -------- | -------- | ------- | ----------- |
-| `status` | `String` | **required** | `'ok'` (emerald, pulsing), `'error'` (red), `'unknown'` (gray). |
-| `label`  | `String` | **required** | Short text next to the dot, e.g. `WireMock Connected`. |
-```vue
-<BaseStatusPill :status="healthy ? 'ok' : 'error'" :label="healthy ? 'Connected' : 'Disconnected'" />
-```
----
-### BaseFileDropzone
-Dashed "click to select a file" upload zone (extracted from WireMate's
-Postman-import modal). Renders a document-arrow-up icon (overridable via the
-`#icon` slot), a label line, and an optional dimmed hint line. Clicking opens
-the native file picker; dragging files onto the zone also works (the border
-highlights emerald while dragging). The hidden input resets after every
-selection, so picking the same file twice still emits.
-**Props:**
-| Prop       | Type      | Default | Description |
-| ---------- | --------- | ------- | ----------- |
-| `label`    | `String`  | **required** | Main line, e.g. `Click to select a Postman collection (.json)`. |
-| `hint`     | `String`  | `''`    | Dimmed helper line below the label. |
-| `accept`   | `String`  | `''`    | Forwarded to the input's `accept`. Dropped files are **not** filtered by it. |
-| `multiple` | `Boolean` | `false` | Allow multi-select; when `false`, a multi-file drop emits only the first file. |
-| `disabled` | `Boolean` | `false` | Dims the zone and ignores clicks/drops. |
-**Emits:** `files` (`File[]`, never empty).
-**Slots:** `icon` — replaces the default upload icon.
-```vue
-<BaseFileDropzone
-  accept="application/json,.json"
-  label="Click to select a Postman collection (.json)"
-  hint="Exported from Postman → Export → Collection v2.1"
-  @files="onFiles"
-/>
-```
-### BaseCodeBlock
-Themed monospace `<pre>` for JSON payloads, request dumps and code snippets
-(extracted from WireMate's stub/request detail views). Preserves whitespace
-verbatim, scrolls both axes, and adapts to the theme. Extra classes (margins
-etc.) fall through via the normal class merge.
-**Props:**
-| Prop             | Type     | Default  | Description |
-| ---------------- | -------- | -------- | ----------- |
-| `code`           | `String` | **required** | The raw text to render. |
-| `variant`        | `String` | `'soft'` | `'soft'` = tinted fill, no border (in-card look); `'bordered'` = bordered card fill (standalone look). |
-| `size`           | `String` | `'sm'`   | `'sm'` = `text-sm px-5 py-4`; `'xs'` = dense `text-xs p-3`. |
-| `maxHeightClass` | `String` | `''`     | Optional Tailwind max-height utility, e.g. `max-h-96`. |
-```vue
-<BaseCodeBlock :code="formatJson(response.body)" size="xs" max-height-class="max-h-64" />
-```
----
-## Forms & tables
-These components use `dark:` Tailwind variants, so the consuming app must map
-the `dark` variant to the `.dark` class that `useTheme()` toggles (see
-[Tailwind setup for consumers](#tailwind-setup-for-consumers)).
-### BaseInput
-Themed text/number input carrying the shared field skin (slate border,
-`bg-slate-50` / dark `bg-slate-900` surface). Everything else — `placeholder`,
-`id`, `disabled`, `step`/`min`, extra classes like `font-mono` or
-`placeholder:*` — falls through via attrs and Vue class merging.
-**Props:**
-| Prop         | Type               | Default  | Description |
-| ------------ | ------------------ | -------- | ----------- |
-| `modelValue` | `String \| Number \| null` | `''`     | `v-model` value. |
-| `type`       | `String`           | `'text'` | Native input type. |
-| `size`       | `String`           | `'md'`   | `'md'` = `px-3 py-2`, `'sm'` = `px-2 py-1.5`. |
-| `block`      | `Boolean`          | `true`   | Full-width (`w-full`); set `false` for inline fields. |
-**Emits:** `update:modelValue(value: string)` — always the raw string; parse
-numbers in the owner.
-```vue
-<BaseInput v-model="query" placeholder="e.g. AMD or BTC" class="font-mono" />
-```
-### BaseSelect
-Themed `<select>` sharing BaseInput's field skin. Options come from the
-default slot so callers keep full control of `<option>` rendering.
-**Props:**
-| Prop         | Type               | Default | Description |
-| ------------ | ------------------ | ------- | ----------- |
-| `modelValue` | `String \| null`   | `undefined` | `v-model` value. When left undefined the browser keeps its own default selection. |
-| `size`       | `String`           | `'sm'`  | `'sm'` = `px-2 py-1.5`, `'md'` = `px-3 py-2`. |
-| `block`      | `Boolean`          | `true`  | Full-width; set `false` for inline selects. |
-**Slots:** `default` — the `<option>` elements.
-**Emits:** `update:modelValue(value: string)`.
-```vue
-<BaseSelect v-model="strategyType">
-  <option v-for="e in catalog" :key="e.type" :value="e.type" :title="e.description">
-    {{ e.label }}
-  </option>
-</BaseSelect>
-```
-### BaseDropdown
-Button-style single-select dropdown ("Select Social User ⌄"). Unlike
-`BaseSelect` (a native `<select>`), this renders a trigger button plus a
-floating menu, so the closed control shows a placeholder and a chevron that
-rotates while open — matching the app's filter dropdowns. Selecting a row
-emits its `value` and closes the menu; Escape and an outside click also close
-it.
-**Props:**
-| Prop          | Type                       | Default      | Description |
-| ------------- | -------------------------- | ------------ | ----------- |
-| `options`     | `DropdownOption[]`         | **required** | `{ value, label, title?, disabled? }` per row. |
-| `modelValue`  | `String \| Number \| null` | `null`       | Selected option's `value` (`v-model`). |
-| `placeholder` | `String`                   | `'Select'`   | Trigger text shown when nothing is selected. |
-| `size`        | `String`                   | `'md'`       | `'md'` = `px-4 py-2.5` (app filter height), `'sm'` = `px-3 py-2`. Ignored when `triggerClass` is set. |
-| `block`       | `Boolean`                  | `true`       | Full-width; set `false` for an inline, content-width dropdown. |
-| `disabled`    | `Boolean`                  | `false`      | Disables the trigger. |
-| `ariaLabel`   | `String`                   | `''`         | Accessible name for the trigger/listbox when there is no visible label. |
-| `triggerClass`| `String`                   | `''`         | Replaces the trigger's default slate skin entirely (including the `size` padding). |
-| `chevronClass`| `String`                   | `'w-5 h-5 text-slate-500 dark:text-slate-400'` | Classes for the chevron icon. |
-**Emits:** `update:modelValue(value)`.
-```vue
-<BaseDropdown
-  v-model="socialUserId"
-  :options="socialUsers.map((u) => ({ value: u.id, label: u.name }))"
-  placeholder="Select Social User"
-  aria-label="Social user"
-/>
-```
-### BaseDateTimePicker
-Date / date-time / time picker built on
-[@vuepic/vue-datepicker](https://vue3datepicker.com). The package is a regular
-dependency of this lib (installed automatically) and its CSS ships inside
-`ui-lib.css`, so consumers install and import nothing extra. Dark mode follows
-`useTheme()`; the skin matches BaseInput (slate surfaces, emerald accent).
-**Props:**
-| Prop         | Type               | Default      | Description |
-| ------------ | ------------------ | ------------ | ----------- |
-| `modelValue` | `ModelValue`       | `null`       | `v-model` value — `Date`, `Date[]` for ranges, a time object in `'time'` mode, or a string/number with `model-type`. |
-| `mode`       | `'date' \| 'datetime' \| 'time'` | `'datetime'` | Calendar only, calendar + time, or time only. |
-| `format`     | `String`           | per mode     | date-fns input pattern. Defaults: `dd/MM/yyyy`, `dd/MM/yyyy HH:mm`, `HH:mm` (`hh:mm a` when `is24` is false). |
-| `is24`       | `Boolean`          | `true`       | 24-hour clock. |
-| `autoApply`  | `Boolean`          | `false`      | Select on click, without the Cancel/Select row. |
-| `teleport`   | `Boolean \| String \| HTMLElement` | `true` | Menu mount target; `true` = body, so modals don't clip it. |
-| `timeConfig` | `Partial<TimeConfig>` | —         | Extra time options (seconds, increments…), merged over the defaults. |
-Every other VueDatePicker prop (`range`, `min-date`, `max-date`,
-`disabled-dates`, `placeholder`, `model-type`, …), event and slot is passed
-straight through.
-**Emits:** `update:modelValue(value)`.
-```vue
-<BaseDateTimePicker v-model="startsAt" placeholder="Start" />
-<BaseDateTimePicker v-model="day" mode="date" :min-date="new Date()" auto-apply />
-<BaseDateTimePicker v-model="period" mode="date" range />
-```
-### BaseSegmentedControl
-Segmented button group ("All | Stock | Crypto"). One button per option; the
-selected one gets the filled treatment and `aria-pressed="true"`.
-**Props:**
-| Prop          | Type                | Default  | Description |
-| ------------- | ------------------- | -------- | ----------- |
-| `options`     | `SegmentedOption[]` | **required** | `{ value, label, title? }` per button. |
-| `modelValue`  | `String \| Number`  | **required** | Selected option's `value` (`v-model`). |
-| `variant`     | `String`            | `'base'` | `'base'` (`px-3 py-2`, emerald-500 fill), `'wide'` (`px-4 py-2`, emerald-600 fill), `'toolbar'` (`h-9` uppercase `text-xs` with focus-visible rings). |
-| `ariaLabel`   | `String`            | `''`     | When set, the wrapper renders `role="group"` + `aria-label`. |
-| `optionClass` | `Function`          | —        | `(option, active) => string` override for per-button fill classes (e.g. severity colours); layout stays owned by the variant. |
-**Emits:** `update:modelValue(value)`.
-```vue
-<BaseSegmentedControl v-model="assetFilter" :options="ASSET_FILTERS" />
-<BaseSegmentedControl v-model="exchange" :options="EXCHANGES" variant="wide" aria-label="Exchange" />
-```
-### BaseTable
-Styling shell for data tables — **not** a data grid. Owns the table skin
-(slate header band, `px-4 py-3` header cells, row dividers + hover, empty-state
-row); body rows are the caller's own `<tr>` markup via the default slot. Pass
-`card` for the rounded, bordered, horizontally scrolling card chrome, or wrap
-it yourself (e.g. a `BaseRow` with `overflow-x-auto`).
-**Props:**
-| Prop        | Type            | Default      | Description |
-| ----------- | --------------- | ------------ | ----------- |
-| `columns`   | `TableColumn[]` | **required** | `{ label, align? }`; `align: 'right'` right-aligns the header cell. |
-| `empty`     | `Boolean`       | `false`      | True renders the empty-state row spanning every column. |
-| `emptyText` | `String`        | `'No rows.'` | Fallback empty-state text. |
-| `card`      | `Boolean`       | `false`      | Wrap in the rounded, bordered, scrolling card. |
-**Slots:** `default` — the `<tr>` rows; `empty` — custom empty-state content.
-```vue
-<BaseTable :columns="COLUMNS" :empty="rows.length === 0">
-  <template #empty>No trades match your filters.</template>
-  <tr v-for="row in rows" :key="row.id" class="border-t border-slate-200 dark:border-slate-700">
-    …
-  </tr>
-</BaseTable>
-```
-### BaseSpecFields
-Spec-driven form fields: renders a select / checkbox / number input per
-`SpecField`, with labels and help text, in a responsive two-column grid. Feed
-it a backend-described catalogue and every form editing those values stays in
-lockstep. Never mutates `params` — every edit is emitted as `(key, value)`
-and the owner writes it back into its own state.
-**Props:**
-| Prop     | Type                             | Default      | Description |
-| -------- | -------------------------------- | ------------ | ----------- |
-| `specs`  | `SpecField[]`                    | **required** | `{ key, label, type: 'decimal' \| 'integer' \| 'boolean' \| 'select', default?, options?, step?, min?, help? }` (optional members are nullable). |
-| `params` | `Record<string, SpecFieldValue>` | **required** | Current values keyed by `spec.key`. |
-**Slots:** `after` (`{ spec }`) — extra content under each field (e.g. a live
-preview attached to one key).
-**Emits:** `update(key: string, value: SpecFieldValue)` — numbers are parsed
-(`parseFloat`); unparseable input passes through raw so the owner's
-validation can catch it.
-```vue
-<BaseSpecFields :specs="entry.params" :params="form.params"
-  @update="(key, value) => (form.params[key] = value)" />
-```
-### BaseStatBreakdown
-Compact per-item breakdown meant to sit under a summary/stat card (pairs with
-[`EarningsCard`](#earningscard)). Each item renders on its own line — label
-left, value right in monospace. A `null`/`undefined` value (a source that is
-unconfigured, unreachable, or has no matching rows) shows an em-dash rather
-than a misleading 0. With `signed`, values gain an explicit "+" and are
-coloured green/red by sign (same `"-$3.00"` / `"+$5.00"` shape as `fmtUsd`).
-**Props:**
-| Prop       | Type                  | Default      | Description |
-| ---------- | --------------------- | ------------ | ----------- |
-| `items`    | `StatBreakdownItem[]` | **required** | `{ label, value }` per row. |
-| `currency` | `String`              | `''`         | Currency symbol placed after the sign, e.g. `'$'`. |
-| `decimals` | `Number`              | `2`          | Fraction digits shown for each value. |
-| `signed`   | `Boolean`             | `false`      | Show an explicit "+" on non-negative values and colour rows green/red by sign. |
-```ts
-import type { StatBreakdownItem } from 'mgv-backoffice'
-interface StatBreakdownItem {
-  label: string                      // row label rendered on the left
-  value: number | null | undefined   // null/undefined renders as an em-dash
-}
-```
-```vue
-<EarningsCard title="TOTAL P&L" :amount="totalPnl" signed />
-<BaseStatBreakdown
-  :items="[
-    { label: 'Alpaca', value: 42.5 },
-    { label: 'Binance', value: -3.1 },
-    { label: 'Kraken', value: null },
-  ]"
-  currency="$"
-  signed
-/>
-```
-### BaseFilterChip
-Colour-coded toggleable filter chip — one-click event/category filters above
-a data feed. Idle renders a tinted border/background in the semantic colour;
-active renders a solid fill with white text (`aria-pressed` reflects the
-state). Layout classes (`h-9 flex-1`, …) pass through the class attribute;
-click handlers bind natively on the component.
-**Props:**
-| Prop       | Type      | Default   | Description |
-| ---------- | --------- | --------- | ----------- |
-| `label`    | `String`  | `''`      | Chip text; the default slot overrides it. |
-| `color`    | `'emerald' \| 'sky' \| 'amber' \| 'red' \| 'slate'` | `'slate'` | Semantic colour of the idle tint and active fill. |
-| `active`   | `Boolean` | `false`   | Whether the chip's filter is applied (solid fill). |
-| `disabled` | `Boolean` | `false`   | Greys out + blocks the click. |
-| `title`    | `String`  | —         | Native tooltip. |
-```vue
-<BaseFilterChip
-  v-for="f in filters"
-  :key="f.key"
-  class="h-9 flex-1"
-  :color="f.color"
-  :active="isActive(f)"
-  :title="f.title"
-  @click="toggle(f)"
->{{ f.label }}</BaseFilterChip>
-```
-### BaseCredentialsForm
-One service's API-credentials card: key id + secret + base/data URLs, with
-the has-secret handling (placeholder dots, blank-keeps-stored-secret), the
-save-validation ladder and a saving spinner. Load/save results are EMITTED —
-the parent owns toasts / error banners. Exposes `load()` so a parent Reload
-button can re-pull several cards in parallel.
-**Props:** `title` + `idPrefix` + `fetchFn: () => Promise<CredentialsView>` +
-`updateFn: (body: CredentialsUpdate) => Promise<CredentialsView>` +
-`defaults: { baseUrl, dataUrl }` (required); `subtitle`, `keyLabel`,
-`keyPlaceholder`, `secretLabel`, `secretPlaceholder`, `secretSetHint`,
-`permissionsHint`, `requiredKeyMessage`, `requiredSecretMessage`,
-`savedMessage`, `saveLabel` (optional copy overrides).
-**Slots:** `no-secret-hint` — rich help while no secret is stored;
-`base-url-extra` (`{ form }`) — extras under the Base URL field (e.g.
-live/paper shortcut buttons that write into the form); `footer` — extra
-content at the card's bottom.
-**Emits:** `saved(message)`, `error(message)`, `load-error(message)`.
-```vue
-<BaseCredentialsForm
-  ref="card"
-  title="Alpaca API"
-  id-prefix="alpaca"
-  :fetch-fn="fetchAlpaca"
-  :update-fn="updateAlpaca"
-  :defaults="{ baseUrl: LIVE_BASE, dataUrl: DATA_URL }"
-  @saved="onSaved"
-  @error="onError"
-  @load-error="onLoadError"
-/>
-```
----
-### BasePillPickerModal
-"Pick one of many" modal: every item rendered as a clickable pill, narrowed
-by a free-text filter and an optional segmented group toggle. Clicking a pill
-emits `pick` with the item; backdrop / Escape / the footer Close emit `close`.
-Narrowing state lives inside, so a `v-if`-mounted instance always opens fresh.
-**Props:** `title` + `items: PillPickerItem[]` (required);
-`groups?: SegmentedOption<string>[]` (renders the group toggle with an
-`allLabel` option prepended, narrowing by each item's `group`); `icon?`
-(defaults to the magnifying glass), `subtitle?`, `searchPlaceholder`,
-`emptyMessage`, `noMatchMessage`, `mono` (mono font for the filter input and
-pills — symbols, codes, ids), `maxWidthClass` (default `max-w-2xl`),
-`closeText`, `groupAriaLabel`, `allLabel`.
-**Emits:** `pick(item: PillPickerItem)`, `close`.
-```ts
-interface PillPickerItem {
-  id: string      // unique key; identifies the pick
-  label: string   // pill text; what the filter matches
-  group?: string  // segmented-toggle bucket
-  title?: string  // pill tooltip
-}
-```
-```vue
-<BasePillPickerModal
-  v-if="open"
-  title="Symbols"
-  :items="symbols.map(s => ({ id: s.id, label: s.symbol, group: s.assetClass }))"
-  :groups="[{ value: 'STOCK', label: 'STOCK' }, { value: 'CRYPTO', label: 'CRYPTO' }]"
-  mono
-  @pick="apply"
-  @close="open = false"
-/>
-```
----
-### BaseBarDistribution
-Compact value-distribution chart: one thin rounded bar per distinct
-value, count labelled on top and the value underneath — scrolls
-sideways when there are many bars. Pure Tailwind, no chart library.
-Extracted from TradeAutomation's variant-stats modal.
-**Props:**
-| Prop           | Type     | Default                | Description |
-| -------------- | -------- | ---------------------- | ----------- |
-| `bars`         | `Array`  | **required**           | `DistributionBar[]` — `{ label, count }` per bar, in display order (sort ascending for numeric values). |
-| `ariaLabel`    | `String` | `'Value distribution'` | Accessible description of the chart. |
-| `countNoun`    | `String` | `'item'`               | Noun for each bar's tooltip count, e.g. `'variant'` → "3 variants". |
-| `titlePrefix`  | `String` | `''`                   | Tooltip prefix before the value, e.g. the field name. |
-| `maxBarHeight` | `Number` | `56`                   | Height of the tallest bar, in px. |
-| `barClass`     | `String` | emerald fill           | Tailwind classes for the bar fill. |
-```vue
-<BaseBarDistribution
-  :bars="[{ label: '0.5', count: 1 }, { label: '1', count: 4 }]"
-  aria-label="Distribution of Take profit across variants"
-  title-prefix="Take profit"
-  count-noun="variant"
-/>
-```
----
-### BaseSearchSelect
-Searchable select (combobox): type to filter, pick with the mouse or
-ArrowUp/ArrowDown + Enter. `multiple` turns it into a tag picker with removable
-chips (Backspace on an empty search removes the last one). Same field skin as
-`BaseInput` / `BaseSelect`; Escape and an outside click close the menu.
-**Props:**
-| Prop            | Type                          | Default         | Description |
-| --------------- | ----------------------------- | --------------- | ----------- |
-| `options`       | `DropdownOption[]`            | **required**    | `{ value, label, title?, disabled? }` per row. |
-| `modelValue`    | `value \| null \| value[]`    | `null`          | Selected value, or values with `multiple`. |
-| `multiple`      | `Boolean`                     | `false`         | Pick several (chips). |
-| `placeholder`   | `String`                      | `'Select'`      | Shown when nothing is selected. |
-| `searchable`    | `Boolean`                     | `true`          | Typing filters the options. |
-| `clearable`     | `Boolean`                     | `true`          | Show the × clear button while something is selected. |
-| `block`         | `Boolean`                     | `true`          | Full-width. |
-| `disabled`      | `Boolean`                     | `false`         | |
-| `ariaLabel`     | `String`                      | `''`            | Accessible name without a visible label. |
-| `noResultsText` | `String`                      | `'No matches.'` | |
-| `emptyText`     | `String`                      | `'No options.'` | |
-**Emits:** `update:modelValue` — the value (single; `null` when cleared) or the
-array of values (`multiple`).
-```vue
-<BaseSearchSelect v-model="userId" :options="users.map(u => ({ value: u.id, label: u.name }))" placeholder="Select User" />
-<BaseSearchSelect v-model="tags" :options="TAGS" multiple />
-```
-### BaseCard
-Bordered surface card — the shared chrome for forms, filter/search panels and
-grouped content.
-**Props:** `title`, `subtitle`, `padding: 'md' | 'sm' | 'none'` (`'md'`).
-**Slots:** `default` (body), `actions` (header, right), `footer` (bottom, right-aligned — submit/cancel).
-```vue
-<BaseCard title="Template">
-  <form>…</form>
-  <template #footer><BaseButton type="submit" description="Save" /></template>
-</BaseCard>
-```
-### BaseField
-Label + control + message wrapper for forms and filter bars.
-**Props:** `label`, `labelFor` (the control's id), `required`, `error`
-(red, replaces the hint), `hint`, `compact` (small uppercase filter-bar label),
-`grow` (takes the free space in a flex row).
-```vue
-<BaseCard padding="sm">
-  <div class="flex flex-wrap items-end gap-4">
-    <BaseField label="Search symbol" label-for="q" compact grow>
-      <BaseInput id="q" v-model="query" />
-    </BaseField>
-    <BaseField label="Class" compact>
-      <BaseSegmentedControl v-model="cls" :options="CLASSES" />
-    </BaseField>
-  </div>
-</BaseCard>
-```
-### BaseStatCard
-Dashboard stat tile in the `EarningsCard` style (dashed accent border, bold
-title, big value) for any value — counts, labels, pre-formatted numbers.
-**Props:** `title` (required), `value`, `subtitle`,
-`accent: 'emerald' | 'sky' | 'amber' | 'red' | 'slate'` (`'emerald'`),
-`to` (router location — makes the whole card a link).
-**Slots:** `icon` (fills the tinted chip; receives `iconClass`), `default` (extra content).
-```vue
-<BaseStatCard title="Categories" :value="71" accent="sky" :to="{ name: 'Category List' }">
-  <template #icon="{ iconClass }"><SwatchIcon :class="iconClass" /></template>
-</BaseStatCard>
-```
-### BaseCheckbox
-Rounded checkbox, emerald when checked (works with or without a forms plugin).
-`v-model` is the boolean; `change` fires with the new value; attrs (`id`, `name`)
-go to the `<input>`.
-**Props:** `modelValue`, `label`, `disabled`. **Slots:** `default` (rich label).
-**Emits:** `update:modelValue(value)`, `change(value)`.
-```vue
-<BaseCheckbox v-model="remember" id="remember" label="Remember me" />
-```
-### BaseToggle
-On/off switch (`role="switch"`). `v-model` is the boolean; `change` fires after
-every user toggle with the new value.
-**Props:** `modelValue`, `label` (visible label, also the accessible name),
-`ariaLabel` (when there is no label), `color: 'emerald' | 'red' | 'sky' | 'amber'`
-(on state, `'emerald'`), `offTone: 'slate' | 'red'` (off track, `'slate'`), `disabled`.
-**Emits:** `update:modelValue(value)`, `change(value)`.
-```vue
-<BaseToggle v-model="task.alive" :label="task.name" color="red" @change="save(task)" />
-<BaseToggle v-model="account.alive" off-tone="red" aria-label="Alive" />
-```
-### BaseAuthLayout
-Full-page, centred shell for sign-in / sign-up / password-recovery screens:
-logo on top (defaults to `BaseLogo`), then a bordered card with the title,
-content and an optional footer.
-**Props:** `title`, `subtitle`, `wide` (max-w-3xl card for multi-column forms; default max-w-md).
-**Slots:** `default` (form), `logo` (replaces `BaseLogo`), `footer` ("No account? Sign up").
-```vue
-<BaseAuthLayout title="Forgot password">
-  <form>…</form>
-  <template #footer>No account? <RouterLink to="/register">Sign up</RouterLink></template>
-</BaseAuthLayout>
-```
-### BaseBooleanBadge
-Yes/no pill for boolean columns: green check when true, red cross when false.
-**Props:** `value` (`boolean | null`), `trueLabel` (`'Yes'`), `falseLabel` (`'No'`).
-```vue
-<BaseBooleanBadge :value="user.hasVerifiedEmail" true-label="Verified" false-label="Not verified" />
-```
-### BaseDetailList
-Read-only label/value grid for detail pages (the "view" counterpart of a form).
-Empty values show `emptyText`; `href` renders the value as an external link;
-`mono` uses the monospace face.
-**Props:** `items: DetailItem[]` (`{ label, value?, href?, mono? }`, required),
-`columns: 1 | 2 | 3` (`2`, from `sm` up), `emptyText` (`'—'`).
-```vue
-<BaseCard title="Details">
-  <BaseDetailList :items="[{ label: 'Status', value: post.status }, { label: 'Link', value: post.link, href: post.link }]" />
-</BaseCard>
-```
-## Composables
-```ts
-import {
-  initTheme,
-  useTheme,
-  useThemeClasses,
-  useEscapeKey,
-  useDebouncedRef,
-  useToast,
-  useMobileSidebar,
-  useSidebarCollapse,
-  useNotifications,
-  useQueryParamSync,
-  useFieldClasses,
-  usePolling,
-} from 'mgv-backoffice'
-import type {
-  UseThemeOptions,
-  UseSidebarCollapseOptions,
-  UsePollingOptions,
-} from 'mgv-backoffice'
-```
-| Composable | Purpose |
-| ---------- | ------- |
-| `initTheme({ storageKey? })` | Explicitly initialize the theme singleton. Call in your app entry point **before mounting** when you need a custom storage key — library components call `useTheme()` internally, so a component mounting first would otherwise lock in the default key (a dev-mode warning fires if that happens). |
-| `useTheme({ storageKey? })` | Singleton dark/light controller. Toggles `<html class="dark">` and persists via localStorage (default key `'mgv-theme'`). Prefer `initTheme` at app entry for custom keys. |
-| `useThemeClasses()` | Named Tailwind class roles for dark/light (card, border, primaryText, mutedText, dimText, input, ghostButton, emeraldText, redText, …). Since 1.34.0 returns a `reactive` object of plain strings — bind `t.card` directly, never `t.card.value` (the old ComputedRef shape leaked ref internals into `:class` bindings). |
-| `useEscapeKey(handler)` | Component-scoped Escape key listener. |
-| `useDebouncedRef(source, delay?)` | Debounced mirror of a ref. Timer cleared on scope dispose. |
-| `useToast(durationMs?)` | Per-component toast state: `{ showToast, toastMessage, toastType, showToastMessage }`. `showToastMessage` also accepts a per-call duration override. |
-| `useMobileSidebar()` | Singleton state shared between `BaseSidebar` and `BaseAppLayout` for the off-canvas open/closed flag. |
-| `useSidebarCollapse({ storageKey? })` | Singleton collapsed/expanded state for the desktop sidebar rail, shared between `BaseSidebar` and `BaseAppLayout` and persisted to localStorage (default key `'mgv-sidebar-collapsed'`). |
-| `useNotifications()` | Singleton notification state shared by the sidebar bell and `BaseNotificationPanel`: `{ notifications, unreadCount, open, openPanel, closePanel, togglePanel, setNotifications, add, remove, markRead, markAllRead, clear }`. |
-| `useQueryParamSync()` | URL-query mirroring for filterable views: `{ qparam(name), qenum(name, allowed, fallback), replaceQuery(next) }`. Read filters from the query string once on setup, write changes back with `router.replace` (no-op when unchanged) so filtered views stay shareable without polluting history. |
-| `useFieldClasses()` | Shared form-field class strings for the gray/emerald form skin: `{ label, input, requiredInput(value) }`. `requiredInput` returns a red border+ring skin while the value is empty and the standard skin otherwise. |
-| `usePolling(fn, intervalMs, { immediate?, pauseWhenHidden? })` | Visibility-gated polling loop bound to the component lifecycle: starts on mount, stops on unmount, pauses while the tab is hidden and refreshes + resumes on return to visible (both default on). Pass `intervalMs: null` for refresh-only mode (run on mount + each return-to-visible, no timer). Returns `{ start, stop, active }`. A loop stopped via `stop()` stays stopped across hide/show cycles (since 1.36.0) — only a visibility-paused loop auto-resumes. Catch errors inside `fn` — the loop never swallows rejections. |
----
-## Typography
-Since 1.33.0 the library ships the shared brand typography: the stylesheet
-loads **Fira Sans** (UI text) and **Fira Code** (numerals/data) from Google
-Fonts via `@import`, registers them as the Tailwind `--font-sans` /
-`--font-mono` theme defaults, and applies `font-family: var(--font-sans)` to
-`body`. Consumers get the fonts just by importing the lib CSS — remove any
-app-local Google Fonts `<link rel="stylesheet">` and `--font-sans`/`--font-mono`
-overrides. Keep (or add) the preconnect hints in `index.html` for a faster
-first paint:
-```html
-<link rel="preconnect" href="https://fonts.googleapis.com" />
-<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-```
-## Tailwind setup for consumers
-The lib's components rely on Tailwind utility classes (including dark-mode
-variants). Consumers should add the lib's `dist` output to their Tailwind
-`content` paths so the JIT can see the class names:
-```js
-// tailwind.config.js
-export default {
-  content: [
-    './index.html',
-    './src/**/*.{vue,ts}',
-    './node_modules/mgv-backoffice/dist/**/*.{js,mjs,cjs,vue}',
-  ],
-}
-```
-The legacy `tailwind.safelist.js` only covers the v1 components; the
-recommended path for v4+ is the `content` glob above.
+# mgv-backoffice
+Shared Vue 3 UI component library built with TypeScript and Tailwind CSS.
+## Installation
+```bash
+npm install mgv-backoffice
+```
+### Peer Dependencies
+These must be installed in your project:
+```bash
+npm install vue@^3.5.0 vue-router@^5.0.0 @heroicons/vue@^2.0.0
+```
+> `vue-router` 5.x is required (peer range `^5.0.0`) — it's what the library is
+> developed and tested against. Upgrade from Router 4 before installing this library.
+### Import Styles
+Include the library's stylesheet in your app entry point:
+```ts
+import 'mgv-backoffice/dist/style.css'
+```
+### Tailwind Safelist
+If your project uses Tailwind, import the safelist so dynamic classes used by this library are generated correctly:
+```js
+// In your Tailwind config
+import safelist from 'mgv-backoffice/tailwind.safelist'
+```
+Or include the pre-built CSS safelist:
+```css
+@import 'mgv-backoffice/tailwind.safelist.css';
+```
+> Maintainers: `tailwind.safelist.js` is the single source of truth.
+> `tailwind.safelist.css` is generated from it via `npm run safelist`
+> (runs automatically before `npm run build`) — don't edit it by hand.
+---
+## Components
+### BaseAlert
+Inline notice panel with color-coded variants (error / warning / success /
+info), theme-aware via the shared `isDark` ref. The optional default slot
+renders body content under the title, and `compact` gives a slim text-xs
+variant for in-form warnings.
+**Props:**
+| Prop      | Type        | Default            | Description              |
+| --------- | ----------- | ------------------ | ------------------------ |
+| `title`   | `String`    | `''`               | Bold headline (optional when the slot carries the message). |
+| `color`   | `AlertEnum` | `AlertEnum.ERROR`  | Alert color variant.     |
+| `compact` | `Boolean`   | `false`            | Slim variant: text-xs, smaller icon/padding. |
+**Slots:** default — body content rendered under the title.
+**Example:**
+```vue
+<template>
+  <BaseAlert title="Operation successful" :color="AlertEnum.SUCCESS" />
+  <BaseAlert title="Proxying is active." :color="AlertEnum.WARNING">
+    <p class="mt-0.5 text-xs opacity-90">The canned response below is ignored.</p>
+  </BaseAlert>
+  <BaseAlert compact :color="AlertEnum.WARNING">
+    Chunked dribble is ignored while Fault Simulation is active.
+  </BaseAlert>
+</template>
+<script setup lang="ts">
+import { BaseAlert, AlertEnum } from 'mgv-backoffice'
+</script>
+```
+---
+### BaseBadge
+Colored status badge/pill. Renders nothing when the default slot is empty;
+an omitted or unrecognized `color` falls back to the red palette.
+**Props:**
+| Prop    | Type     | Default | Description                       |
+| ------- | -------- | ------- | --------------------------------- |
+| `color` | `String` | —       | Color variant (use `ColorsEnums`) |
+**Slots:** `default` — badge label content.
+**Example:**
+```vue
+<template>
+  <BaseBadge :color="ColorsEnums.GREEN">Active</BaseBadge>
+  <BaseBadge :color="ColorsEnums.RED">Inactive</BaseBadge>
+</template>
+<script setup lang="ts">
+import { BaseBadge, ColorsEnums } from 'mgv-backoffice'
+</script>
+```
+---
+### BaseBreadcrumb
+Breadcrumb navigation. Provide items manually or pass a URL path for
+auto-generation; with neither prop it auto-generates from
+`window.location.pathname`. A "Home" crumb linking to `/` is always prepended.
+**Props:**
+| Prop    | Type            | Default     | Description                                |
+| ------- | --------------- | ----------- | ------------------------------------------ |
+| `items` | `BreadCrumb[]`  | `undefined` | Manual breadcrumb entries                  |
+| `path`  | `String`        | `undefined` | URL path for auto-generated breadcrumbs    |
+**BreadCrumb type:**
+```ts
+interface BreadCrumb {
+  name: string
+  url: string
+}
+```
+**Example:**
+```vue
+<template>
+  <!-- Manual -->
+  <BaseBreadcrumb :items="[
+    { name: 'Home', url: '/' },
+    { name: 'Users', url: '/users' },
+    { name: 'Profile', url: '/users/1' }
+  ]" />
+  <!-- Auto-generated from path -->
+  <BaseBreadcrumb path="/users/settings/profile" />
+</template>
+<script setup lang="ts">
+import { BaseBreadcrumb } from 'mgv-backoffice'
+import type { BreadCrumb } from 'mgv-backoffice'
+</script>
+```
+---
+### BaseButton
+Button with color, size, loading state, and Vue Router integration.
+**Props:**
+| Prop          | Type                                | Default               | Description                          |
+| ------------- | ----------------------------------- | --------------------- | ------------------------------------ |
+| `description` | `String`                            | **required**          | Button label text                    |
+| `color`       | `String`                            | `BaseButtonEnum.GREEN` | Color variant (`BLUE`/`WHITE`/`DARK`/`GREEN`/`EMERALD`/`RED`/`YELLOW`/`PURPLE`/`SKY`/`GRAY`/`AMBER`) |
+| `outline`     | `Boolean`                           | `false`               | Outlined/secondary style — transparent fill, coloured text + border, tinted hover (theme-aware) |
+| `ghost`       | `Boolean`                           | `false`               | Ghost/borderless style — no border or fill, coloured text + tinted hover (theme-aware). For compact toolbar/action buttons |
+| `to`          | `String`                            | —                     | Vue Router path (renders `<router-link>`) |
+| `type`        | `'button' \| 'submit' \| 'reset'`  | `'button'`            | HTML button type                     |
+| `iconLeft`    | `Boolean`                           | `false`               | Render the slot icon before the label |
+| `isRounded`   | `Boolean`                           | —                     | Fully rounded corners                |
+| `isDisable`   | `Boolean`                           | —                     | Disabled state                       |
+| `size`        | `String`                            | —                     | Size variant (use `BaseButtonSizeEnum`) |
+| `isLoading`   | `Boolean`                           | —                     | Show loading spinner                 |
+**Slots:** `default`
+**Example:**
+```vue
+<template>
+  <BaseButton description="Submit" :color="BaseButtonEnum.GREEN" type="submit" />
+  <BaseButton description="Go to Users" :to="'/users'" />
+  <BaseButton description="Saving..." :isLoading="true" :isDisable="true" />
+  <BaseButton
+    description="Delete"
+    :color="BaseButtonEnum.RED"
+    :size="BaseButtonSizeEnum.SMALL"
+  />
+  <!-- Outlined / secondary -->
+  <BaseButton description="Import" :color="BaseButtonEnum.EMERALD" outline iconLeft>
+    <ArrowUpTrayIcon class="w-4 h-4 mr-1.5" />
+  </BaseButton>
+  <!-- Ghost / borderless toolbar action -->
+  <BaseButton description="Logs" :color="BaseButtonEnum.SKY" ghost iconLeft :size="BaseButtonSizeEnum.SMALL">
+    <ClipboardDocumentListIcon class="w-4 h-4 mr-1.5" />
+  </BaseButton>
+</template>
+<script setup lang="ts">
+import { BaseButton, BaseButtonEnum, BaseButtonSizeEnum } from 'mgv-backoffice'
+</script>
+```
+---
+### BaseLine
+Horizontal divider with style variants.
+**Props:**
+| Prop   | Type     | Default         | Description       |
+| ------ | -------- | --------------- | ----------------- |
+| `mode` | `String` | `LineEnum.BASE` | Divider style     |
+**Example:**
+```vue
+<template>
+  <BaseLine />
+  <BaseLine :mode="LineEnum.SQUARE" />
+</template>
+<script setup lang="ts">
+import { BaseLine, LineEnum } from 'mgv-backoffice'
+</script>
+```
+---
+### BaseLogo
+SVG brand logo component.
+**Props:**
+| Prop   | Type     | Default                | Description  |
+| ------ | -------- | ---------------------- | ------------ |
+| `size` | `String` | `BaseLogoEnum.MEDIUM`  | Logo size    |
+**Example:**
+```vue
+<template>
+  <BaseLogo :size="BaseLogoEnum.LARGE" />
+</template>
+<script setup lang="ts">
+import { BaseLogo, BaseLogoEnum } from 'mgv-backoffice'
+</script>
+```
+---
+### BaseModal
+> ⚠️ **Deprecated.** Prefer [`BaseConfirmModal`](#baseconfirmmodal) for confirm/cancel
+> flows or [`BaseModalShell`](#basemodalshell) for custom dialogs — they support dark
+> mode, teleport to `<body>`, and slot-based composition. Kept for backward
+> compatibility.
+Confirmation dialog with support for delete and success modes. `DELETE` mode renders
+the confirm/cancel pair; any other mode renders the title, optional `description`,
+the default slot, and a single OK button that emits `closeModal`.
+**Props:**
+| Prop          | Type     | Default     | Description                         |
+| ------------- | -------- | ----------- |-------------------------------------|
+| `title`       | `String` | **required**| Modal heading                       |
+| `description` | `String` | —           | Body text                           |
+| `to`          | `String` | `"/"`       | Unused — declared for backward compatibility only; confirm just emits `confirmModal`, no navigation happens |
+| `mode`        | `String` | `'SUCCESS'` | Modal variant (use `BaseModalEnum`) |
+**Events:**
+| Event          | Description                     |
+| -------------- | ------------------------------- |
+| `closeModal`   | Emitted when modal is dismissed (cancel/OK button, backdrop click, or Escape) |
+| `confirmModal` | Emitted on confirm action       |
+**Example:**
+```vue
+<template>
+  <BaseModal
+    title="Delete this item?"
+    description="This action cannot be undone."
+    :mode="BaseModalEnum.DELETE"
+    @closeModal="showModal = false"
+    @confirmModal="handleDelete"
+  />
+</template>
+<script setup lang="ts">
+import { ref } from 'vue'
+import { BaseModal, BaseModalEnum } from 'mgv-backoffice'
+const showModal = ref(true)
+const handleDelete = () => { /* ... */ }
+</script>
+```
+---
+### BaseRow
+Card-like content container with border and shadow.
+**Props:**
+| Prop      | Type     | Default   | Description            |
+| --------- | -------- | --------- | ---------------------- |
+| `bgColor` | `String` | `"bg-white"` | Background color — a full Tailwind class (e.g. `"bg-slate-50"`), not a bare color name |
+**Slots:** `default` — row content.
+**Example:**
+```vue
+<template>
+  <BaseRow>
+    <p>Card content goes here</p>
+  </BaseRow>
+</template>
+<script setup lang="ts">
+import { BaseRow } from 'mgv-backoffice'
+</script>
+```
+---
+### BaseSpinner
+Animated loading spinner — a neutral ring with a coloured leading arc.
+**Props:**
+| Prop    | Type                                                                       | Default  | Description                                                  |
+|---------|----------------------------------------------------------------------------|----------|-------------------------------------------------------------|
+| `size`  | `'sm' \| 'md' \| 'lg' \| 'xl'`                                              | `'sm'`   | Diameter + ring thickness — 16 / 24 / 32 / 48px.            |
+| `color` | `'blue' \| 'emerald' \| 'sky' \| 'indigo' \| 'teal' \| 'purple' \| 'red' \| 'amber'` | `'emerald'` | Colour of the spinning arc. The track stays neutral gray.   |
+With no props it renders a 16px emerald spinner. For page loaders use `size="xl"` centered, e.g. `<div class="flex justify-center py-12"><BaseSpinner size="xl" /></div>`.
+**Example:**
+```vue
+<template>
+  <!-- legacy default -->
+  <BaseSpinner />
+  <!-- larger, themed -->
+  <BaseSpinner size="lg" color="emerald" />
+</template>
+<script setup lang="ts">
+import { BaseSpinner } from 'mgv-backoffice'
+</script>
+```
+---
+### BaseToast
+Toast notification with positioning and auto-dismiss.
+**Props:**
+| Prop           | Type             | Default   | Description                                |
+| -------------- | ---------------- | --------- | ------------------------------------------ |
+| `mode`         | `BaseToastEnum`  | **required** | Toast variant (SUCCESS, WARNING, ERROR) |
+| `description`  | `String`         | **required** | Message text                            |
+| `hasCloseIcon` | `Boolean`        | `true`    | Show close button                          |
+| `positioning`  | `String`         | `PositioningEnum.TOP_RIGHT` | Screen position (use `PositioningEnum`) |
+| `duration`     | `Number`         | `5000`    | Auto-dismiss delay in milliseconds         |
+**Example:**
+```vue
+<template>
+  <BaseToast
+    :mode="BaseToastEnum.SUCCESS"
+    description="Changes saved successfully!"
+    :positioning="PositioningEnum.TOP_RIGHT"
+  />
+</template>
+<script setup lang="ts">
+import { BaseToast, BaseToastEnum, PositioningEnum } from 'mgv-backoffice'
+</script>
+```
+---
+### ColoredSquares
+Colored square indicator with randomized pastel accent.
+**Props:**
+| Prop    | Type     | Default | Description                       |
+| ------- | -------- | ------- | --------------------------------- |
+| `color` | `String` | —       | Color variant (use `ColorsEnums`) |
+**Slots:** `default` — label content.
+**Example:**
+```vue
+<template>
+  <ColoredSquares :color="ColorsEnums.BLUE">Category A</ColoredSquares>
+</template>
+<script setup lang="ts">
+import { ColoredSquares, ColorsEnums } from 'mgv-backoffice'
+</script>
+```
+---
+### EarningsCard
+Earnings summary card with formatted currency display. Supports a signed P&L
+mode that renders a red loss theme (and a downward trend glyph) for negative
+amounts.
+**Props:**
+| Prop       | Type     | Default                 | Description          |
+| ---------- | -------- |-------------------------|----------------------|
+| `title`    | `String` | `'TOTAL EARNINGS'`      | Card heading         |
+| `amount`   | `Number` | `0`                     | Monetary value (a stringified number is coerced) |
+| `subtitle` | `String` | `'Lifetime commission'` | Subheading text      |
+| `badge`    | `String` | `''`                    | Optional badge label |
+| `currency` | `String` | `'$'`                   | Currency symbol      |
+| `decimals` | `Number` | `2`                     | Fraction digits shown for the amount |
+| `accent`   | `'orange' \| 'emerald' \| 'red'` | `'orange'` | Card theme. `emerald` tints it green; `red` is the loss theme. |
+| `signed`   | `Boolean` | `false`                | Treat `amount` as a signed P&L figure: a negative value automatically switches to the `red` loss theme and flips the trend glyph to point **down**; a non-negative value keeps the chosen `accent` and the upward glyph. |
+| `compact`  | `Boolean` | `false`                | Dense variant for dashboards that tile many cards on one row: tighter padding, smaller type, trend glyph shrunk into the top-right corner. Don't combine with `badge` — both occupy the top-right corner. |
+**Example:**
+```vue
+<template>
+  <!-- Always-positive total: original behaviour. -->
+  <EarningsCard
+    title="Monthly Revenue"
+    :amount="12500"
+    subtitle="April 2026"
+    currency="€"
+  />
+  <!-- Signed P&L: renders red + a down arrow when the amount is negative. -->
+  <EarningsCard
+    title="TOTAL P&L"
+    :amount="-128.4"
+    subtitle="Realised + unrealised"
+    accent="emerald"
+    signed
+  />
+</template>
+<script setup lang="ts">
+import { EarningsCard } from 'mgv-backoffice'
+</script>
+```
+---
+### EuroAmount
+Formatted euro currency display with conditional color coding.
+**Props:**
+| Prop           | Type      | Default | Description                                     |
+| -------------- | --------- | ------- |-------------------------------------------------|
+| `amount`       | `Number`  | —       | Value to display                                |
+| `beforeAmount` | `Number`  | `null`  | Previous value: red if `amount < beforeAmount`, green if `amount >= beforeAmount`. When omitted, a non-negative amount renders neutral (never green); a negative amount is always red. |
+| `showCurrency` | `Boolean` | `true`  | Show euro symbol                                |
+**Example:**
+```vue
+<template>
+  <!-- Shows green (amount > beforeAmount) -->
+  <EuroAmount :amount="1500" :beforeAmount="1200" />
+  <!-- Shows red (negative) -->
+  <EuroAmount :amount="-300" />
+  <!-- Without currency symbol -->
+  <EuroAmount :amount="800" :showCurrency="false" />
+</template>
+<script setup lang="ts">
+import { EuroAmount } from 'mgv-backoffice'
+</script>
+```
+---
+### Pagination
+Page navigation with smart ellipsis for large page counts.
+**Props:**
+| Prop           | Type     | Default | Description             |
+| -------------- | -------- | ------- | ----------------------- |
+| `totalItems`   | `Number` | **required** | Total number of items   |
+| `itemsPerPage` | `Number` | `20`    | Items shown per page    |
+**Events:**
+| Event          | Payload  | Description                      |
+| -------------- | -------- |----------------------------------|
+| `page-changed` | `Number` | Emitted with the new page number |
+**Example:**
+```vue
+<template>
+  <Pagination
+    :totalItems="200"
+    :itemsPerPage="10"
+    @page-changed="onPageChange"
+  />
+</template>
+<script setup lang="ts">
+import { Pagination } from 'mgv-backoffice'
+const onPageChange = (page: number) => {
+  console.log('Page:', page)
+}
+</script>
+```
+---
+### TrendArrow
+Up/down trend indicator displayed as a colored badge.
+**Props:**
+| Prop     | Type     | Default | Description                                          |
+| -------- | -------- | ------- |------------------------------------------------------|
+| `number` | `Number` | —       | Positive = green arrow up, negative = red arrow down, zero = neutral gray dash |
+| `icon`   | `String` | —       | Optional suffix appended after the number (e.g. `"%"`) |
+**Example:**
+```vue
+<template>
+  <TrendArrow :number="12.5" />   <!-- Green up arrow -->
+  <TrendArrow :number="-3.2" />   <!-- Red down arrow -->
+  <TrendArrow :number="0" />      <!-- Neutral gray dash -->
+</template>
+<script setup lang="ts">
+import { TrendArrow } from 'mgv-backoffice'
+</script>
+```
+---
+## Enums
+All enums are importable directly from the package:
+```ts
+import {
+  AlertEnum,
+  BaseBadgeEnum,
+  BaseButtonEnum,
+  BaseButtonSizeEnum,
+  BaseLogoEnum,
+  BaseModalEnum,
+  BaseToastEnum,
+  ColorsEnums,
+  LineEnum,
+  PositioningEnum
+} from 'mgv-backoffice'
+```
+| Enum                 | Values                                                        |
+| -------------------- |---------------------------------------------------------------|
+| `AlertEnum`          | `WARNING`, `ERROR`, `SUCCESS`, `INFO`                         |
+| `BaseBadgeEnum`      | `WIN`, `LOSE`                                                 |
+| `BaseButtonEnum`     | `RED`, `BLUE`, `WHITE`, `DARK`, `GREEN`, `EMERALD`, `YELLOW`, `PURPLE`, `SKY`, `GRAY`, `AMBER` |
+| `BaseButtonSizeEnum` | `EXTRA_SMALL`, `SMALL`, `BASE`, `LARGE`, `EXTRA_LARGE`        |
+| `BaseLogoEnum`       | `SMALL`, `MEDIUM`, `LARGE` (`BaseLoginEnum` is a deprecated alias) |
+| `BaseModalEnum`      | `DELETE`, `SUCCESS`                                           |
+| `BaseToastEnum`      | `SUCCESS`, `WARNING`, `ERROR`                                 |
+| `ColorsEnums`        | `NONE`, `RED`, `YELLOW`, `BLACK`, `GRAY`, `GREEN`, `BLUE`     |
+| `LineEnum`           | `BASE`, `BASE_SHORTER`, `SQUARE`                              |
+| `PositioningEnum`    | `TOP_LEFT`, `TOP_RIGHT`, `BOTTOM_LEFT`, `BOTTOM_RIGHT`        |
+---
+## Types
+```ts
+import type { BreadCrumb, DropdownOption, PnL, PnLInputs } from 'mgv-backoffice'
+```
+| Type             | Shape                                  |
+| ---------------- | -------------------------------------- |
+| `BreadCrumb`     | `{ name: string; url: string }`        |
+| `DropdownOption` | `{ value: string \| number; label: string; title?: string; disabled?: boolean }` |
+| `PnLInputs`      | `{ buyPrice; lastPrice; filledQty }` (each `number \| string \| null \| undefined`) |
+| `PnL`            | `{ pnlUsd: number \| null; pnlPct: number \| null }` |
+The other exported types — `NavItem`, `NavSection`, `EntityPickerItem`,
+`LoginCredentials`, `NotificationItem`, `SegmentedOption`, `TableColumn`,
+`SpecField`, `SpecFieldType`, `SpecFieldValue`, `StatBreakdownItem`,
+`PillPickerItem`, `DistributionBar`, `CredentialsView`, `CredentialsUpdate` —
+are documented in their component's section.
+---
+## Utilities
+```ts
+import { getBaseColor, getBaseColorOf } from 'mgv-backoffice'
+```
+| Function         | Signature                          | Returns                             |
+| ---------------- | ---------------------------------- | ----------------------------------- |
+| `getBaseColor`   | `(c: AlertEnum) => string`         | Tailwind color name for alert type  |
+| `getBaseColorOf` | `(c: ColorsEnums) => string`       | Tailwind color name for color enum  |
+### HTTP colours
+```ts
+import {
+  methodBadgeSolid,
+  methodBadgeBright,
+  methodBadgeTinted,
+  statusBadgeSolid,
+  statusBadgeTinted,
+  statusBadgeSoft,
+} from 'mgv-backoffice'
+```
+Tailwind class helpers for HTTP method and status code badges. `Solid` variants
+return saturated `bg-*-600` classes for use on neutral surfaces; `Bright` /
+`Tinted` variants return softer combinations suitable for cards. `statusBadgeTinted`
+takes `(status, isDark)` to adapt between themes.
+`methodBadgeTinted(method, isDark)` gives each method its own hue on a soft
+tinted surface (`bg-*-500/15` dark / `bg-*-100` light; GET blue, POST emerald,
+PUT amber, DELETE red, PATCH purple, HEAD sky) — the card-chip palette used by
+WireMate's mock/stub cards. `statusBadgeSoft(status, isDark)` is its status
+companion keyed by status class (emerald 2xx / sky 3xx / amber 4xx / red 5xx).
+### Key/value row validators
+```ts
+import { rowKeyMissing, rowValueMissing } from 'mgv-backoffice'
+import type { KeyValueRowLike } from 'mgv-backoffice'
+```
+| Function          | Signature                                                              | Returns |
+| ----------------- | ---------------------------------------------------------------------- | ------- |
+| `rowValueMissing` | `(row: { key?, value?, matcherType? }) => boolean`                     | `true` when the row has a key but no value. |
+| `rowKeyMissing`   | `(row: { key?, value?, matcherType? }) => boolean`                     | `true` when the row has a value but no key. |
+Consistency checks for dynamic key/value grids (header lists, query params,
+metadata rows). Rows with `matcherType: 'absent'` are exempt — an absent
+matcher intentionally carries no value.
+### Input validators
+```ts
+import { isValidAbsoluteUrl, isValidJson, isValidXml, isValidBase64 } from 'mgv-backoffice'
+```
+Pure, dependency-free form-input validators. The payload validators treat
+empty/whitespace-only input as **valid** — required-ness is a separate rule
+from well-formedness; `isValidAbsoluteUrl` validates a value that must exist,
+so empty is invalid there.
+| Function             | Signature                    | Returns |
+| -------------------- | ---------------------------- | ------- |
+| `isValidAbsoluteUrl` | `(value: string) => boolean` | `true` for an absolute `http://` / `https://` URL (other schemes rejected). |
+| `isValidJson`        | `(str: string) => boolean`   | `true` when empty or parseable as JSON. |
+| `isValidXml`         | `(str: string) => boolean`   | `true` when empty or well-formed XML (DOMParser `<parsererror>` check; browser-only). |
+| `isValidBase64`      | `(str: string) => boolean`   | `true` when empty or well-formed base64 (whitespace stripped, length/alphabet checked, then `atob` as the final authority). |
+### HTML sanitizer
+```ts
+import { sanitizeHtml, isSafeHref } from 'mgv-backoffice'
+```
+| Function       | Signature                                       | Returns |
+| -------------- | ----------------------------------------------- | ------- |
+| `sanitizeHtml` | `(raw: string \| undefined \| null) => string`  | Allow-list–sanitised HTML safe for `v-html`. |
+| `isSafeHref`   | `(value: string) => boolean`                    | `true` if the href uses a safe scheme (http/https/mailto/tel, root-relative, or anchor) or is empty/whitespace-only. |
+Allow-list sanitizer for strings bound into `v-html`. Keeps a small set of
+formatting tags (`a`, `b`/`strong`, `i`/`em`, `code`, `pre`, `p`, `ul`/`ol`/`li`,
+`span`, `div`, `br`), strips all other elements (unwrapping to text, or dropping
+content entirely for `script`/`style`/`iframe`/etc.), removes every attribute
+except `href`/`title` on anchors, keeps only allow-listed hrefs (http/https/
+mailto/tel, root-relative `/`, anchors `#`, or empty — every other scheme such
+as `javascript:`, `data:`, `ftp:` is stripped), and hardens surviving links with
+`rel="noopener noreferrer" target="_blank"`. Browser-only (uses `DOMParser`).
+```ts
+sanitizeHtml('<p>Hi<script>alert(1)<\/script></p>') // '<p>Hi</p>'
+```
+### Display formatters
+```ts
+import {
+  fmtNumber,
+  fmtDate,
+  fmtDateTime,
+  fmtDateShort,
+  fmtPrice,
+  fmtPct,
+  fmtUsd,
+  // …plus fmtDateTimeMs, fmtCalendarDate, fmtCalendarDateTime,
+  // fmtMsAsSeconds, fmtBytes, fmtDuration, formatJson, stringifyValue
+} from 'mgv-backoffice'
+```
+Locale-aware, pure, dependency-free formatters for tables, logs and charts.
+`fmtNumber`, `fmtDate`, `fmtCalendarDate`, `fmtCalendarDateTime` and
+`fmtDuration` handle missing/non-finite input gracefully (rendering an
+em-dash) so raw API values can be passed without pre-sanitising; the
+epoch/numeric formatters (`fmtDateTime`, `fmtDateShort`, `fmtDateTimeMs`,
+`fmtPrice`, `fmtPct`, `fmtUsd`) expect valid input and will render
+`"Invalid Date"` / `"NaN"` otherwise.
+| Function       | Signature                                                       | Returns |
+| -------------- | --------------------------------------------------------------- | ------- |
+| `fmtNumber`    | `(n: number \| string \| null \| undefined, digits = 4) => string` | Fixed-fraction number; em-dash for null/undefined/non-finite. Accepts numeric strings. |
+| `fmtDate`      | `(s: string \| number \| null \| undefined) => string`          | Locale date-time from ISO string or epoch; em-dash on empty, raw value on parse failure. |
+| `fmtDateTime`  | `(ms: number) => string`                                        | Compact `"Mon D, HH:MM"` label from epoch-millis (chart axes/tooltips). |
+| `fmtDateTimeMs`| `(s: string \| number) => string`                               | Full 24-hour locale date-time WITH the millisecond fraction — for dense feeds where same-second rows must stay distinguishable. |
+| `fmtDateShort` | `(ms: number) => string`                                        | Short `"Mon D"` calendar label from epoch-millis. |
+| `fmtCalendarDate` | `(s: string \| number \| null \| undefined) => string`       | `"Mon D, YYYY"` en-US calendar label; em-dash on empty, raw value on parse failure. |
+| `fmtCalendarDateTime` | `(s: string \| number \| null \| undefined) => string`   | `"Mon D, YYYY, HH:MM"` en-US calendar label with time of day. |
+| `fmtMsAsSeconds` | `(ms: number \| null \| undefined) => string`                 | `"= 1.50 s"` magnitude hint for millisecond inputs (3 decimals below 1 s); `''` for non-positive input. |
+| `fmtBytes`     | `(bytes: number \| null \| undefined) => string`                | `"512 B"` / `"1.5 KB"` / `"2.0 MB"`; `''` for zero/falsy input. |
+| `fmtDuration`  | `(ms: number \| null \| undefined, maxUnits = 2) => string`     | Compact day/hour/minute duration, e.g. `"3d 5h"` / `"5h 12m"` / `"12m"`. Zero-value leading units are dropped; `maxUnits` caps how many units render. Em-dash for null/undefined/non-finite. |
+| `fmtPrice`     | `(n: number) => string`                                         | Price with precision that scales to magnitude (more decimals for sub-cent values). |
+| `fmtPct`       | `(n: number, digits = 2) => string`                             | Percentage with explicit sign, e.g. `"+2.50%"`. |
+| `fmtUsd`       | `(v: number) => string`                                         | Signed USD amount with leading sign, e.g. `"+$5.00"`. |
+| `formatJson`   | `(content: string) => string`                                   | Pretty-prints parseable JSON with 2-space indentation; returns anything else verbatim. |
+| `stringifyValue` | `(value: unknown) => string`                                  | Display string for an unknown value: strings pass through, null/undefined → `''`, everything else JSON-serialized (`String()` fallback). |
+### Spec-form helpers
+```ts
+import { buildSpecParams, firstInvalidNumericSpec } from 'mgv-backoffice'
+```
+Value-map helpers for spec-driven forms (the state behind `BaseSpecFields`).
+A spec whose `default` is `null` is treated as OPTIONAL — blank means "knob
+disabled" and passes validation.
+| Function                 | Signature | Returns |
+| ------------------------ | --------- | ------- |
+| `buildSpecParams`        | `(specs: SpecField[] \| undefined, existing: Record<string, SpecFieldValue>) => Record<string, SpecFieldValue>` | Value map seeded from each spec's `default`, keeping non-null overlapping values the caller already has (an existing `null` is re-seeded from the spec's `default`). |
+| `firstInvalidNumericSpec`| `(specs: SpecField[] \| undefined, params: Record<string, SpecFieldValue>) => string \| null` | Label of the first blank / NaN numeric field, or `null` when all numerics are valid. |
+### Profit & loss
+```ts
+import { computePnL } from 'mgv-backoffice'
+import type { PnL, PnLInputs } from 'mgv-backoffice'
+```
+| Function     | Signature                       | Returns |
+| ------------ | ------------------------------- | ------- |
+| `computePnL` | `(row: PnLInputs) => PnL`       | Unrealised mark-to-market PnL in absolute USD and percent. Returns `{ pnlUsd: null, pnlPct: null }` when any input is missing, non-finite, or `buyPrice <= 0` / `lastPrice <= 0`. |
+```ts
+interface PnLInputs {
+  buyPrice: number | string | null | undefined
+  lastPrice: number | string | null | undefined
+  filledQty: number | string | null | undefined
+}
+interface PnL {
+  pnlUsd: number | null
+  pnlPct: number | null
+}
+```
+```ts
+computePnL({ buyPrice: 100, lastPrice: 110, filledQty: 5 })
+// { pnlUsd: 50, pnlPct: 10 }
+```
+---
+## Layout & shells (Tier 2 — full backoffice chrome)
+### BaseAppLayout
+Root layout: dark/light page background, skip link, `<main>`-with-inert wrapper.
+The `<main>` content offset tracks the sidebar width automatically —
+`lg:ml-60` when expanded, `lg:ml-16` when collapsed (via `useSidebarCollapse()`) —
+and adds `pt-14 lg:pt-0` for the mobile top bar while the sidebar is shown.
+**Props:**
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `showSidebar` | `Boolean` | `true` | Render the `sidebar` slot. Set false for full-bleed pages. |
+| `skipLinkLabel` | `String` | `'Skip to main content'` | Label for the accessibility skip link. |
+**Slots:** `sidebar`, `default` (page content).
+```vue
+<BaseAppLayout :show-sidebar="route.name !== 'presentation'">
+  <template #sidebar><AppSidebar /></template>
+  <RouterView />
+</BaseAppLayout>
+```
+### BaseSidebar
+Responsive sidebar with desktop fixed-positioning and mobile off-canvas
+behavior, focus management, optional theme toggle, a desktop collapse
+toggle (icon-only rail), an optional notifications bell, and configurable
+nav sections.
+**Props:**
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `sections` | `NavSection[]` | **required** | Grouped nav items. |
+| `homeRouteName` | `String` | `'home'` | Route name for the logo / "go home" click. |
+| `appName` | `String` | `''` | Optional app name in the footer. |
+| `version` | `String` | `''` | Optional version string in the footer. |
+| `showThemeToggle` | `Boolean` | `true` | Toggle the dark/light switch in the footer. |
+| `collapsible` | `Boolean` | `true` | Show the desktop collapse toggle that shrinks the sidebar to an icon-only rail. |
+| `showNotifications` | `Boolean` | `false` | Show the notifications bell (with unread badge) that toggles `BaseNotificationPanel`. |
+> **Collapse state** is shared via `useSidebarCollapse()` (and persisted to
+> localStorage) so `BaseAppLayout` can shrink the content offset from
+> `lg:ml-60` to `lg:ml-16` in step with the rail. Collapsing only affects
+> desktop (`lg+`); on mobile the sidebar stays a full off-canvas panel.
+> **Notifications:** set `:show-notifications="true"` to render the bell,
+> then drop a [`BaseNotificationPanel`](#basenotificationpanel) in your app.
+> Both share state through `useNotifications()`, so the unread badge and the
+> panel stay in sync.
+**Slots:**
+| Slot     | Slot props | Description |
+| -------- | ---------- | ----------- |
+| `logo`   | `{ size }` | Brand logo. Receives a `size` hint (28px in mobile bar, 52px in expanded sidebar, 36px in the collapsed rail). |
+| `status` | —          | Footer status row (e.g. health indicator, sync state). |
+| `footer` | —          | Replaces the default `appName` + `v{version}` line. |
+**Types:**
+```ts
+import type { NavItem, NavSection } from 'mgv-backoffice'
+interface NavItem {
+  name: string       // Vue Router route name
+  label: string      // display text
+  icon: Component    // typically a Heroicon
+}
+interface NavSection {
+  title: string
+  items: NavItem[]
+}
+```
+```vue
+<BaseSidebar :sections="navSections" home-route-name="projects" app-name="WireMate UI" :version="appVersion">
+  <template #logo="{ size }"><WireMateLogo :size="size" /></template>
+  <template #status>
+    <HealthIndicator />
+  </template>
+</BaseSidebar>
+```
+---
+### BaseSidebarUser
+Signed-in user block for the `BaseSidebar` `footer` slot: initials avatar,
+name and email (a link to the profile page when `to` is set) and a Logout
+button that emits `logout`.
+**Props:** `name` (required), `email`, `to` (profile route), `showLogout` (`true`),
+`logoutLabel` (`'Logout'`), `profileLabel` (`'View profile'`, tooltip).
+**Emits:** `logout`.
+```vue
+<BaseSidebar :sections="nav">
+  <template #footer>
+    <BaseSidebarUser :name="me.username" :email="me.email" :to="{ name: 'Profile' }" @logout="logOut" />
+  </template>
+</BaseSidebar>
+```
+### BaseNotificationPanel
+Left-anchored notification drawer (teleported to `<body>`, slides in from
+the left, backdrop + Escape to close). Open/close state and the list live
+in `useNotifications()`, so the sidebar bell and the panel stay in sync.
+Enable the bell on the sidebar with `:show-notifications="true"`, drop one
+`<BaseNotificationPanel />` anywhere in your app, and feed it data via the
+composable.
+**Props:**
+| Prop              | Type      | Default                        | Description |
+| ----------------- | --------- | ------------------------------ | ----------- |
+| `title`           | `String`  | `'Notifications'`              | Panel heading. |
+| `emptyText`       | `String`  | `'You have no notifications.'` | Shown when the list is empty. |
+| `showMarkAllRead` | `Boolean` | `true`                         | Render the "Mark all as read" action when there are unread items. |
+**Emits:** `select` (the clicked notification's `id`; the row is also marked read).
+```vue
+<script setup lang="ts">
+import { BaseNotificationPanel, useNotifications } from 'mgv-backoffice'
+const { setNotifications } = useNotifications()
+setNotifications([
+  { id: 1, title: 'New comment', message: 'Alice replied to your post', time: '2m ago', type: 'info' },
+  { id: 2, title: 'Build passed', time: '1h ago', read: true, type: 'success' },
+])
+</script>
+<template>
+  <BaseSidebar :sections="navSections" :show-notifications="true" />
+  <BaseNotificationPanel @select="(id) => goTo(id)" />
+</template>
+```
+```ts
+import type { NotificationItem } from 'mgv-backoffice'
+interface NotificationItem {
+  id: string | number
+  title: string
+  message?: string
+  time?: string                                   // pre-formatted by you
+  read?: boolean
+  type?: 'info' | 'success' | 'warning' | 'error' // status dot colour
+}
+```
+---
+## Authentication
+### BaseGoogleSignInButton
+Google-branded "Sign in with Google" button (official multi-colour "G",
+dark-mode surface swap). Purely presentational — it runs no OAuth itself;
+listen on `click` and start your own Google Identity / Firebase / backend
+flow there.
+**Props:**
+| Prop       | Type      | Default                    | Description |
+| ---------- | --------- | -------------------------- | ----------- |
+| `label`    | `String`  | `'Sign in with Google'`    | Button text. |
+| `loading`  | `Boolean` | `false`                    | Disables and shows a spinner. |
+| `disabled` | `Boolean` | `false`                    | Disables without the spinner. |
+| `block`    | `Boolean` | `true`                     | Full-width layout. |
+**Emits:** `click` (only when not disabled/loading).
+### BaseLoginForm
+Presentational sign-in card: email + password (with show/hide), an optional
+"Remember me" checkbox, an error banner, the Google button + "or" divider,
+and `logo` / `forgot` / `footer` slots. Owns its input state and emits
+`submit` / `google-sign-in`; the app handles the actual request and feeds
+back `loading` / `error`.
+**Props:**
+| Prop            | Type      | Default     | Description |
+| --------------- | --------- | ----------- | ----------- |
+| `title`         | `String`  | `'Sign in'` | Card heading. |
+| `subtitle`      | `String`  | `''`        | Muted line under the heading. |
+| `submitLabel`   | `String`  | `'Sign in'` | Submit button text. |
+| `loading`       | `Boolean` | `false`     | Disables the form, spinner on submit. |
+| `googleLoading` | `Boolean` | `false`     | Disables the form, spinner on the Google button. |
+| `error`         | `String`  | `''`        | Error banner above the form. |
+| `showGoogle`    | `Boolean` | `true`      | Render the Google button + divider. |
+| `showRemember`  | `Boolean` | `false`     | Render the "Remember me" checkbox. |
+**Emits:** `submit` (`LoginCredentials`), `google-sign-in`.
+**Slots:** `logo`, `forgot` (next to the password label), `footer`.
+```vue
+<script setup lang="ts">
+import { BaseLoginForm } from 'mgv-backoffice'
+import type { LoginCredentials } from 'mgv-backoffice'
+async function onSubmit(creds: LoginCredentials) { /* call your API */ }
+function onGoogle() { /* start Google OAuth */ }
+</script>
+<template>
+  <BaseLoginForm
+    subtitle="Welcome back"
+    :show-remember="true"
+    @submit="onSubmit"
+    @google-sign-in="onGoogle"
+  >
+    <template #logo><MyLogo /></template>
+    <template #forgot><a href="/forgot" class="text-sm text-emerald-600">Forgot?</a></template>
+    <template #footer>No account? <a href="/signup" class="text-emerald-600">Sign up</a></template>
+  </BaseLoginForm>
+</template>
+```
+---
+## Modals & sections
+### BaseModalShell
+Shared modal chrome — `Teleport` to body, backdrop, themed card, escape key,
+aria-modal. Compose this rather than building modals from scratch.
+**Props:**
+| Prop            | Type      | Default     | Description |
+| --------------- | --------- | ----------- | ----------- |
+| `title`         | `String`  | **required** | Modal heading. |
+| `icon`          | `Component` | **required** | Heroicon rendered in a tinted circular chip left of the title (the `icon` slot can override the whole chip). |
+| `iconBgClass`   | `String`  | `''`        | Background classes of the icon chip; empty falls back to the emerald tint (dark-mode aware). |
+| `iconClass`     | `String`  | `'text-emerald-600'` | Classes applied to the icon itself. |
+| `maxWidthClass` | `String`  | `'max-w-md'` | Tailwind max-w utility for the card. |
+| `manualClose`   | `Boolean` | `false`     | If true, backdrop click and Escape do NOT auto-emit `cancel`. |
+| `scrollable`    | `Boolean` | `false`     | Switch to the large-content layout: a flex column capped at `90vh` with a fixed header/footer and a scrolling body. |
+| `subtitle`      | `String`  | `''`        | Muted line under the title (scrollable layout only). |
+**Slots:** `icon`, `default`, `footer`, and (scrollable layout) `header-actions` — content on the right of the header, e.g. a close button.
+**Events:** `cancel`, `backdrop`.
+### BaseConfirmModal
+Confirmation dialog built on `BaseModalShell`. Variant chooses red (danger) or
+amber (warning) styling.
+**Props:** `title`, `message`, `confirmText`, `cancelText`, `submittingText`,
+`variant: 'danger' | 'warning'`, `submitting`. While `submitting` is true,
+backdrop clicks and Escape stop dismissing the dialog.
+**Slots:** `message` — rich markup replacing the plain `message` string;
+`default` — extra content below the message (warning banner, opt-in checkbox).
+**Events:** `confirm`, `cancel`.
+### BaseTextInputModal
+"Ask the user for a single string and confirm" dialog. Preserves typed input
+on stray backdrop clicks; Escape always cancels.
+**Props:** `title`, `message`, `initialValue`, `placeholder`, `inputLabel`,
+`confirmText`, `cancelText`, `submittingText`, `submitting`.
+**Slots:** `icon` — override the default emerald document icon.
+**Events:** `confirm(value: string)`, `cancel`.
+### BaseEntityPickerModal
+Searchable "pick one from a list" dialog. Pass `items` directly or an async
+`loader` that runs on mount.
+**Props:** `title`, `message?`, `items?: EntityPickerItem[]`,
+`loader?: () => Promise<EntityPickerItem[]>`, `excludeId?`,
+`variant: 'emerald' | 'purple' | 'blue' | 'red' | 'amber'`,
+`searchPlaceholder`, `emptyMessage`, `noMatchMessage`, `confirmText`,
+`cancelText`, `submittingText`, `submitting`.
+**Slots:** `icon` — override the default icon chip.
+**Events:** `confirm(itemId: string)`, `cancel`.
+```ts
+interface EntityPickerItem { id: string; label: string }
+```
+### BaseCollapsibleSection
+Section wrapper with a clickable header, optional badge, and a `default` slot
+for the body. Parent owns the `collapsed` state.
+**Props:** `title`, `collapsed`, `badge?`, `bodyClass?`.
+**Events:** `toggle`.
+### BaseNotFoundPage
+Drop-in 404 view.
+**Props:** `code` (`'404'`), `message` (`'Page not found'`),
+`homeRouteName` (`'home'`), `homeLabel` (`'Go home'`).
+### BasePageHeader
+Page-level header: icon badge + title/subtitle on the left, action
+buttons on the right. Gives top-level views a consistent header shape
+and width. The icon badge only renders when the `icon` slot is filled,
+so icon-less apps get a plain title/subtitle header.
+**Props:**
+| Prop            | Type     | Default       | Description |
+| --------------- | -------- | ------------- | ----------- |
+| `title`         | `String` | **required**  | H1 text. |
+| `subtitle`      | `String` | `''`          | Muted line below the title. |
+| `iconColor`     | `String` | `'emerald'`   | Badge + icon colour: `'emerald' \| 'sky' \| 'red' \| 'amber'`. |
+| `maxWidthClass` | `String` | `'max-w-4xl'` | Tailwind max-w utility constraining header width. Pass `''` to skip the width wrapper entirely — the header then spans its container. |
+| `align`         | `String` | `'center'`    | Vertical alignment of the title block vs the actions: `'center'` or `'end'` (actions sit on the title baseline). |
+| `marginClass`   | `String` | `'mb-8'`      | Space under the header. Pass `''` when the parent manages vertical rhythm (`space-y-*`). |
+| `accent`        | `Boolean` | `false`       | Brand-green gauge bar in front of the title (icon-less headers). |
+**Slots:**
+| Slot       | Slot props        | Description |
+| ---------- | ----------------- | ----------- |
+| `icon`     | `{ iconClass }`   | Page Heroicon. Bind `:class="iconClass"` for the theme-aware colour. Badge square renders only when this slot is filled. |
+| `subtitle` | —                 | Rich subtitle content (links, `<strong>`, interpolation); overrides the `subtitle` prop. |
+| `actions`  | —                 | Buttons rendered on the right (refresh, destructive, etc.). |
+```vue
+<template>
+  <BasePageHeader title="Request Journal" subtitle="Recent matched requests" icon-color="sky">
+    <template #icon="{ iconClass }">
+      <DocumentTextIcon class="w-5 h-5" :class="iconClass" />
+    </template>
+    <template #actions>
+      <BaseButton description="Refresh" @click="reload" />
+    </template>
+  </BasePageHeader>
+</template>
+<script setup lang="ts">
+import { BasePageHeader, BaseButton } from 'mgv-backoffice'
+import { DocumentTextIcon } from '@heroicons/vue/24/outline'
+</script>
+```
+---
+### BaseToolbarButton
+Bordered toolbar button — the "Refresh / Delete All" row that sits under
+a page header. Optional leading icon (via slot) plus a label.
+**Props:**
+| Prop       | Type      | Default     | Description |
+| ---------- | --------- | ----------- | ----------- |
+| `label`    | `String`  | `''`        | Button text. Omit for an icon-only button. |
+| `variant`  | `String`  | `'neutral'` | `'neutral'` (grey), `'danger'` (solid red) or `'ghost'` (slate h-9 outline — toolbar/modal-footer buttons). |
+| `disabled` | `Boolean` | `false`     | Greys out and blocks the click. |
+| `title`    | `String`  | `undefined` | Native tooltip / a11y text. |
+| `type`     | `String`  | `'button'`  | Native button type. |
+**Slots:**
+| Slot   | Slot props      | Description |
+| ------ | --------------- | ----------- |
+| `icon` | `{ iconClass }` | Leading Heroicon. Bind `:class="iconClass"` (`w-4 h-4`); add state classes as needed. |
+**Emits:** `click` (native `MouseEvent`).
+```vue
+<template>
+  <BaseToolbarButton label="Refresh" :disabled="isLoading" title="Refresh" @click="reload">
+    <template #icon="{ iconClass }">
+      <ArrowPathIcon :class="[iconClass, { 'animate-spin': isLoading }]" />
+    </template>
+  </BaseToolbarButton>
+  <BaseToolbarButton label="Delete All" variant="danger" @click="deleteAll">
+    <template #icon="{ iconClass }">
+      <TrashIcon :class="iconClass" />
+    </template>
+  </BaseToolbarButton>
+</template>
+```
+---
+### BaseActionButton
+Compact ghost action button — the colour-coded "Edit / Logs / Stub /
+Delete" actions on a card footer or action row. No border/fill at rest;
+a tinted hover background keyed to the semantic colour.
+**Props:**
+| Prop        | Type      | Default     | Description |
+| ----------- | --------- | ----------- | ----------- |
+| `label`     | `String`  | `''`        | Button text. Omit for an icon-only button. |
+| `color`     | `String`  | `'emerald'` | `'emerald' \| 'sky' \| 'indigo' \| 'teal' \| 'purple' \| 'red' \| 'amber' \| 'amberStrong'`. |
+| `disabled`  | `Boolean` | `false`     | Dims via opacity and suppresses the hover tint. |
+| `fullWidth` | `Boolean` | `false`     | Stretch to fill its flex row (`flex-1`). |
+| `title`     | `String`  | `undefined` | Native tooltip. |
+| `ariaLabel` | `String`  | `undefined` | Accessible label. |
+| `type`      | `String`  | `'button'`  | Native button type. |
+**Slots:**
+| Slot   | Slot props      | Description |
+| ------ | --------------- | ----------- |
+| `icon` | `{ iconClass }` | Leading Heroicon. Bind `:class="iconClass"` (`w-4 h-4`). |
+**Emits:** `click` (native `MouseEvent`).
+```vue
+<template>
+  <BaseActionButton label="Edit" color="emerald" full-width title="Edit this mock" @click="edit">
+    <template #icon="{ iconClass }">
+      <PencilSquareIcon :class="iconClass" />
+    </template>
+  </BaseActionButton>
+  <BaseActionButton label="Delete" color="red" @click="remove">
+    <template #icon="{ iconClass }">
+      <TrashIcon :class="iconClass" />
+    </template>
+  </BaseActionButton>
+</template>
+```
+---
+### BaseCopyButton
+Copy-to-clipboard icon button with transient "copied" feedback — clicks
+write `text` to the clipboard, swap the clipboard icon for a checkmark
+for `resetMs`, then revert. Uses the async Clipboard API with a
+hidden-textarea `execCommand` fallback for insecure origins. Emits
+`copied` / `error` so the parent can fire its own toast.
+**Props:**
+| Prop        | Type      | Default   | Description |
+| ----------- | --------- | --------- | ----------- |
+| `text`      | `String`  | **required** | Value written to the clipboard. |
+| `label`     | `String`  | `''`      | Used in the tooltip / aria-label (`Copy {label}`). |
+| `variant`   | `String`  | `'ghost'` | `'ghost'` (borderless `p-1` icon) or `'bordered'` (`w-9 h-9` boxed, turns emerald while copied). |
+| `resetMs`   | `Number`  | `1500`    | How long the checkmark stays before reverting. |
+| `iconClass` | `String`  | `'w-4 h-4'` | Icon size class. |
+**Emits:** `copied`, `error(err)`.
+```vue
+<template>
+  <!-- Inline ID copy, parent fires the toast -->
+  <BaseCopyButton
+    :text="stub.id"
+    label="Stub ID"
+    @copied="showToastMessage('Stub ID copied to clipboard', BaseToastEnum.SUCCESS)"
+    @error="showToastMessage('Failed to copy stub ID', BaseToastEnum.ERROR)"
+  />
+  <!-- Boxed copy next to a read-only input -->
+  <BaseCopyButton :text="mock.id" label="Mock ID" variant="bordered" :reset-ms="2000" />
+</template>
+<script setup lang="ts">
+import { BaseCopyButton, BaseToastEnum } from 'mgv-backoffice'
+</script>
+```
+---
+### BaseChipButton
+Small tinted emerald "chip" action button — the compact "+ Add" pill used
+above repeatable form rows. Label comes from the default slot.
+**Props:**
+| Prop       | Type      | Default | Description |
+| ---------- | --------- | ------- | ----------- |
+| `size`     | `String`  | `'sm'`  | `'sm'` = `px-2.5 py-1`; `'xs'` = `px-2 py-0.5` for tight corners. |
+| `disabled` | `Boolean` | `false` | Dims the chip and blocks clicks. |
+**Emits:** `click`.
+```vue
+<BaseChipButton @click="addRow(rows)">+ Add</BaseChipButton>
+<BaseChipButton size="xs" @click="addNamespace">+ Add</BaseChipButton>
+```
+---
+### BaseRemoveButton
+The red "×" remove-row affordance used beside repeatable form rows. Name it
+for screen readers via `aria-label`; `title`, `disabled` and extra classes
+(`pt-1`, `self-start`, …) fall through as attrs.
+**Emits:** `click`.
+```vue
+<BaseRemoveButton :aria-label="`Remove header ${i + 1}`" @click="rows.splice(i, 1)" />
+```
+---
+### BaseStatusPill
+Connection/health status pill: a colored dot (pulsing while `ok`) next to a
+short label on a tinted background.
+**Props:**
+| Prop     | Type     | Default | Description |
+| -------- | -------- | ------- | ----------- |
+| `status` | `String` | **required** | `'ok'` (emerald, pulsing), `'error'` (red), `'unknown'` (gray). |
+| `label`  | `String` | **required** | Short text next to the dot, e.g. `WireMock Connected`. |
+```vue
+<BaseStatusPill :status="healthy ? 'ok' : 'error'" :label="healthy ? 'Connected' : 'Disconnected'" />
+```
+---
+### BaseFileDropzone
+Dashed "click to select a file" upload zone (extracted from WireMate's
+Postman-import modal). Renders a document-arrow-up icon (overridable via the
+`#icon` slot), a label line, and an optional dimmed hint line. Clicking opens
+the native file picker; dragging files onto the zone also works (the border
+highlights emerald while dragging). The hidden input resets after every
+selection, so picking the same file twice still emits.
+**Props:**
+| Prop       | Type      | Default | Description |
+| ---------- | --------- | ------- | ----------- |
+| `label`    | `String`  | **required** | Main line, e.g. `Click to select a Postman collection (.json)`. |
+| `hint`     | `String`  | `''`    | Dimmed helper line below the label. |
+| `accept`   | `String`  | `''`    | Forwarded to the input's `accept`. Dropped files are **not** filtered by it. |
+| `multiple` | `Boolean` | `false` | Allow multi-select; when `false`, a multi-file drop emits only the first file. |
+| `disabled` | `Boolean` | `false` | Dims the zone and ignores clicks/drops. |
+**Emits:** `files` (`File[]`, never empty).
+**Slots:** `icon` — replaces the default upload icon.
+```vue
+<BaseFileDropzone
+  accept="application/json,.json"
+  label="Click to select a Postman collection (.json)"
+  hint="Exported from Postman → Export → Collection v2.1"
+  @files="onFiles"
+/>
+```
+### BaseCodeBlock
+Themed monospace `<pre>` for JSON payloads, request dumps and code snippets
+(extracted from WireMate's stub/request detail views). Preserves whitespace
+verbatim, scrolls both axes, and adapts to the theme. Extra classes (margins
+etc.) fall through via the normal class merge.
+**Props:**
+| Prop             | Type     | Default  | Description |
+| ---------------- | -------- | -------- | ----------- |
+| `code`           | `String` | **required** | The raw text to render. |
+| `variant`        | `String` | `'soft'` | `'soft'` = tinted fill, no border (in-card look); `'bordered'` = bordered card fill (standalone look). |
+| `size`           | `String` | `'sm'`   | `'sm'` = `text-sm px-5 py-4`; `'xs'` = dense `text-xs p-3`. |
+| `maxHeightClass` | `String` | `''`     | Optional Tailwind max-height utility, e.g. `max-h-96`. |
+```vue
+<BaseCodeBlock :code="formatJson(response.body)" size="xs" max-height-class="max-h-64" />
+```
+---
+## Forms & tables
+These components use `dark:` Tailwind variants, so the consuming app must map
+the `dark` variant to the `.dark` class that `useTheme()` toggles (see
+[Tailwind setup for consumers](#tailwind-setup-for-consumers)).
+### BaseInput
+Themed text/number input carrying the shared field skin (slate border,
+`bg-slate-50` / dark `bg-slate-900` surface). Everything else — `placeholder`,
+`id`, `disabled`, `step`/`min`, extra classes like `font-mono` or
+`placeholder:*` — falls through via attrs and Vue class merging.
+**Props:**
+| Prop         | Type               | Default  | Description |
+| ------------ | ------------------ | -------- | ----------- |
+| `modelValue` | `String \| Number \| null` | `''`     | `v-model` value. |
+| `type`       | `String`           | `'text'` | Native input type. |
+| `size`       | `String`           | `'md'`   | `'md'` = `px-3 py-2`, `'sm'` = `px-2 py-1.5`. |
+| `block`      | `Boolean`          | `true`   | Full-width (`w-full`); set `false` for inline fields. |
+**Emits:** `update:modelValue(value: string)` — always the raw string; parse
+numbers in the owner.
+```vue
+<BaseInput v-model="query" placeholder="e.g. AMD or BTC" class="font-mono" />
+```
+### BaseSelect
+Themed `<select>` sharing BaseInput's field skin. Options come from the
+default slot so callers keep full control of `<option>` rendering.
+**Props:**
+| Prop         | Type               | Default | Description |
+| ------------ | ------------------ | ------- | ----------- |
+| `modelValue` | `String \| null`   | `undefined` | `v-model` value. When left undefined the browser keeps its own default selection. |
+| `size`       | `String`           | `'sm'`  | `'sm'` = `px-2 py-1.5`, `'md'` = `px-3 py-2`. |
+| `block`      | `Boolean`          | `true`  | Full-width; set `false` for inline selects. |
+**Slots:** `default` — the `<option>` elements.
+**Emits:** `update:modelValue(value: string)`.
+```vue
+<BaseSelect v-model="strategyType">
+  <option v-for="e in catalog" :key="e.type" :value="e.type" :title="e.description">
+    {{ e.label }}
+  </option>
+</BaseSelect>
+```
+### BaseDropdown
+Button-style single-select dropdown ("Select Social User ⌄"). Unlike
+`BaseSelect` (a native `<select>`), this renders a trigger button plus a
+floating menu, so the closed control shows a placeholder and a chevron that
+rotates while open — matching the app's filter dropdowns. Selecting a row
+emits its `value` and closes the menu; Escape and an outside click also close
+it.
+**Props:**
+| Prop          | Type                       | Default      | Description |
+| ------------- | -------------------------- | ------------ | ----------- |
+| `options`     | `DropdownOption[]`         | **required** | `{ value, label, title?, disabled? }` per row. |
+| `modelValue`  | `String \| Number \| null` | `null`       | Selected option's `value` (`v-model`). |
+| `placeholder` | `String`                   | `'Select'`   | Trigger text shown when nothing is selected. |
+| `size`        | `String`                   | `'md'`       | `'md'` = `px-4 py-2.5` (app filter height), `'sm'` = `px-3 py-2`. Ignored when `triggerClass` is set. |
+| `block`       | `Boolean`                  | `true`       | Full-width; set `false` for an inline, content-width dropdown. |
+| `disabled`    | `Boolean`                  | `false`      | Disables the trigger. |
+| `ariaLabel`   | `String`                   | `''`         | Accessible name for the trigger/listbox when there is no visible label. |
+| `triggerClass`| `String`                   | `''`         | Replaces the trigger's default slate skin entirely (including the `size` padding). |
+| `chevronClass`| `String`                   | `'w-5 h-5 text-slate-500 dark:text-slate-400'` | Classes for the chevron icon. |
+| `tone`        | `'neutral' \| 'success' \| 'danger'` | `'neutral'` | Tints the default skin (slate / emerald / red) while keeping the `size` padding — e.g. an Active/Paused status dropdown. Ignored when `triggerClass` is set. |
+**Emits:** `update:modelValue(value)`.
+```vue
+<BaseDropdown
+  v-model="socialUserId"
+  :options="socialUsers.map((u) => ({ value: u.id, label: u.name }))"
+  placeholder="Select Social User"
+  aria-label="Social user"
+/>
+```
+### BaseDateTimePicker
+Date / date-time / time picker built on
+[@vuepic/vue-datepicker](https://vue3datepicker.com). The package is a regular
+dependency of this lib (installed automatically) and its CSS ships inside
+`ui-lib.css`, so consumers install and import nothing extra. Dark mode follows
+`useTheme()`; the skin matches BaseInput (slate surfaces, emerald accent).
+**Props:**
+| Prop         | Type               | Default      | Description |
+| ------------ | ------------------ | ------------ | ----------- |
+| `modelValue` | `ModelValue`       | `null`       | `v-model` value — `Date`, `Date[]` for ranges, a time object in `'time'` mode, or a string/number with `model-type`. |
+| `mode`       | `'date' \| 'datetime' \| 'time'` | `'datetime'` | Calendar only, calendar + time, or time only. |
+| `format`     | `String`           | per mode     | date-fns input pattern. Defaults: `dd/MM/yyyy`, `dd/MM/yyyy HH:mm`, `HH:mm` (`hh:mm a` when `is24` is false). |
+| `is24`       | `Boolean`          | `true`       | 24-hour clock. |
+| `autoApply`  | `Boolean`          | `false`      | Select on click, without the Cancel/Select row. |
+| `teleport`   | `Boolean \| String \| HTMLElement` | `true` | Menu mount target; `true` = body, so modals don't clip it. |
+| `timeConfig` | `Partial<TimeConfig>` | —         | Extra time options (seconds, increments…), merged over the defaults. |
+Every other VueDatePicker prop (`range`, `min-date`, `max-date`,
+`disabled-dates`, `placeholder`, `model-type`, …), event and slot is passed
+straight through.
+**Emits:** `update:modelValue(value)`.
+```vue
+<BaseDateTimePicker v-model="startsAt" placeholder="Start" />
+<BaseDateTimePicker v-model="day" mode="date" :min-date="new Date()" auto-apply />
+<BaseDateTimePicker v-model="period" mode="date" range />
+```
+### BaseSegmentedControl
+Segmented button group ("All | Stock | Crypto"). One button per option; the
+selected one gets the filled treatment and `aria-pressed="true"`.
+**Props:**
+| Prop          | Type                | Default  | Description |
+| ------------- | ------------------- | -------- | ----------- |
+| `options`     | `SegmentedOption[]` | **required** | `{ value, label, title? }` per button. |
+| `modelValue`  | `String \| Number`  | **required** | Selected option's `value` (`v-model`). |
+| `variant`     | `String`            | `'base'` | `'base'` (`px-3 py-2`, emerald-500 fill), `'wide'` (`px-4 py-2`, emerald-600 fill), `'toolbar'` (`h-9` uppercase `text-xs` with focus-visible rings). |
+| `ariaLabel`   | `String`            | `''`     | When set, the wrapper renders `role="group"` + `aria-label`. |
+| `optionClass` | `Function`          | —        | `(option, active) => string` override for per-button fill classes (e.g. severity colours); layout stays owned by the variant. |
+**Emits:** `update:modelValue(value)`.
+```vue
+<BaseSegmentedControl v-model="assetFilter" :options="ASSET_FILTERS" />
+<BaseSegmentedControl v-model="exchange" :options="EXCHANGES" variant="wide" aria-label="Exchange" />
+```
+### BaseTable
+Styling shell for data tables — **not** a data grid. Owns the table skin
+(slate header band, `px-4 py-3` header cells, row dividers + hover, empty-state
+row); body rows are the caller's own `<tr>` markup via the default slot. Pass
+`card` for the rounded, bordered, horizontally scrolling card chrome, or wrap
+it yourself (e.g. a `BaseRow` with `overflow-x-auto`).
+**Props:**
+| Prop        | Type            | Default      | Description |
+| ----------- | --------------- | ------------ | ----------- |
+| `columns`   | `TableColumn[]` | **required** | `{ label, align? }`; `align: 'right'` right-aligns the header cell. |
+| `empty`     | `Boolean`       | `false`      | True renders the empty-state row spanning every column. |
+| `emptyText` | `String`        | `'No rows.'` | Fallback empty-state text. |
+| `card`      | `Boolean`       | `false`      | Wrap in the rounded, bordered, scrolling card. |
+**Slots:** `default` — the `<tr>` rows; `empty` — custom empty-state content.
+```vue
+<BaseTable :columns="COLUMNS" :empty="rows.length === 0">
+  <template #empty>No trades match your filters.</template>
+  <tr v-for="row in rows" :key="row.id" class="border-t border-slate-200 dark:border-slate-700">
+    …
+  </tr>
+</BaseTable>
+```
+### BaseSpecFields
+Spec-driven form fields: renders a select / checkbox / number input per
+`SpecField`, with labels and help text, in a responsive two-column grid. Feed
+it a backend-described catalogue and every form editing those values stays in
+lockstep. Never mutates `params` — every edit is emitted as `(key, value)`
+and the owner writes it back into its own state.
+**Props:**
+| Prop     | Type                             | Default      | Description |
+| -------- | -------------------------------- | ------------ | ----------- |
+| `specs`  | `SpecField[]`                    | **required** | `{ key, label, type: 'decimal' \| 'integer' \| 'boolean' \| 'select', default?, options?, step?, min?, help? }` (optional members are nullable). |
+| `params` | `Record<string, SpecFieldValue>` | **required** | Current values keyed by `spec.key`. |
+**Slots:** `after` (`{ spec }`) — extra content under each field (e.g. a live
+preview attached to one key).
+**Emits:** `update(key: string, value: SpecFieldValue)` — numbers are parsed
+(`parseFloat`); unparseable input passes through raw so the owner's
+validation can catch it.
+```vue
+<BaseSpecFields :specs="entry.params" :params="form.params"
+  @update="(key, value) => (form.params[key] = value)" />
+```
+### BaseStatBreakdown
+Compact per-item breakdown meant to sit under a summary/stat card (pairs with
+[`EarningsCard`](#earningscard)). Each item renders on its own line — label
+left, value right in monospace. A `null`/`undefined` value (a source that is
+unconfigured, unreachable, or has no matching rows) shows an em-dash rather
+than a misleading 0. With `signed`, values gain an explicit "+" and are
+coloured green/red by sign (same `"-$3.00"` / `"+$5.00"` shape as `fmtUsd`).
+**Props:**
+| Prop       | Type                  | Default      | Description |
+| ---------- | --------------------- | ------------ | ----------- |
+| `items`    | `StatBreakdownItem[]` | **required** | `{ label, value }` per row. |
+| `currency` | `String`              | `''`         | Currency symbol placed after the sign, e.g. `'$'`. |
+| `decimals` | `Number`              | `2`          | Fraction digits shown for each value. |
+| `signed`   | `Boolean`             | `false`      | Show an explicit "+" on non-negative values and colour rows green/red by sign. |
+```ts
+import type { StatBreakdownItem } from 'mgv-backoffice'
+interface StatBreakdownItem {
+  label: string                      // row label rendered on the left
+  value: number | null | undefined   // null/undefined renders as an em-dash
+}
+```
+```vue
+<EarningsCard title="TOTAL P&L" :amount="totalPnl" signed />
+<BaseStatBreakdown
+  :items="[
+    { label: 'Alpaca', value: 42.5 },
+    { label: 'Binance', value: -3.1 },
+    { label: 'Kraken', value: null },
+  ]"
+  currency="$"
+  signed
+/>
+```
+### BaseFilterChip
+Colour-coded toggleable filter chip — one-click event/category filters above
+a data feed. Idle renders a tinted border/background in the semantic colour;
+active renders a solid fill with white text (`aria-pressed` reflects the
+state). Layout classes (`h-9 flex-1`, …) pass through the class attribute;
+click handlers bind natively on the component.
+**Props:**
+| Prop       | Type      | Default   | Description |
+| ---------- | --------- | --------- | ----------- |
+| `label`    | `String`  | `''`      | Chip text; the default slot overrides it. |
+| `color`    | `'emerald' \| 'sky' \| 'amber' \| 'red' \| 'slate'` | `'slate'` | Semantic colour of the idle tint and active fill. |
+| `active`   | `Boolean` | `false`   | Whether the chip's filter is applied (solid fill). |
+| `disabled` | `Boolean` | `false`   | Greys out + blocks the click. |
+| `title`    | `String`  | —         | Native tooltip. |
+```vue
+<BaseFilterChip
+  v-for="f in filters"
+  :key="f.key"
+  class="h-9 flex-1"
+  :color="f.color"
+  :active="isActive(f)"
+  :title="f.title"
+  @click="toggle(f)"
+>{{ f.label }}</BaseFilterChip>
+```
+### BaseCredentialsForm
+One service's API-credentials card: key id + secret + base/data URLs, with
+the has-secret handling (placeholder dots, blank-keeps-stored-secret), the
+save-validation ladder and a saving spinner. Load/save results are EMITTED —
+the parent owns toasts / error banners. Exposes `load()` so a parent Reload
+button can re-pull several cards in parallel.
+**Props:** `title` + `idPrefix` + `fetchFn: () => Promise<CredentialsView>` +
+`updateFn: (body: CredentialsUpdate) => Promise<CredentialsView>` +
+`defaults: { baseUrl, dataUrl }` (required); `subtitle`, `keyLabel`,
+`keyPlaceholder`, `secretLabel`, `secretPlaceholder`, `secretSetHint`,
+`permissionsHint`, `requiredKeyMessage`, `requiredSecretMessage`,
+`savedMessage`, `saveLabel` (optional copy overrides).
+**Slots:** `no-secret-hint` — rich help while no secret is stored;
+`base-url-extra` (`{ form }`) — extras under the Base URL field (e.g.
+live/paper shortcut buttons that write into the form); `footer` — extra
+content at the card's bottom.
+**Emits:** `saved(message)`, `error(message)`, `load-error(message)`.
+```vue
+<BaseCredentialsForm
+  ref="card"
+  title="Alpaca API"
+  id-prefix="alpaca"
+  :fetch-fn="fetchAlpaca"
+  :update-fn="updateAlpaca"
+  :defaults="{ baseUrl: LIVE_BASE, dataUrl: DATA_URL }"
+  @saved="onSaved"
+  @error="onError"
+  @load-error="onLoadError"
+/>
+```
+---
+### BasePillPickerModal
+"Pick one of many" modal: every item rendered as a clickable pill, narrowed
+by a free-text filter and an optional segmented group toggle. Clicking a pill
+emits `pick` with the item; backdrop / Escape / the footer Close emit `close`.
+Narrowing state lives inside, so a `v-if`-mounted instance always opens fresh.
+**Props:** `title` + `items: PillPickerItem[]` (required);
+`groups?: SegmentedOption<string>[]` (renders the group toggle with an
+`allLabel` option prepended, narrowing by each item's `group`); `icon?`
+(defaults to the magnifying glass), `subtitle?`, `searchPlaceholder`,
+`emptyMessage`, `noMatchMessage`, `mono` (mono font for the filter input and
+pills — symbols, codes, ids), `maxWidthClass` (default `max-w-2xl`),
+`closeText`, `groupAriaLabel`, `allLabel`.
+**Emits:** `pick(item: PillPickerItem)`, `close`.
+```ts
+interface PillPickerItem {
+  id: string      // unique key; identifies the pick
+  label: string   // pill text; what the filter matches
+  group?: string  // segmented-toggle bucket
+  title?: string  // pill tooltip
+}
+```
+```vue
+<BasePillPickerModal
+  v-if="open"
+  title="Symbols"
+  :items="symbols.map(s => ({ id: s.id, label: s.symbol, group: s.assetClass }))"
+  :groups="[{ value: 'STOCK', label: 'STOCK' }, { value: 'CRYPTO', label: 'CRYPTO' }]"
+  mono
+  @pick="apply"
+  @close="open = false"
+/>
+```
+---
+### BaseBarDistribution
+Compact value-distribution chart: one thin rounded bar per distinct
+value, count labelled on top and the value underneath — scrolls
+sideways when there are many bars. Pure Tailwind, no chart library.
+Extracted from TradeAutomation's variant-stats modal.
+**Props:**
+| Prop           | Type     | Default                | Description |
+| -------------- | -------- | ---------------------- | ----------- |
+| `bars`         | `Array`  | **required**           | `DistributionBar[]` — `{ label, count }` per bar, in display order (sort ascending for numeric values). |
+| `ariaLabel`    | `String` | `'Value distribution'` | Accessible description of the chart. |
+| `countNoun`    | `String` | `'item'`               | Noun for each bar's tooltip count, e.g. `'variant'` → "3 variants". |
+| `titlePrefix`  | `String` | `''`                   | Tooltip prefix before the value, e.g. the field name. |
+| `maxBarHeight` | `Number` | `56`                   | Height of the tallest bar, in px. |
+| `barClass`     | `String` | emerald fill           | Tailwind classes for the bar fill. |
+```vue
+<BaseBarDistribution
+  :bars="[{ label: '0.5', count: 1 }, { label: '1', count: 4 }]"
+  aria-label="Distribution of Take profit across variants"
+  title-prefix="Take profit"
+  count-noun="variant"
+/>
+```
+---
+### BaseSearchSelect
+Searchable select (combobox): type to filter, pick with the mouse or
+ArrowUp/ArrowDown + Enter. `multiple` turns it into a tag picker with removable
+chips (Backspace on an empty search removes the last one). Same field skin as
+`BaseInput` / `BaseSelect`; Escape and an outside click close the menu.
+**Props:**
+| Prop            | Type                          | Default         | Description |
+| --------------- | ----------------------------- | --------------- | ----------- |
+| `options`       | `DropdownOption[]`            | **required**    | `{ value, label, title?, disabled? }` per row. |
+| `modelValue`    | `value \| null \| value[]`    | `null`          | Selected value, or values with `multiple`. |
+| `multiple`      | `Boolean`                     | `false`         | Pick several (chips). |
+| `placeholder`   | `String`                      | `'Select'`      | Shown when nothing is selected. |
+| `searchable`    | `Boolean`                     | `true`          | Typing filters the options. |
+| `clearable`     | `Boolean`                     | `true`          | Show the × clear button while something is selected. |
+| `block`         | `Boolean`                     | `true`          | Full-width. |
+| `disabled`      | `Boolean`                     | `false`         | |
+| `ariaLabel`     | `String`                      | `''`            | Accessible name without a visible label. |
+| `noResultsText` | `String`                      | `'No matches.'` | |
+| `emptyText`     | `String`                      | `'No options.'` | |
+**Emits:** `update:modelValue` — the value (single; `null` when cleared) or the
+array of values (`multiple`).
+```vue
+<BaseSearchSelect v-model="userId" :options="users.map(u => ({ value: u.id, label: u.name }))" placeholder="Select User" />
+<BaseSearchSelect v-model="tags" :options="TAGS" multiple />
+```
+### BaseCard
+Bordered surface card — the shared chrome for forms, filter/search panels and
+grouped content.
+**Props:** `title`, `subtitle`, `padding: 'md' | 'sm' | 'none'` (`'md'`).
+**Slots:** `default` (body), `actions` (header, right), `footer` (bottom, right-aligned — submit/cancel).
+```vue
+<BaseCard title="Template">
+  <form>…</form>
+  <template #footer><BaseButton type="submit" description="Save" /></template>
+</BaseCard>
+```
+### BaseField
+Label + control + message wrapper for forms and filter bars.
+**Props:** `label`, `labelFor` (the control's id), `required`, `error`
+(red, replaces the hint), `hint`, `compact` (small uppercase filter-bar label),
+`grow` (takes the free space in a flex row).
+```vue
+<BaseCard padding="sm">
+  <div class="flex flex-wrap items-end gap-4">
+    <BaseField label="Search symbol" label-for="q" compact grow>
+      <BaseInput id="q" v-model="query" />
+    </BaseField>
+    <BaseField label="Class" compact>
+      <BaseSegmentedControl v-model="cls" :options="CLASSES" />
+    </BaseField>
+  </div>
+</BaseCard>
+```
+### BaseStatCard
+Dashboard stat tile in the `EarningsCard` style (dashed accent border, bold
+title, big value) for any value — counts, labels, pre-formatted numbers.
+**Props:** `title` (required), `value`, `subtitle`,
+`accent: 'emerald' | 'sky' | 'amber' | 'red' | 'slate'` (`'emerald'`),
+`to` (router location — makes the whole card a link).
+**Slots:** `icon` (fills the tinted chip; receives `iconClass`), `default` (extra content).
+```vue
+<BaseStatCard title="Categories" :value="71" accent="sky" :to="{ name: 'Category List' }">
+  <template #icon="{ iconClass }"><SwatchIcon :class="iconClass" /></template>
+</BaseStatCard>
+```
+### BaseCheckbox
+Rounded checkbox, emerald when checked (works with or without a forms plugin).
+`v-model` is the boolean; `change` fires with the new value; attrs (`id`, `name`)
+go to the `<input>`.
+**Props:** `modelValue`, `label`, `disabled`. **Slots:** `default` (rich label).
+**Emits:** `update:modelValue(value)`, `change(value)`.
+```vue
+<BaseCheckbox v-model="remember" id="remember" label="Remember me" />
+```
+### BaseToggle
+On/off switch (`role="switch"`). `v-model` is the boolean; `change` fires after
+every user toggle with the new value.
+**Props:** `modelValue`, `label` (visible label, also the accessible name),
+`ariaLabel` (when there is no label), `color: 'emerald' | 'red' | 'sky' | 'amber'`
+(on state, `'emerald'`), `offTone: 'slate' | 'red'` (off track, `'slate'`), `disabled`.
+**Emits:** `update:modelValue(value)`, `change(value)`.
+```vue
+<BaseToggle v-model="task.alive" :label="task.name" color="red" @change="save(task)" />
+<BaseToggle v-model="account.alive" off-tone="red" aria-label="Alive" />
+```
+### BaseAuthLayout
+Full-page, centred shell for sign-in / sign-up / password-recovery screens:
+logo on top (defaults to `BaseLogo`), then a bordered card with the title,
+content and an optional footer.
+**Props:** `title`, `subtitle`, `wide` (max-w-3xl card for multi-column forms; default max-w-md).
+**Slots:** `default` (form), `logo` (replaces `BaseLogo`), `footer` ("No account? Sign up").
+```vue
+<BaseAuthLayout title="Forgot password">
+  <form>…</form>
+  <template #footer>No account? <RouterLink to="/register">Sign up</RouterLink></template>
+</BaseAuthLayout>
+```
+### BaseBooleanBadge
+Yes/no pill for boolean columns: green check when true, red cross when false.
+**Props:** `value` (`boolean | null`), `trueLabel` (`'Yes'`), `falseLabel` (`'No'`).
+```vue
+<BaseBooleanBadge :value="user.hasVerifiedEmail" true-label="Verified" false-label="Not verified" />
+```
+### BaseDetailList
+Read-only label/value grid for detail pages (the "view" counterpart of a form).
+Empty values show `emptyText`; `href` renders the value as an external link;
+`mono` uses the monospace face.
+**Props:** `items: DetailItem[]` (`{ label, value?, href?, mono? }`, required),
+`columns: 1 | 2 | 3` (`2`, from `sm` up), `emptyText` (`'—'`).
+```vue
+<BaseCard title="Details">
+  <BaseDetailList :items="[{ label: 'Status', value: post.status }, { label: 'Link', value: post.link, href: post.link }]" />
+</BaseCard>
+```
+## Composables
+```ts
+import {
+  initTheme,
+  useTheme,
+  useThemeClasses,
+  useEscapeKey,
+  useDebouncedRef,
+  useToast,
+  useMobileSidebar,
+  useSidebarCollapse,
+  useNotifications,
+  useQueryParamSync,
+  useFieldClasses,
+  usePolling,
+} from 'mgv-backoffice'
+import type {
+  UseThemeOptions,
+  UseSidebarCollapseOptions,
+  UsePollingOptions,
+} from 'mgv-backoffice'
+```
+| Composable | Purpose |
+| ---------- | ------- |
+| `initTheme({ storageKey? })` | Explicitly initialize the theme singleton. Call in your app entry point **before mounting** when you need a custom storage key — library components call `useTheme()` internally, so a component mounting first would otherwise lock in the default key (a dev-mode warning fires if that happens). |
+| `useTheme({ storageKey? })` | Singleton dark/light controller. Toggles `<html class="dark">` and persists via localStorage (default key `'mgv-theme'`). Prefer `initTheme` at app entry for custom keys. |
+| `useThemeClasses()` | Named Tailwind class roles for dark/light (card, border, primaryText, mutedText, dimText, input, ghostButton, emeraldText, redText, …). Since 1.34.0 returns a `reactive` object of plain strings — bind `t.card` directly, never `t.card.value` (the old ComputedRef shape leaked ref internals into `:class` bindings). |
+| `useEscapeKey(handler)` | Component-scoped Escape key listener. |
+| `useDebouncedRef(source, delay?)` | Debounced mirror of a ref. Timer cleared on scope dispose. |
+| `useToast(durationMs?)` | Per-component toast state: `{ showToast, toastMessage, toastType, showToastMessage }`. `showToastMessage` also accepts a per-call duration override. |
+| `useMobileSidebar()` | Singleton state shared between `BaseSidebar` and `BaseAppLayout` for the off-canvas open/closed flag. |
+| `useSidebarCollapse({ storageKey? })` | Singleton collapsed/expanded state for the desktop sidebar rail, shared between `BaseSidebar` and `BaseAppLayout` and persisted to localStorage (default key `'mgv-sidebar-collapsed'`). |
+| `useNotifications()` | Singleton notification state shared by the sidebar bell and `BaseNotificationPanel`: `{ notifications, unreadCount, open, openPanel, closePanel, togglePanel, setNotifications, add, remove, markRead, markAllRead, clear }`. |
+| `useQueryParamSync()` | URL-query mirroring for filterable views: `{ qparam(name), qenum(name, allowed, fallback), replaceQuery(next) }`. Read filters from the query string once on setup, write changes back with `router.replace` (no-op when unchanged) so filtered views stay shareable without polluting history. |
+| `useFieldClasses()` | Shared form-field class strings for the gray/emerald form skin: `{ label, input, requiredInput(value) }`. `requiredInput` returns a red border+ring skin while the value is empty and the standard skin otherwise. |
+| `usePolling(fn, intervalMs, { immediate?, pauseWhenHidden? })` | Visibility-gated polling loop bound to the component lifecycle: starts on mount, stops on unmount, pauses while the tab is hidden and refreshes + resumes on return to visible (both default on). Pass `intervalMs: null` for refresh-only mode (run on mount + each return-to-visible, no timer). Returns `{ start, stop, active }`. A loop stopped via `stop()` stays stopped across hide/show cycles (since 1.36.0) — only a visibility-paused loop auto-resumes. Catch errors inside `fn` — the loop never swallows rejections. |
+---
+## Typography
+Since 1.33.0 the library ships the shared brand typography: the stylesheet
+loads **Fira Sans** (UI text) and **Fira Code** (numerals/data) from Google
+Fonts via `@import`, registers them as the Tailwind `--font-sans` /
+`--font-mono` theme defaults, and applies `font-family: var(--font-sans)` to
+`body`. Consumers get the fonts just by importing the lib CSS — remove any
+app-local Google Fonts `<link rel="stylesheet">` and `--font-sans`/`--font-mono`
+overrides. Keep (or add) the preconnect hints in `index.html` for a faster
+first paint:
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+```
+## Tailwind setup for consumers
+The lib's components rely on Tailwind utility classes (including dark-mode
+variants). Consumers should add the lib's `dist` output to their Tailwind
+`content` paths so the JIT can see the class names:
+```js
+// tailwind.config.js
+export default {
+  content: [
+    './index.html',
+    './src/**/*.{vue,ts}',
+    './node_modules/mgv-backoffice/dist/**/*.{js,mjs,cjs,vue}',
+  ],
+}
+```
+The legacy `tailwind.safelist.js` only covers the v1 components; the
+recommended path for v4+ is the `content` glob above.