feat(csl): Citation Style Language support (IEEE, Vancouver, AMA, ACS, Nature, APSA, Chicago author-date)

[aicoder2009]

Summary

Adds Citation Style Language (CSL) support so OpenCitation goes beyond its four built-in styles into real journal/discipline styles — the headline feature for the researcher/professional audience. Starter set: IEEE, Vancouver, AMA, ACS, Nature, APSA, Chicago (author-date).

Sample output (validated in tests):

IEEE:    [1] K. He, X. Zhang, … "Deep residual learning…," pp. 770–778, 2016, doi:…
ACS:     (1) He, K.; Zhang, X.; … 2016, 770–778.        (bold year)
Chicago: He, Kaiming, … 2016. "Deep Residual Learning…."   in-text: (He et al. 2016)

Architecture

• src/lib/citation/csl/to-csl-json.ts — maps all 28 source types to CSL-JSON (pure, tested).
• csl/engine.ts — citeproc wrapper producing text + clean inline HTML + in-text markers ([1] / author-date).
• csl/styles.ts — lazy style registry. The engine and each style are code-split via import(), so citeproc lands in a ~402 KB chunk that loads only when a CSL style is used — never in the main/cite bundle.
• index.ts — formatCitationAny / generateInTextCitationAny route built-ins to the sync formatters and CSL ids to the engine.
• Bundled styles + en-US locale are generated reproducibly by scripts/fetch-csl-styles.mjs from the CSL project (CC BY-SA 3.0).

Wired into

• Generator (/cite): new "Journal & discipline styles" group; generation, in-text copy, and BibTeX/bulk/lookup paths format via the async CSL-aware path with error handling.
• List view: "reformat all to…" and per-citation re-style.
• Add-citation modal: CSL options + async live preview.

Citation.style broadened to string so CSL ids round-trip; saved citations store formatted text/html, so lists and shares render CSL output without loading the engine.

Verification

• ✅ typecheck clean
• ✅ 668 tests (16 new, including real citeproc output for numbered and author-date styles)
• ✅ lint 0 errors
• ✅ build passes; citeproc confirmed code-split into a lazy chunk

Known follow-ups (not in this PR)

• In-list in-text copy falls back to author-year for CSL styles (the generator's in-text is correct).
• Only the en-US locale is bundled.
• A searchable picker over the full ~10k-style CSL repo and offline-caching the engine chunk are natural next steps.

https://claude.ai/code/session_019tCTyU5MpR5qdcnjV8UHfu

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added support for multiple discipline-specific and journal citation styles including IEEE, Vancouver, AMA, ACS, Nature, APSA, and Chicago author-date formatting.

• Documentation

  • Updated documentation to reflect current test suite of 668 tests.
  • Expanded citation style guidance with journal and discipline style options.

• Dependencies

  • Added citeproc library for enhanced citation formatting capabilities.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
opencitation	Ready	Preview, Comment	Jun 9, 2026 1:08am

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6e2c51b7-0275-4342-bf2e-d4e1a9f2a993

📥 Commits

Reviewing files that changed from the base of the PR and between 26467f9 and 3fa8cf8.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (23)

• CLAUDE.md
• README.md
• package.json
• scripts/fetch-csl-styles.mjs
• src/app/cite/page.tsx
• src/app/lists/[id]/page.tsx
• src/components/wiki/citation-add-modal.tsx
• src/lib/citation/csl/engine.test.ts
• src/lib/citation/csl/engine.ts
• src/lib/citation/csl/styles.ts
• src/lib/citation/csl/styles/acs.ts
• src/lib/citation/csl/styles/ama.ts
• src/lib/citation/csl/styles/apsa.ts
• src/lib/citation/csl/styles/chicago-author-date.ts
• src/lib/citation/csl/styles/ieee.ts
• src/lib/citation/csl/styles/locale-en-us.ts
• src/lib/citation/csl/styles/nature.ts
• src/lib/citation/csl/styles/vancouver.ts
• src/lib/citation/csl/to-csl-json.test.ts
• src/lib/citation/csl/to-csl-json.ts
• src/lib/citation/index.ts
• src/types/citation.ts
• src/types/citeproc.d.ts

---

📝 Walkthrough

Walkthrough

This PR adds Citation Style Language (CSL) formatting support to the citation system. It integrates citeproc-js, implements a conversion layer from internal CitationFields to CSL JSON, bundles multiple CSL discipline styles, and refactors the UI to support async formatting across both built-in and CSL styles.

Changes

CSL Citation Formatting Support

Layer / File(s)	Summary
Type definitions and citeproc dependency src/types/citeproc.d.ts, package.json	Declares TypeScript interfaces for the citeproc-js library (CiteprocSys, CiteprocEngine, CiteprocStatic) and adds the citeproc npm dependency at version ^2.4.63.
CSL JSON conversion from CitationFields src/lib/citation/csl/to-csl-json.ts, src/lib/citation/csl/to-csl-json.test.ts	Implements the bridge from OpenCitation CitationFields to CSL JSON, including TypeScript interfaces (CslName, CslDate, CslJson), conversion helpers for authors and dates, source-type-to-CSL-type mapping, and comprehensive tests covering books, journals, chapters, films, seasons, preprints, and websites.
CSL formatting engine src/lib/citation/csl/engine.ts, src/lib/citation/csl/engine.test.ts	Implements formatCsl and inTextCsl async functions using citeproc-js to render bibliographies and in-text citations, with helpers to normalize HTML (removing block <div> wrappers) and plain text output; includes tests for IEEE numbered, Chicago author-date, and error handling.
CSL style registry and fetch script scripts/fetch-csl-styles.mjs, src/lib/citation/csl/styles.ts, src/lib/citation/csl/styles/*.ts	Provides a CslStyleDef interface and CSL_STYLES registry for dynamic style loading, exports isCslStyle and cslStyleLabel helpers, implements a fetch script to download CSL XML files from upstream repositories, and includes auto-generated style modules for IEEE, Vancouver, AMA, ACS, Nature, APSA, Chicago author-date, and en-US locale.
Async citation API routing src/lib/citation/index.ts, src/types/citation.ts	Adds formatCitationAny and generateInTextCitationAny async entry points that route between built-in CitationStyle formatters and CSL formatters based on style ID, re-exports CSL registry helpers, and broadens the Citation.style field from CitationStyle union to plain string.
Cite page refactor src/app/cite/page.tsx	Converts all citation formatting to use async formatCitationAny and generateInTextCitationAny, changes selectedStyle state to string, adds try/catch error handling in quick-add, BibTeX import, manual generation, bulk result rendering, and research lookup paths, converts copyInTextCitation to async, broadens STYLE_LABELS and style selector to include CSL_STYLES, and adds a new UI section rendering CSL discipline styles.
Modal and list page updates src/components/wiki/citation-add-modal.tsx, src/app/lists/[id]/page.tsx	Updates CitationAddModal and list detail page to use formatCitationAny, converts selectedStyle and reformatTarget state to plain string, expands style selectors to include both CITATION_STYLES and CSL_STYLES, adds async effect for reformatting when style changes, and integrates async formatting into citation editing and bulk reformatting flows.
Documentation updates CLAUDE.md, README.md	Updates test counts from 652 to 668 across both files and expands README documentation to mention journal and discipline citation styles (IEEE, Vancouver, AMA, ACS, Nature, APSA, Chicago author-date) powered by Citation Style Language.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

A rabbit hops through styles so fine,
Where citeproc and CSL align,
IEEE, Chicago, Nature's call,
Async formatting conquers all,
With discipline and poise we write it,
Citations formatted—let's cite it! 🐰📚

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/happy-dijkstra-o04h9l

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

scripts/fetch-csl-styles.mjs

Oops! Something went wrong! :(

ESLint: 9.39.2

A configuration object specifies rule "@typescript-eslint/no-unused-vars", but could not find plugin "@typescript-eslint".

Common causes of this problem include:

1. The "@typescript-eslint" plugin is not defined in your configuration file.
2. The "@typescript-eslint" plugin is not defined within the same configuration object in which the "@typescript-eslint/no-unused-vars" rule is applied.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}