Component API

Shared UI components live in shared/dt-utils.js and are available as simple JavaScript functions. Each function accepts an options object and returns a DOM element or modifies an existing one.

## KPI Card

The most common component. Displays a metric value, label, trend indicator, and optional sparkline.

<!-- HTML structure -->
<div class="dt-kpi-card" id="kpi-revenue">
  <p class="dt-kpi-card__label">Monthly Revenue</p>
  <p class="dt-kpi-card__value">$0</p>
  <p class="dt-kpi-card__trend dt-kpi-card__trend--up">+12.4%</p>
</div>

// Update via JS
import { updateKPI } from '../../shared/dt-utils.js';

updateKPI('kpi-revenue', {
  value:     '$71,200',
  trend:     '+12.4%',
  direction: 'up',       // 'up' | 'down' | 'neutral'
});

### KPI Card options

Option	Type	Default	Description
`value`	string	—	Formatted metric value (e.g. `"$71.2k"`)
`trend`	string	—	Trend label (e.g. `"+12.4%"`)
`direction`	'up' \| 'down' \| 'neutral'	'neutral'	Controls colour of trend badge
`sub`	string	—	Optional sub-label below the trend

## Data Table

A sortable, filterable table component used in list-heavy templates (pipeline, HR, etc.).

import { createDataTable } from '../../shared/dt-utils.js';

const table = createDataTable({
  container: document.getElementById('deals-table'),
  columns: [
    { key: 'account', label: 'Account',  sortable: true  },
    { key: 'stage',   label: 'Stage',    sortable: true  },
    { key: 'value',   label: 'Value',    sortable: true, format: 'currency' },
    { key: 'close',   label: 'Close Date', sortable: true, format: 'date'  },
  ],
  rows: dealsData,   // array of objects matching column keys
  pageSize: 10,
});

### Column options

Option	Type	Description
`key`	string	Property name in the data row object
`label`	string	Column header text
`sortable`	boolean	Enable click-to-sort on this column
`format`	'currency' \| 'date' \| 'percent' \| 'number'	Apply a built-in formatter to cell values
`render`	(value, row) => string	Custom HTML renderer (overrides `format`)

## Progress / Gauge Bar

<div class="dt-progress" id="quota-bar"></div>

import { setProgress } from '../../shared/dt-utils.js';

setProgress('quota-bar', {
  value:   73,          // 0–100
  label:   'Quota attainment',
  color:   'var(--dt-brand)',
  animate: true,        // slide-in animation on first render
});

## Badge

<span class="dt-badge dt-badge--green">On Track</span>
<span class="dt-badge dt-badge--red">At Risk</span>
<span class="dt-badge dt-badge--yellow">Needs Review</span>
<span class="dt-badge dt-badge--gray">Inactive</span>

## Date Range Picker

Templates with time-series data include a lightweight date-range control:

import { DateRangePicker } from '../../shared/dt-utils.js';

const picker = new DateRangePicker({
  container: document.getElementById('date-picker'),
  presets:   ['7d', '30d', '90d', 'YTD'],
  default:   '30d',
  onChange:  (from, to) => {
    refreshCharts(from, to);   // re-fetch data for the new range
  },
});

## Formatter utilities

import { fmt } from '../../shared/dt-utils.js';

fmt.currency(71200);         // "$71,200"
fmt.currency(71200, 'EUR'); // "€71,200"
fmt.percent(0.1243);         // "12.4%"
fmt.number(1234567);         // "1,234,567"
fmt.compact(1234567);        // "1.2M"
fmt.date('2024-06-15');      // "Jun 15, 2024"