npm package: @metaboliccode-dev/widget
Description: 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 A
Latest version: 0.2.4

# `@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

```bash
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 (`vitest.config.ts`) |
| `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/__tests__/` | Vitest tests; JSON fixtures under `src/__tests__/fixtures/pages/` |
| `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/](./docs/README.md)** | Documentation index |
| [Installation](./docs/installation.md) | Step-by-step guide to install in any project |
| [Quick Start](./docs/quick-start.md) | Minimal setup to render the dashboard |
| [API Reference](./docs/api-reference.md) | Props, built-in tabs, simulation, exports |
| [Configuration & Theming](./docs/configuration.md) | Config shape, CSS variables, branding |
| [HTTP API](./docs/http-api.md) | Report pages endpoint contract and DTO mappers |
| [Iframe Embed](./docs/iframe-embed.md) | Standalone iframe build and config delivery |
| [Development](./docs/development.md) | Local setup, testing, building, publishing |

## Quick install

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

```bash
npm install @metaboliccode-dev/widget
```

See [Installation](./docs/installation.md) for framework-specific notes and troubleshooting.

## Quick usage

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

const fetchers = createHttpDashboardContentFetchers(
  mergeReportPagesApiWithBuiltIn({
    apiKey: "mc-prod",
    userId: "prod-full-user",
  }),
);

export function App() {
  return (
    <div className="h-screen">
      <MetabolicDashboard
        apiKey={METABOLIC_DASHBOARD_STUB_API_KEY}
        dashboardContentFetchers={fetchers}
        sideMenuUserProfile={{ displayName: "User", email: "user@example.com" }}
      />
    </div>
  );
}
```

See [Quick Start](./docs/quick-start.md) 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](./docs/development.md#releasing-a-new-version) for the full publishing procedure.