Widgets

@navapatra/widgets is a set of web components (built with Lit 3) that display API JSON. They work in plain HTML, React, Vue, Svelte and anything else that renders DOM.

Element	Shows	data accepts
<kundali-chart>	The chart SVG, with tooltips and keyboard navigation	/v1/kundali with include: ["svg"] (add "svg.south" for both styles), /v1/charts/svg JSON, or an SVG string
<dasha-table>	A dasha timeline, current period highlighted	/v1/dasha, or /v1/kundali (its dashas)
<panchang-card>	A day’s panchang and choghadiya	/v1/panchang/day
<match-score>	A guna milan score with kootas and doshas	/v1/matching/ashtakoota, or one item of a batch results

<kundali-chart> never draws a chart in the browser. It shows the SVG the API rendered and adds interaction; data without an svg shows an error state.

Install

npm install @navapatra/widgets

import '@navapatra/widgets'; // registers all four elements

Or load one self-registering file from a CDN (Lit included):

<script src="https://cdn.jsdelivr.net/npm/@navapatra/widgets/dist/widgets.iife.js"></script>

The package is published to npm with the first public release.

Display data from your server

The recommended setup: your backend calls the API with a secret key, and the page hands the JSON to the element.

<kundali-chart id="chart" lang="ne"></kundali-chart>

<script type="module">
  // Your backend calls POST /v1/kundali with include: ["svg"] and returns the JSON.
  const res = await fetch('/api/my-kundali');
  document.getElementById('chart').data = await res.json();
</script>

You can also fetch with a client token in your own code and set .data, or let the widget fetch with it (below).

Fetch mode

A widget can call the API itself when you give it a browser-safe credential in its publishable-key attribute:

• a publishable key (pk_) whose allowlist includes your site’s origin, or
• a client token (ct_) that your server created with POST /v1/tokens: at most 15 minutes, only the endpoints you scoped, an optional credit cap. See Mobile apps and the backend proxy.

<kundali-chart
  publishable-key="pk_..."
  endpoint="/v1/charts/svg"
  request='{"birth":{"date":"1990-05-15","time":"10:30","place":{"query":"Kathmandu"}}}'
></kundali-chart>

endpoint is resolved against https://api.navapatra.com/v1/ (a full URL also works). With request the widget sends a POST with that JSON body; without it, a GET. The element fires kc-load (detail: the JSON) and kc-error (detail: { code, status, message }).

When a client token expires, the API answers token_expired and the widget fires kc-error; fetch a new token from your backend and set publishable-key again, and the widget fetches again.

A secret key (sk_) is refused in the browser with a console warning and a secret_key_in_browser error, and any other value fails with invalid_key. Remember that Origin is advisory: give publishable keys a credit cap. See Authentication.

Attributes

Attribute	Elements	Meaning
lang	all	en, ne or hi for the widget’s own labels; inherited from the nearest [lang]. Labels inside the data come from the API in the language you requested.
numerals	all	latin or devanagari. Default: Devanagari for ne and hi.
chart-style	kundali-chart	north (default) or south, for kundali responses that carry both
system	dasha-table	vimshottari (default), yogini or tribhagi, for kundali responses
hide-choghadiya	panchang-card	Hides the choghadiya lists

<dasha-table> highlights the current period when the request included options.asOf.

Theming

Set custom properties on the element or an ancestor. Defaults follow the design tokens when the page loads them, with built-in light and dark values otherwise.

Property	Used for
--kc-bg, --kc-surface, --kc-border	Card background, inset panels, borders
--kc-line	Chart lines
--kc-text, --kc-text-2, --kc-muted	Text, secondary rows, labels
--kc-accent, --kc-accent-soft	Lagna, current period, score; their highlights
--kc-success, --kc-danger	Dosha badges, errors
--kc-font, --kc-font-mono	Text; dates, times and points
--kc-radius, --kc-radius-sm	Corners
--kc-tooltip-bg, --kc-tooltip-text	Chart tooltip
--kc-duration	Transitions

The chart SVG inside reads the variables in Charts and SVG theming.

Accessibility

• <kundali-chart> is one focusable group named by the chart title. Arrow keys, Home and End move between the lagna and the grahas, Escape hides the tooltip, and each placement is announced. A visually hidden list gives every placement as text.
• Tooltips open on hover and touch as well as focus.
• Motion is limited to short fades and is removed under prefers-reduced-motion.

React

import { KundaliChart, PanchangCard } from '@navapatra/widgets/react';

<KundaliChart data={kundali} chartStyle="south" lang="ne" onKcError={(e) => console.warn(e.detail)} />;

The wrapper sets data and the other properties as DOM properties, so objects are not stringified into attributes. react is an optional peer dependency.