@tenders-sa-org/widget-intel

Tenders-SA Intelligence Widgets — Shadow DOM-based embeddable procurement intelligence widgets. Vanilla JS, zero framework dependencies, self-initializing.

Installation

Script tag (CDN)

<script src="https://cdn.jsdelivr.net/npm/@tenders-sa-org/widget-intel@latest/dist/widget-intel.global.js" async></script>

npm

npm install @tenders-sa-org/widget-intel

Then import and call init():

import { init } from '@tenders-sa-org/widget-intel'
init()

Widget Types

| Type | Description | Attribute Value | |-------------------------|--------------------------------------|---------------------------| | Province Health Badge | Single province health score circle | province-health-badge | | Province Health Bar | Horizontal bars for multiple provinces| province-health-bar | | Intelligence Feed | Scrolling list of intelligence items | intelligence-feed | | Ticker | Horizontal scrolling headlines | ticker | | Province Heatmap | Grid of all province health scores | province-heatmap |

Usage

Place any element with data-tsa-widget and data-token attributes anywhere on your page. The widget auto-initializes on DOMContentLoaded.

Province Health Badge

Shows a single province's health score as a color-coded circle with status label.

<div
  data-tsa-widget="province-health-badge"
  data-token="pub_your_token_here"
  data-theme="light"
></div>

Supports data-province to specify which province (optional — backend resolves from token).

Province Health Bar

Renders horizontal health bars for multiple provinces. Color-coded by status.

<div
  data-tsa-widget="province-health-bar"
  data-token="pub_your_token_here"
  data-provinces="GP,WC,KZN"
  data-theme="light"
></div>

Intelligence Feed

Displays a feed of procurement intelligence items with title, source, category, and date.

<div
  data-tsa-widget="intelligence-feed"
  data-token="pub_your_token_here"
  data-theme="dark"
></div>

Ticker

Horizontal scrolling ticker of procurement headlines. Pauses on hover.

<div
  data-tsa-widget="ticker"
  data-token="pub_your_token_here"
  data-theme="light"
></div>

Province Heatmap

Shows all province health scores in a responsive grid, color-coded by status.

<div
  data-tsa-widget="province-heatmap"
  data-token="pub_your_token_here"
  data-theme="dark"
></div>

Attributes

| Attribute | Required | Default | Description | |---------------------|----------|----------|------------------------------------------------| | data-tsa-widget | yes | — | Widget type identifier | | data-token | yes | — | Publisher token (prefixed pub_) | | data-theme | no | light | Theme: light or dark | | data-provinces | no | — | Comma-separated province codes (GP,WC,KZN) |

JavaScript API

import { init, scanWidgets, TsaBadge, TsaHealthBar, TsaFeed, TsaTicker, TsaHeatmap } from '@tenders-sa-org/widget-intel'

// Manually re-scan for widgets
scanWidgets()

// Initialize (same as auto-init)
init()

Theming

All widgets support light and dark themes via the data-theme attribute. Theme-aware variables are scoped inside Shadow DOM — no global style leakage.

Impression Tracking

Widgets automatically send a one-time POST impression event to the API on first successful data load.

Polling

Widgets poll the API every 5 minutes for updated data. Polling automatically refetches and re-renders.

Browser Support

• Chrome 80+
• Firefox 75+
• Safari 13.1+
• Edge 80+

Requires Shadow DOM v1 and CustomEvent support.

Development

# Install
npm install

# Build
npm run build

# Watch mode
npm run dev

# Type check
npm run typecheck

# Test
npm run test

License

MIT