# Campos

> Campos is a React-first TypeScript library for football visualisation: charts, pitch primitives, provider adapters, canonical schema types, and a server-side static export, published on npm as `@withqwerty/campos-*`. It is currently in alpha (`0.1.0-alpha.x`) with stable JSDoc, exported types, and zero-config defaults that aim to look publishable without prop tuning.

## Overview

- [llms-full.txt](https://campos.withqwerty.com/llms-full.txt): inline single-fetch briefing with the same material expanded (coordinates, styling model, adapter shapes, zero-config philosophy)
- [About](https://campos.withqwerty.com/about): why Campos exists and what shaped it
- [Getting Started](https://campos.withqwerty.com/getting-started): install, zero-config chart, typed adapter flow
- [Showcase — Can Campos build this?](https://campos.withqwerty.com/showcase): battle-test recreations of published football visualisations
- [Components index](https://campos.withqwerty.com/): every component with a dedicated page
- [Decisions log](https://campos.withqwerty.com/decisions): architecture decision records (public excerpt)
- [Adapters](https://campos.withqwerty.com/adapters): provider coverage and canonical output shape

## Install

Five packages ship on npm. Install the React runtime plus the adapter(s) you need:

- [@withqwerty/campos-react](https://www.npmjs.com/package/@withqwerty/campos-react): primary consumer entry point — chart components + internal compute layer
- [@withqwerty/campos-adapters](https://www.npmjs.com/package/@withqwerty/campos-adapters): provider normalisation (`fromOpta.*`, `fromStatsBomb.*`, etc.)
- [@withqwerty/campos-schema](https://www.npmjs.com/package/@withqwerty/campos-schema): canonical football types, JSON schemas, `getCountryCode()` helper (FIFA codes, not ISO)
- [@withqwerty/campos-stadia](https://www.npmjs.com/package/@withqwerty/campos-stadia): pitch and goal surface primitives
- [@withqwerty/campos-static](https://www.npmjs.com/package/@withqwerty/campos-static): Node-side SVG/PNG export

The old `@withqwerty/campos-core` package is retired. Compute and model helpers live inside `@withqwerty/campos-react` during alpha.

## Core conventions

- [Coordinate system](https://campos.withqwerty.com/stadia/): attacker-perspective `x: 0..100` (own goal → opposition goal), `y: 0..100` (attacker's right → attacker's left), origin at bottom-left. Adapters produce this frame; renderers own orientation via `attackingDirection`.
- [FIFA country codes](https://campos.withqwerty.com/adapters/): flags and country identifiers use FIFA three-letter codes (ENG/SCO/WAL/NIR are distinct football nations). Use `getCountryCode()` to resolve provider country names.
- [Styling model](https://campos.withqwerty.com/components/): every chart family uses a callback-first styling surface (`markers`, `lines`, `areas`, `guides`, `labels`, `text`, `badges`). Do not hand-pass SVG style strings through — use the typed `StyleValue<T, Context>` channels.

## Pitch charts

- [ShotMap](https://campos.withqwerty.com/shotmap/): shot maps with xG scaling and pitch overlays
- [PassMap](https://campos.withqwerty.com/passmap/): completed/incomplete passes with directional cues
- [PassNetwork](https://campos.withqwerty.com/passnetwork/): average-position pass networks with directed/weighted edges
- [PassFlow](https://campos.withqwerty.com/passflow/): zonal pass-flow arrows between grid zones
- [PassSonar](https://campos.withqwerty.com/passsonar/): polar pass-direction surfaces
- [Heatmap](https://campos.withqwerty.com/heatmap/): pitch-binned event density
- [Territory](https://campos.withqwerty.com/territory/): zone-aggregated pitch surfaces
- [KDE](https://campos.withqwerty.com/kde/): kernel density pitch surfaces
- [Formation](https://campos.withqwerty.com/formation/): lineup and formation cards
- [GoalMouthShotChart](https://campos.withqwerty.com/goalmouthshotchart/): goal-mouth shot placement

## Cartesian and polar charts

- [ScatterPlot](https://campos.withqwerty.com/scatterplot/): scouting scatter with regions, labels, and quadrant guides
- [Beeswarm](https://campos.withqwerty.com/beeswarm/): metric beeswarm distributions
- [DistributionComparison](https://campos.withqwerty.com/distributioncomparison/): paired distribution curves
- [RadarChart](https://campos.withqwerty.com/radarchart/): classic scouting radars
- [PizzaChart](https://campos.withqwerty.com/pizzachart/): percentile pizza charts
- [BumpChart](https://campos.withqwerty.com/bumpchart/): rank-over-time league table histories
- [XGTimeline](https://campos.withqwerty.com/xgtimeline/): match xG cumulative timeline
- [CometChart](https://campos.withqwerty.com/cometchart/): change-over-time comet traces
- [MarginalDensity](https://campos.withqwerty.com/marginaldensity/): marginal density primitive for scatter axes

## Scouting and stat primitives

- [PercentileBar + PercentilePill](https://campos.withqwerty.com/percentile-surfaces/): percentile displays for scouting rows and cards
- [StatBadge](https://campos.withqwerty.com/statbadge/): compact stat badge primitive
- [SmallMultiples](https://campos.withqwerty.com/smallmultiples/): shared grid layout for neighbouring charts
- [Stadia](https://campos.withqwerty.com/stadia/): standalone pitch and goal primitives

## Adapters

Shape: `from<Provider>.<product>(rawInput, options)`. Every product returns canonical Campos entities — never provider-shaped objects.

- [Opta](https://campos.withqwerty.com/adapters/#opta): F24 and Match Events feeds — shots, passes, events, formations, lineups
- [StatsBomb](https://campos.withqwerty.com/adapters/#statsbomb): open-data events — shots, passes, pressures
- [WhoScored](https://campos.withqwerty.com/adapters/#whoscored): matchCentre feed — formations, events, shots
- [Understat](https://campos.withqwerty.com/adapters/#understat): match shot seams
- [FBref](https://campos.withqwerty.com/adapters/#fbref): summary tables and narrower surfaces
- [Sofascore](https://campos.withqwerty.com/adapters/#sofascore): public match surfaces

## Source and release

- [GitHub — public package repo](https://github.com/withqwerty/campos): OSS source, npm release origin
- [Issues and bug reports](https://github.com/withqwerty/campos/issues)
- [npm package registry](https://www.npmjs.com/package/@withqwerty/campos-react): version history, changelog
- [Release notes](https://github.com/withqwerty/campos/blob/main/CHANGELOG.md)
- [Contributing](https://github.com/withqwerty/campos/blob/main/CONTRIBUTING.md)
- [Security policy](https://github.com/withqwerty/campos/blob/main/SECURITY.md)