@metaboliccode-dev/widget

Publishable React library: shell layout, side navigation, lazy-loaded tabbed dashboard views, optional practitioner/patient simulation, token-based theming (MetabolicDashboardConfig → CSS variables), HTTP-backed default tabs (built-in API base URL and API key gate), and a standalone iframe build for embedding.

Requirements

• Node.js and npm
• React 18+ / react-dom 18+ (peer dependencies)

Development

npm install
npm run dev:iframe

Runs the iframe embed entry locally (see vite.config.iframe.ts).

Scripts

| Command | Description | | --- | --- | | npm run build | Library ESM + CSS + declarations (dist/) and iframe bundle (dist-iframe/) | | npm run build:lib | Library only | | npm run build:iframe | Iframe bundle only | | npm run preview:iframe | Preview built iframe | | npm run typecheck | tsc on src/ | | npm run test / npm run test:run | Vitest runner (vitest.config.ts). The checked-in suite covers request headers, bulk report availability, suggested products mapping, and disabled side-menu behavior. See Development → Testing. | | npm run lint / npm run lint:fix | Biome | | npm run docs:api | TypeDoc API docs |

Layout

| Path | Role | | --- | --- | | src/ | Library source (MetabolicDashboard, tabs, branding, API mappers) | | src/public/ | Default logos, triad icons, and placeholders bundled with the library | | dist/ | Published ESM library output | | dist-iframe/ | Static iframe app after npm run build:iframe |

Documentation

| Document | Description | |----------|-------------| | docs/ | Documentation index | | Installation | Step-by-step guide to install in any project | | Quick Start | Minimal setup to render the dashboard | | API Reference | Props, built-in tabs, simulation, exports | | Configuration & Theming | Config shape, CSS variables, branding | | HTTP API | Report pages endpoint contract and DTO mappers | | Iframe Embed | Standalone iframe build and config delivery | | Development | Local setup, testing, building, publishing |

Quick install

Published as a public package on npmjs.org — no authentication needed.

npm install @metaboliccode-dev/widget

See Installation for framework-specific notes and troubleshooting.

Quick usage

import {
  MetabolicDashboard,
  METABOLIC_DASHBOARD_STUB_API_KEY,
} from "@metaboliccode-dev/widget";
import "@metaboliccode-dev/widget/styles.css";

export function App() {
  return (
    <div className="h-screen">
      <MetabolicDashboard
        apiKey={METABOLIC_DASHBOARD_STUB_API_KEY}
        reportHttpConfig={{ apiKey: "mc-prod", userId: "prod-full-user" }}
        sideMenuUserProfile={{ displayName: "User", email: "[email protected]" }}
      />
    </div>
  );
}

The library owns the report-pages API base URL (baked in at build time). Consumers only pass auth — never a baseUrl.

See Quick Start for the dual-key pattern (why apiKey and the custom fetchers both carry credentials).

AG Charts enterprise license

Charts use AG Charts (ag-charts-community + ag-charts-enterprise). The enterprise license key is baked into the published bundle by the manually-triggered GitHub Actions release workflow (the AG_CHARTS_LICENSE_KEY repo secret is passed to the build step). Consumers do not need to do anything — installing the package gives you an unlocked build. See Development → Releasing a new version for the full publishing procedure.