Integration guide

How it works

A widget is a standard web component. Your page loads one module, drops one custom element, and assigns the rows. Nothing else is required — no build step, no wrapper library, no framework in particular.

Quick start

All three of these are working today against this deployment. Every widget page has the same snippets pre-filled with that widget's own columns and sample rows — start from there. If you are picking a first widget, Pull-Through is the one we suggest.

<!-- 1. Load the widget. It self-registers <afn-pullthrough>. -->
<script type="module" src="https://widgets-d.afnai.com/cdn/afn-pullthrough/v1/afn-pullthrough.js"></script>

<!-- 2. Drop the tag wherever you want it. -->
<afn-pullthrough id="w"></afn-pullthrough>

<!-- 3. Feed it rows. -->
<script>
  const el = document.querySelector('#w');
  el.data = [
    { Category: 'Started',      BranchCount: 235, PeerGroupCount: 1120, CompanyCount: 16491 },
    { Category: 'Credit Pulled', BranchCount: 195, PeerGroupCount: 946, CompanyCount: 13720 },
    { Category: 'Funded',       BranchCount: 71,  PeerGroupCount: 340,  CompanyCount: 3253 }
  ];
  el.params = { cohort: 'BranchCount' };
</script>

import { createElement, useEffect, useRef } from 'react';

const CDN = 'https://widgets-d.afnai.com';
const loaded = new Set();

function ensureLoaded(tag, channel) {
  const key = `${tag}@${channel}`;
  if (loaded.has(key)) return;
  loaded.add(key);
  const s = document.createElement('script');
  s.type = 'module';
  s.src = `${CDN}/cdn/${tag}/${channel}/${tag}.js`;
  document.head.appendChild(s);
}

// Works on React 18 and 19. React <=18 stringifies unknown props, so object
// data has to be assigned to the element itself -- and only once the custom
// element is defined, because its module loads asynchronously.
export function AfnWidget({ tag, channel = 'v1', data, params, options, style }) {
  const ref = useRef(null);

  useEffect(() => { ensureLoaded(tag, channel); }, [tag, channel]);

  useEffect(() => {
    let cancelled = false;
    customElements.whenDefined(tag).then(() => {
      const el = ref.current;
      if (cancelled || !el) return;
      if (data !== undefined) el.data = data;
      if (params !== undefined) el.params = params;
      if (options !== undefined) el.options = options;
    });
    return () => { cancelled = true; };
  }, [tag, data, params, options]);

  return createElement(tag, { ref, style });
}

<AfnWidget
  tag="afn-pullthrough"
  data={rows}
  params={{ cohort: 'BranchCount' }}
  options={{ theme: 'dark' }}
/>

// wwwroot/js/widget-interop.js -- reference it from index.html.
// Blazor cannot assign object-valued DOM properties directly, so it calls
// this through IJSRuntime. Waiting on whenDefined matters: the widget's
// module is still loading when OnAfterRenderAsync first fires.
window.setWidgetData = async (el, tag, data, params, options) => {
  await customElements.whenDefined(tag);
  if (data) el.data = data;
  if (params) el.params = params;
  if (options) el.options = options;
};

<afn-pullthrough @ref="el"></afn-pullthrough>

@code {
    private ElementReference el;
    [Inject] private IJSRuntime JS { get; set; } = default!;

    // Use List<Dictionary<string, object>>, NOT typed records. Blazor's JSON
    // options camel-case property names but leave dictionary keys alone, so
    // this is what gets your column names across verbatim.
    private readonly List<Dictionary<string, object>> rows = new()
    {
        new() { ["Category"] = "Started", ["BranchCount"] = 235 },
        new() { ["Category"] = "Funded",  ["BranchCount"] = 71  }
    };

    protected override async Task OnAfterRenderAsync(bool first)
    {
        if (first)
            await JS.InvokeVoidAsync("setWidgetData", el, "afn-pullthrough", rows, null, null);
    }
}

The contract

Three properties, and only the first is required.

Assigning any of them re-renders. Sizing is automatic — the widget observes its own container, so give the element a width and it fills it.

The contract is readable at runtime, which is handy in tests:

// Every widget declares its own contract as a static property. This is the
// authoritative list of columns -- the same one shown on each widget's page.
const contract = customElements.get('afn-pullthrough').contract;

contract.version   // '1.0.0'
contract.data      // [{ name: 'Category', type: 'string', required: true }, ...]
contract.params    // [{ name: 'cohort', type: 'enum', values: [...], default: ... }]

Three events are emitted:

const el = document.querySelector('afn-pullthrough');

// Fired once the widget has rendered with the data you gave it.
el.addEventListener('ready', e => console.log('rendered', e.detail));

// Fired instead of 'ready' when the rows do not satisfy the contract. The
// widget shows its own error card, so you do not have to handle this.
el.addEventListener('error', e => console.warn('widget error', e.detail));

// Fired when the user clicks a mark. See "Clicks and drill-down" below.
el.addEventListener('widget-select', e => console.log('clicked', e.detail));

// A widget also declares what it emits, so you can check at runtime:
el.constructor.contract.events;   // ['ready', 'error', 'widget-select']

Clicks and drill-down

Widgets do not navigate anywhere or open anything by themselves — what a click means belongs to your app. Every widget reports the click through one event, widget-select, and you decide what happens: route to a detail page, open a drawer, filter a sibling widget, log it.

const el = document.querySelector('afn-pullthrough');

el.addEventListener('widget-select', (e) => {
  const { label, value, formatted, series, index, rows, params } = e.detail;

  // `rows` holds the ORIGINAL row objects you fed in -- the same object
  // references, not copies -- so anything extra you carried on a row
  // (an id, a URL, a foreign key) is still there to drill down with.
  const loanId = rows[0].YourOwnIdColumn;

  window.location = `/loans?stage=${encodeURIComponent(label)}&id=${loanId}`;
});

// The event bubbles and crosses the shadow boundary, so one listener on a
// container works for a whole dashboard of widgets:
dashboard.addEventListener('widget-select', (e) => route(e.detail));

What the payload carries

Making it look clickable

// The event fires whether or not you set this. `interactive` only turns on
// the hover/focus affordance -- a widget nobody listens to should not look
// clickable, so it is off by default. Set it when you ARE handling clicks.
el.options = { interactive: true };

On the card and leaderboard widgets this also makes each tile or row a real button — focusable, and activated by Enter or Space — so drill-down is not mouse-only. Chart marks are not individually keyboard-reachable; if that matters for your audience, keep a non-chart route to the same destination.

Two behaviours worth knowing

• Line and area charts report the category, not one point. A line is a couple of pixels wide, so a click anywhere in the plot area resolves to the nearest category — the same thing its tooltip already does. On a multi-series line that means series and value come back null and rows holds every series' row for that category, because adding unrelated series together (ratings, turn times) would be meaningless. Clicking exactly on a point marker still gives you the precise series.
• Gauges and activity rings resolve by position. A gauge has one datum, so anywhere on the dial reports that metric. Rings report whichever concentric band you clicked; the gap between bands and the hole in the middle report nothing at all.

Colours

Every colour in every widget can be replaced from your own stylesheet. You do not have to — leave it alone and you get the AFN palette, which is the right answer for most internal apps. But if the widget has to sit inside your brand, set custom properties on the element and it will follow.

/* Set as many or as few as you like. Anything you leave out keeps the
   widget's own default, so a partial override still looks coherent. */
afn-pullthrough {
  /* chart: one monochrome scale, interpolated to whatever length the
     chart needs -- 9 funnel stages, a choropleth gradient, a gauge arc */
  --afnw-ramp-from: #fed7aa;
  --afnw-ramp-to:   #7c2d12;

  /* ...or control discrete series individually instead */
  /* --afnw-series-1: #f0abfc;  --afnw-series-2: #e879f9; */

  /* card */
  --afnw-surface:   #fffbf5;
  --afnw-ink:       #431407;
  --afnw-muted:     #a8734a;
  --afnw-accent:    #c2410c;
}

Each widget's page generates this block for you, pre-filled with that widget's own current values — switch Colours to add my brand in the embed panel. That is the easiest way to start, since the var set differs by chart type.

Chart colours: two ways

Card colours

Without CSS

// Equivalent to the CSS above, for a brand colour that arrives at
// runtime rather than sitting in a stylesheet.
el.options = {
  colors: { 'ramp-from': '#fed7aa', 'ramp-to': '#7c2d12', ink: '#431407' }
};

Where your data comes from

Entirely your call. A widget cannot tell whether its rows came from SQL, a REST call, a cache or a hard-coded fixture — it only checks that the columns are there. So use whatever your app already uses, and shape the result to the contract.

Versions

Every widget URL carries a version. You choose how much movement you accept.

A major bump means the data contract changed — a new required column, a rename, a different row shape. That is the only thing that can break your integration, and it can never reach you through a vN URL: a new major gets a new URL, and yours keeps working. Patch and minor releases are exactly the promise that your existing rows keep rendering.

Before you embed: tell us your origin

When something breaks

One note on page weight: widgets share a single copy of their charting library, fetched once per page from this host regardless of how many widgets you embed. Twenty widgets on a page cost roughly one library download, not twenty.