pdf-factory

Generate and parse tournament PDFs from TODS (Tennis Open Data Standards) data. Draw sheets, schedules, player lists, court cards, sign-in sheets, and match cards — with Grand Slam and tour-level presets.

Part of the CourtHive ecosystem.

Storybook

Live examples and interactive documentation: https://courthive.github.io/pdf-factory/

Install

pnpm add pdf-factory
# or
npm install pdf-factory

Quick start

Generate a draw sheet

import { tournamentEngine } from 'tods-competition-factory';
import { generateDrawPDF } from 'pdf-factory';

// Load a TODS tournament record
tournamentEngine.setState(tournamentRecord);
const { drawIds } = tournamentEngine.getEvent({ eventId });

// Generate a PDF — returns a jsPDF doc
const doc = generateDrawPDF({
  tournamentRecord,
  drawId: drawIds[0],
  preset: 'wimbledon', // or 'usOpen', 'rolandGarros', 'australianOpen', 'itfJunior', ...
});

// Output as bytes
const pdfBytes = doc.output('arraybuffer');

Generate a schedule (Order of Play)

import { generateSchedulePDF, extractScheduleData } from 'pdf-factory';

const scheduleData = extractScheduleData({ tournamentRecord });
const doc = generateSchedulePDF({ scheduleData, tournamentRecord });

Generate a player list

import { generatePlayerListPDF, extractParticipantData } from 'pdf-factory';

const participants = extractParticipantData({ tournamentRecord, eventId });
const doc = generatePlayerListPDF({ participants, tournamentRecord });

Generate court cards

import { generateCourtCardPDF, extractCourtCardData } from 'pdf-factory';

const courtCards = extractCourtCardData({ tournamentRecord, eventId });
const doc = generateCourtCardPDF({ courtCards, tournamentRecord });

Parse an existing PDF back to TODS

The parser entry point is separate (Node-only, depends on pdf2json):

import { parsePdfBuffer, extractDrawFromPage } from 'pdf-factory/parser';

const parsed = await parsePdfBuffer(pdfBuffer);
const draw = extractDrawFromPage(parsed.pages[0]);
// draw.participants, draw.scores, draw.seeds, ...

Presets

Format presets control name display, score formatting, seed placement, round labels, and page layout. Built-in presets mirror real-world tournament PDFs:

| Preset | Style | Round labels | | ---------------- | --------------------- | --------------------- | | wimbledon | LAST, First (GBR) [1] | First Round ... Final | | usOpen | LAST, First (USA) [1] | Round 1 ... Final | | rolandGarros | LAST First (FRA) [1] | 1er TOUR ... FINALE | | australianOpen | LAST, First (AUS) [1] | First Round ... Final | | itfJunior | LAST, First (NAT) [1] | Round of 64 ... Final | | wtaTour | LAST, First (NAT) [1] | First Round ... Final |

Presets are composable — start from a built-in and override individual fields:

import { getPreset, mergePreset } from 'pdf-factory';

const custom = mergePreset('wimbledon', {
  nameFormat: 'First LAST',
  showEntryStatus: true,
});

Composition catalog

Higher-level composition presets bundle header layout, footer layout, draw format, and page config into named units. Categories: Grand Slam, Tour, ITF, National, Collegiate, Club.

import { getCatalogPreset, listCatalogPresets } from 'pdf-factory';

const presets = listCatalogPresets(); // all available compositions
const wimbledon = getCatalogPreset('wimbledon');

See the Header & Footer Catalog for the three-tier footer system derived from real-world tournament PDFs.

Document types

| Generator | Description | | ------------------------------ | ---------------------------------------------------------- | | generateDrawPDF | Auto-selects renderer based on draw type | | generateTraditionalDrawPDF | Single elimination bracket | | generateSplitDrawPDF | Large draws split across pages (halves/quarters + summary) | | generateFeedInDrawPDF | Feed-in consolation structures | | generateConsolationDrawPDF | Consolation bracket | | generateCompassDrawPDF | Compass (8-direction) draws | | generateDoubleEliminationPDF | Winners + losers bracket | | generateLuckyDrawPDF | Lucky loser draw | | generateMirroredDrawPDF | Mirrored (left-right) bracket | | generateBackdrawPDF | Backdraw structures | | generateSchedulePDF | Order of Play (court grid) | | generateScheduleV2PDF | Sequential schedule layout | | generateSequentialOOP | Sequential Order of Play | | generatePlayerListPDF | Participant list with seeds and rankings | | generateCourtCardPDF | Per-court assignment cards | | generateSignInSheetPDF | Player sign-in sheet | | generateMatchCardPDF | Individual match scoring card |

Architecture

TODS tournament record
  → extractors (extractDrawData, extractScheduleData, ...)
    → composition (page config + preset + header/footer)
      → renderers (traditionalDraw, roundRobin, compass, ...)
        → jsPDF document (Uint8Array or blob)

Parser pipeline (reverse direction):

PDF file
  → pdf2json extraction
    → pdfRuler (spatial analysis, column/row detection)
      → TODS structure mapping

Source layout

src/
  config/        Presets (Grand Slam formats, page sizes, composition catalog)
  core/          Data extractors (TODS → renderer-ready data)
  composition/   Page composition, header/footer layouts, print dispatcher
  generators/    High-level PDF generators (one per document type)
  renderers/     Draw-type-specific renderers (bracket, round robin, compass, ...)
  layout/        Page layout engine, header/footer primitives, fonts, tables
  parser/        PDF-to-TODS extraction (Node-only, separate entry point)
  comparison/    Visual regression utilities (pixel-level PDF comparison)
  utils/         Shared formatting primitives
  stories/       Storybook stories for visual development

Development

pnpm install
pnpm storybook       # interactive dev on :6007
pnpm test            # vitest (watch mode)
pnpm test:run        # single run
pnpm test:coverage   # coverage report
pnpm lint            # eslint with fix
pnpm check-types     # tsc --noEmit
pnpm build           # vite library build → dist/

Testing

Tests are split into two categories:

• Generator tests (always run) — generate PDFs from mocksEngine tournament data and verify output. No external fixtures needed.
• Parser/fidelity tests (local only) — parse third-party tournament PDFs in fixtures/. These are gitignored and skipped automatically in CI via describe.skipIf(!hasFixtures).

To run parser tests locally, populate fixtures/reference/ with PDF files (see fixtures/reference/download-draws.sh).

Dependencies

• jsPDF + jspdf-autotable — PDF generation
• tods-competition-factory — tournament data structures and engine
• pdf2json — PDF parsing (parser entry point only)

License

MIT