SLA Widget

**A lightweight, framework‑agnostic component to display the health status of
your services.** Works with vanilla JS, React, Next.js, or straight from a CDN.

---

🚀 Quick Start (Minimal Example)

$3

``html
type="module"
src="https://cdn.jsdelivr.net/npm/@chainlove/sla-widget/dist/vanilla.mjs"
>


`

- Live demo on CodePen
- Live demo on StackBlitz

---

✨ Features

- 🚀 Drop-in integration (Web Component or React)
- 🎨 4 themes: light, dark, highContrast, auto
- 🖼️ Flexible placement: embedded panel or banner
- 🔎 Detail levels: full or problemsOnly
- 🔄 Auto-refresh (configurable)
- 💬 Custom messages per health state
- ⚠️ Graceful degradation on API failure
- 🌍 CDN or npm / yarn / pnpm
- 📦 Tiny bundle size

---

📦 Installation

$3

`bash
npm install @chainlove/sla-widget


or

yarn add @chainlove/sla-widget

or

pnpm add @chainlove/sla-widget
`

$3

`html
type="module"
src="https://cdn.jsdelivr.net/npm/@chainlove/sla-widget/dist/vanilla.mjs"
>
`

---

🏃 Usage

$3

`html
service-ids="0x123...,0x456..."
details="full"
theme="auto"
position="banner"
>
`

- Live demo on CodePen
- Live demo on StackBlitz

---

$3

`tsx
import { SLAWidget } from '@chainlove/sla-widget/react';

serviceIds={['0x123...', '0x456...']}
details="full"
theme="auto"
position="banner"
/>;
`

- Live demo on StackBlitz

---

$3

`html



`

- Live demo on CodePen
- Live demo on StackBlitz

---

⚙️ Widget Options (All Modes)

$3

#### Usage:

- React / CoreJS: serviceIds → string[]
- Web Component (HTML): service-ids → comma-separated string

#### Type:

- React/CoreJS → string[] Example: ['0x123...', '0x456...']
- Web Component → comma-separated string Example: "0x123...,0x456..."

#### Description:

List of Service IDs to display.

🔊 You can dynamically update this list:

- React: by updating the serviceIds prop
- Web Component: by calling element.setAttribute('service-ids', '...')

---

$3

#### Usage:

- React / CoreJS: statusEndpoint → string
- Web Component (HTML): status-endpoint → string

#### Default: 'API_URL'

API endpoint URL for fetching service status.

---

$3

#### Usage:

- React / CoreJS: refreshIntervalMs → number
- Web Component (HTML): refresh-interval-ms → number

#### Default: false (disabled)

How it works:

- The widget fetches data from API endpoint (statusEndpoint).

Behavior:

- If you set refreshIntervalMs = false (default), the widget fetches data
once, when the page loads.
- If you set refreshIntervalMs to a value (e.g. 5000 = 5 sec), the widget
will update data at that interval

---

$3

#### Usage:

- React / CoreJS: theme → 'light' | 'dark' | 'highContrast' |
'auto'
- Web Component (HTML): theme → same values

#### Default: 'auto'

Widget theme. 🔊 Can be changed dynamically.

---

$3

#### Usage:

- React / CoreJS: position → 'banner' | 'embedded'
- Web Component (HTML): position → same values

#### Default: 'banner'

Widget position on the page:

- position="banner" → widget is displayed as a banner at the top of the
site.
- position="embedded" → widget is displayed as an inline block (you can place
it anywhere in the page).

---

$3

#### Usage:

- React / CoreJS: details → 'full' | 'problemsOnly'
- Web Component (HTML): details → same values

#### Default: 'problemsOnly'

Controls when the widget is shown:

- details="full" → widget is always visible.
- details="problemsOnly" → widget is shown only if one or more services in
service ids have Downtime or Latency. It disappears if all services
are in Uptime.

---

$3

#### Usage:

- React / CoreJS: mode → 'simple' | 'dev'
- Web Component (HTML): mode → same values

#### Default: 'simple'

Controls the display mode of the widget:

- mode="simple" → the widget shows a compact banner or embedded block:

- If any service has Downtime (error) or Latency (warning), the
banner displays a custom message (see customMessages / custom-messages
option below).
- If all service are healthy (ok), the banner may be hidden (if
details='problemsOnly') or show a neutral state (if details='full').

Example for customizing messages (for Web Component):

`html
custom-messages='{"warning":"⚠️ Check this","error":"🚨 Critical issue"}'
`

Example for customizing messages (for React):

`tsx
...
customMessages={{
warning: "⚠️ Check this",
error: "🚨 Critical issue",
}}
/>
`

- mode="dev" → the widget displays a detailed panel with:

- full list of all service
- current health status for each service
- latency / downtime metrics
- useful for debugging and monitoring purposes.

🔊 Typical usage:

- Use 'simple' for production websites and user-facing pages.
- Use 'dev' for internal dashboards, monitoring panels, or while testing.

---

$3

#### Usage:

- React / CoreJS: pinned → 'slide' \| 'fixed'
- Web Component (HTML): pinned → same values

#### Default: 'slide'

Widget pinning behavior:

- 'slide' → widget is placed at the top of the page, **inside the normal page
flow**.
When the user scrolls down, the widget will scroll out of view (i.e. it moves
with the page).
- 'fixed' → widget is pinned to the viewport (CSS position: fixed) and
remains always visible, even when the user scrolls the page.

👉 Use 'fixed' if you want the widget to stay on screen at all times.
Use 'slide' for more lightweight appearance (standard banner behavior at top
of page).

---

$3

#### Usage:

- React / CoreJS: customMessages → { [key in Health]?: string }
- Web Component (HTML): custom-messages → JSON string

#### Default: {}

Custom text to display for each health state. 🔊 Works **only in
mode="simple"**.

You can override the default built-in labels with your own text or icons for:

- UP → when all services are healthy
- LATENCY → when one or more services have high latency
- DOWN → when one or more services are down
- UNKNOWN → when the status of one or more services is unknown

#### Possible keys of Health:

`typescript
export type Health = 'UP' | 'LATENCY' | 'DOWN' | 'UNKNOWN';
`

#### Example for Web Component:

`html
...
custom-messages='{"UP":"✅ All systems operational","LATENCY":"⚠️ Some delays","DOWN":"🚨 Outage detected","UNKNOWN":"❔ Status unknown"}'
>
`

#### Example for React:

`tsx
...
customMessages={{
UP: "✅ All systems operational",
LATENCY: "⚠️ Some delays",
DOWN: "🚨 Outage detected",
UNKNOWN: "❔ Status unknown",
}}
``

---

Additionally, when using the widget, you can dynamically adjust settings
(mode, details) by clicking the ⚙️ settings button inside the widget.

---

⚡️ Contributing

Feel free to open issues, submit pull requests, or suggest improvements!

---

📄 License

MIT