# LUNA Charts

LUNA Charts is a reusable, developer-friendly charting library designed to make accessible, WCAG-oriented data visualization the default rather than an afterthought.

> **Project status:** Groundwork phase. Core architecture and tooling are in place; production-ready chart components (starting with `BarChart`) are still in development. See the [Roadmap](./docs/src/content/docs/getting-started/roadmap.mdx) for details.

## Why LUNA Charts

Most charting libraries treat accessibility as an add-on. LUNA Charts builds it in from the start:

- **Accessible by default** — components are designed and tested against WCAG guidance from day one, not patched in afterward
- **Framework-agnostic** — built as standard Web Components (Stencil), usable in React, Vue, Angular, Svelte, or plain HTML
- **SVG-based rendering** — inspectable, stylable, and screen-reader-friendly output instead of an opaque canvas

## Tech Stack

| Area | Technology |
|---|---|
| Component framework | [Stencil](https://stenciljs.com) (compiles to standard Web Components) |
| Language | TypeScript |
| Package manager | pnpm (monorepo workspaces) |
| Unit & component testing | [Vitest](https://vitest.dev), with [Playwright](https://playwright.dev) as the browser provider |
| Accessibility testing | axe-core |
| Documentation | [Starlight](https://starlight.astro.build) |
| Component explorer | Storybook |
| Linting & formatting | ESLint, Prettier |
| Release management | [Changesets](https://github.com/changesets/changesets) |

The full set of architecture decisions behind these choices is documented in [`docs/.../architecture/adr`](./docs/src/content/docs/architecture/adr) and the broader [Architecture Development Method (ADM) documentation](./docs/src/content/docs/architecture/adm).

## Project Structure

```text
luna-charts/
│
├── packages/
│   └── luna-charts/        # The library itself (Stencil components, Storybook)
│
├── docs/                    # Architecture docs, ADRs, guides (Starlight)
│
├── examples/                # Usage examples (framework integrations)
│
├── .changeset/               # Release/versioning configuration
│
└── .github/                  # Community health files (Code of Conduct, etc.)
```

## Getting Started

### Prerequisites

- Node.js `>= 22.0.0`
- pnpm `11.11.0` (see `devEngines` in `package.json`; pnpm will be downloaded automatically via Corepack if missing)
- Docker (required for running component/browser tests locally, see below)

### Installation

```bash
git clone <this-repository>
cd luna-charts
pnpm install
```

### Common commands

| Command | Description |
|---|---|
| `pnpm lint` | Run ESLint across the repository |
| `pnpm format` | Format all files with Prettier |
| `pnpm test:unit` | Run unit tests for the `luna-charts` package |
| `pnpm test:component` | Run component/browser tests inside the containerized Playwright environment |
| `pnpm test` | Run the full test suite (unit + component) |
| `pnpm changeset` | Record a changeset for your change (required for any user-facing change) |

Component and browser tests run inside Docker (`docker-compose.test.yaml`) to guarantee a reproducible browser environment across all contributors and CI — you don't need Playwright browsers installed locally.

## Documentation

- **Architecture documentation**: see `docs/` — includes the full Architecture Development Method (ADM) documentation (vision, business architecture, technology architecture, governance, migration planning) and all Architecture Decision Records (ADRs)
- **Contributing**: see [CONTRIBUTING.md](./CONTRIBUTING.md)
- **Code of Conduct**: see [.github/CODE_OF_CONDUCT.md](./.github/CODE_OF_CONDUCT.md)

## License

LUNA Charts is licensed under the [GNU Lesser General Public License v3.0 (LGPL-3.0)](./LICENSE).