@citestyle/styles 0.1.0 → 1.0.0

package/README.md

@@ -1,6 +1,8 @@
 # @citestyle/styles
 
-Pre-compiled popular CSL styles, ready to use. Each style is ~3-5KB and imports shared helpers from `@citestyle/core`.
+The 10 most popular citation styles, pre-compiled and ready to import. Each style is ~3-5KB — a compiled JavaScript module that formats citations and bibliographies as pure function calls with zero runtime overhead.
+
+These are the same styles you'd get by running the `@citestyle/compiler` on official `.csl` files, just pre-built so you can `npm install` and go.
 
 ## Installation
 
@@ -8,106 +10,123 @@ Pre-compiled popular CSL styles, ready to use. Each style is ~3-5KB and imports
 npm install @citestyle/styles
 ```
 
-## Available Styles
-
-| Import path | Style |
-|---|---|
-| `@citestyle/styles/apa` | American Psychological Association 7th edition |
-| `@citestyle/styles/mla` | Modern Language Association 9th edition |
-| `@citestyle/styles/chicago-author-date` | Chicago Manual of Style 17th edition (author-date) |
-| `@citestyle/styles/ieee` | IEEE |
-| `@citestyle/styles/vancouver` | Vancouver |
-| `@citestyle/styles/harvard` | Harvard (Cite Them Right) |
-| `@citestyle/styles/ama` | American Medical Association 11th edition |
-| `@citestyle/styles/turabian` | Turabian 9th edition |
-| `@citestyle/styles/nature` | Nature |
-| `@citestyle/styles/science` | Science |
+Requires `@citestyle/core` as a peer dependency (installed automatically).
+
+## Available styles
+
+| Import | Style | Class |
+|---|---|---|
+| `@citestyle/styles/apa` | American Psychological Association 7th ed. | Author-date |
+| `@citestyle/styles/mla` | Modern Language Association 9th ed. | Author-date |
+| `@citestyle/styles/chicago-author-date` | Chicago Manual of Style 17th ed. | Author-date |
+| `@citestyle/styles/harvard` | Harvard — Cite Them Right 12th ed. | Author-date |
+| `@citestyle/styles/ieee` | IEEE | Numeric |
+| `@citestyle/styles/vancouver` | Vancouver | Numeric |
+| `@citestyle/styles/ama` | American Medical Association 11th ed. | Numeric |
+| `@citestyle/styles/nature` | Nature | Numeric |
+| `@citestyle/styles/science` | Science | Numeric |
+
+**Need a different style?** Any of the 10,000+ `.csl` files from the [official CSL repository](https://github.com/citation-style-language/styles) can be compiled with [`@citestyle/compiler`](../compiler):
+
+```bash
+npx citestyle compile my-journal.csl -o my-journal.js
+```
 
 ## Usage
 
-### Direct (without registry)
+### Simplest: one-off formatting
 
-```js
+```javascript
+import { format, formatCitation } from '@citestyle/registry'
 import * as apa from '@citestyle/styles/apa'
 
 const item = {
   id: '1',
   type: 'article-journal',
-  title: 'A theory of everything',
-  author: [{ family: 'Einstein', given: 'Albert' }],
-  issued: { 'date-parts': [[2024]] },
-  'container-title': 'Physical Review Letters',
-  volume: '130',
-  page: '1-10',
-  DOI: '10.1103/example',
+  title: 'Deep learning for protein structure prediction',
+  author: [{ family: 'Jumper', given: 'John' }],
+  issued: { 'date-parts': [[2021]] },
+  'container-title': 'Nature',
+  volume: '596',
+  page: '583-589',
+  DOI: '10.1038/s41586-021-03819-2',
 }
 
-const entry = apa.bibliography(item)
-console.log(entry.text)
-console.log(entry.html)
+// Bibliography entry
+const entry = format(apa, item)
+entry.text   // Jumper, J. (2021). Deep learning for protein structure prediction. Nature, 596, 583–589.
+entry.html   // Semantic HTML with CSS classes (.csl-author, .csl-title, ...) and linked DOI
+entry.parts  // { authors, year, title, container, volume, page, doi }
+entry.links  // { doi: 'https://doi.org/10.1038/s41586-021-03819-2' }
+
+// Inline citation
+const cite = formatCitation(apa, [{ item }])
+cite.text    // (Jumper, 2021)
 ```
 
-### With registry (recommended for documents)
+### With a registry (for documents)
 
-```js
-import * as ieee from '@citestyle/styles/ieee'
+When your document has multiple citations that need to interact — numbering, disambiguation, sorting — use a registry:
+
+```javascript
 import { createRegistry } from '@citestyle/registry'
+import * as ieee from '@citestyle/styles/ieee'
 
 const registry = createRegistry(ieee)
 registry.addItems([item1, item2, item3])
 
-const citation = registry.cite([{ id: '1' }])
-console.log(citation.text) // [1]
+// Citations are auto-numbered
+registry.cite([{ id: 'jumper2021' }])
+// → { text: '[1]', html: '...' }
 
+// Bibliography is sorted per IEEE rules
 const bibliography = registry.getBibliography()
-bibliography.forEach(e => console.log(e.html))
+bibliography.forEach(entry => {
+  console.log(entry.html)  // [1] J. Jumper, "Deep learning for..."
+})
 ```
 
-### Style metadata
+### Direct function calls (no registry, no helpers)
 
-Every style exports a `meta` object:
+Every style module exports `bibliography()` and `citation()` as pure functions:
 
-```js
+```javascript
 import * as apa from '@citestyle/styles/apa'
 
-console.log(apa.meta.id)    // "apa"
-console.log(apa.meta.title) // "American Psychological Association 7th edition"
-console.log(apa.meta.class) // "in-text"
+const entry = apa.bibliography(item)  // → { text, html, parts, links }
+const cite = apa.citation([{ item }]) // → { text, html }
 ```
 
-## Custom Styles
-
-For styles not included here, compile any CSL file with `@citestyle/compiler`:
+### Style metadata
 
-```bash
-npm install @citestyle/compiler
-citestyle compile my-style.csl -o my-style.js
-```
+Every style exports a `meta` object with information from the CSL source:
 
-Then import the output module the same way:
+```javascript
+import * as apa from '@citestyle/styles/apa'
 
-```js
-import * as myStyle from './my-style.js'
+apa.meta.id     // "apa"
+apa.meta.title  // "American Psychological Association 7th edition"
+apa.meta.class  // "in-text"
 ```
 
-## Output Format
+## Output format
 
-Every `bibliography(item)` call returns:
+**Bibliography entries** return four representations:
 
-```js
+```javascript
 {
-  text: '...',   // Plain text
-  html: '...',   // Semantic HTML with CSS classes and linked DOIs
-  parts: {...},  // Decomposed fields for custom layouts
-  links: {...},  // Extracted DOI, URL, PDF links
+  text: '...',    // Plain text — for copy-paste, accessibility, search indexing
+  html: '...',    // Semantic HTML — CSS classes per field, auto-linked DOIs
+  parts: { ... }, // Decomposed fields — for building cards, profiles, custom layouts
+  links: { ... }, // Extracted links — DOI, URL, ready for buttons/badges
 }
 ```
 
-Every `citation(cites)` call returns:
+**Citations** return two:
 
-```js
+```javascript
 {
-  text: '...',   // Plain text (e.g., "(Smith, 2024)")
-  html: '...',   // HTML with <span class="csl-citation">
+  text: '...',    // Plain text — "(Smith, 2024)" or "[1]"
+  html: '...',    // HTML — <span class="csl-citation">...</span>
 }
 ```

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@citestyle/styles",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Pre-compiled popular CSL styles (~3-5KB each)",
+  "author": "Uniweb",
+  "homepage": "https://github.com/uniweb/csl/tree/main/packages/styles",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uniweb/csl.git",
+    "directory": "packages/styles"
+  },
+  "keywords": [
+    "csl",
+    "citation",
+    "styles",
+    "apa",
+    "mla",
+    "chicago",
+    "ieee",
+    "vancouver",
+    "bibliography"
+  ],
   "type": "module",
   "exports": {
     "./apa": "./apa.js",
@@ -22,12 +40,20 @@
     }
   },
   "files": [
-    "*.js",
+    "apa.js",
+    "mla.js",
+    "chicago-author-date.js",
+    "ieee.js",
+    "vancouver.js",
+    "harvard.js",
+    "ama.js",
+    "nature.js",
+    "science.js",
     "types.d.ts",
     "README.md"
   ],
   "dependencies": {
-    "@citestyle/core": "^0.0.2"
+    "@citestyle/core": "1.0.0"
   },
   "license": "MIT",
   "scripts": {

package/types.d.ts

@@ -1,4 +1,8 @@
 import type { CompiledStyle } from '@citestyle/types'
 
 declare const style: CompiledStyle
-export = style
+export default style
+export declare const meta: CompiledStyle['meta']
+export declare function bibliography(item: import('@citestyle/types').CslItem, ctx?: import('@citestyle/types').FormatContext): import('@citestyle/types').FormattedEntry
+export declare function citation(cites: import('@citestyle/types').CiteRef[], ctx?: import('@citestyle/types').FormatContext): import('@citestyle/types').FormattedCitation
+export declare function bibliographySort(a: import('@citestyle/types').CslItem, b: import('@citestyle/types').CslItem): number

package/build.js

@@ -1,97 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Build script for @citestyle/styles
- *
- * Compiles CSL XML source files into JavaScript modules using the
- * @citestyle/compiler. The CSL sources live in test/fixtures/ at the
- * monorepo root — these are the canonical CSL style definitions.
- *
- * Each compiled style is a self-contained ES module (~3-50KB) that
- * exports { meta, bibliography, citation, bibliographySort }.
- *
- * Usage:
- *   node build.js           # Compile all styles listed in STYLES
- *   node build.js --clean   # Remove compiled files first
- */
-
-import { execSync } from 'node:child_process'
-import { existsSync, unlinkSync, readdirSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-const ROOT = join(__dirname, '../..')
-const FIXTURES = join(ROOT, 'test/fixtures')
-const CLI = join(ROOT, 'packages/compiler/src/cli.js')
-
-/**
- * Styles to compile.
- *
- * Each entry maps a CSL filename (in test/fixtures/) to its output name.
- * The output name must match the exports map in package.json.
- *
- * To add a new style:
- * 1. Add the .csl file to test/fixtures/
- * 2. Add an entry here
- * 3. Add the export to package.json: "./name": "./name.js"
- */
-const STYLES = [
-  // Core academic styles
-  'apa',
-  'mla',
-  'chicago-author-date',
-  'ieee',
-  'vancouver',
-  'harvard',
-
-  // Additional popular styles
-  'ama',
-  'nature',
-  'science',
-]
-
-// Parse args
-const args = process.argv.slice(2)
-const clean = args.includes('--clean')
-
-if (clean) {
-  console.log('Cleaning compiled styles...')
-  for (const file of readdirSync(__dirname)) {
-    if (file.endsWith('.js') && file !== 'build.js') {
-      unlinkSync(join(__dirname, file))
-      console.log(`  Removed ${file}`)
-    }
-  }
-}
-
-console.log(`Compiling ${STYLES.length} styles...\n`)
-
-let failed = 0
-
-for (const style of STYLES) {
-  const input = join(FIXTURES, `${style}.csl`)
-  const output = join(__dirname, `${style}.js`)
-
-  if (!existsSync(input)) {
-    console.error(`✗ ${style}: source not found at ${input}`)
-    failed++
-    continue
-  }
-
-  try {
-    execSync(`node ${CLI} compile ${input} -o ${output}`, {
-      cwd: ROOT,
-      stdio: 'inherit',
-    })
-  } catch {
-    console.error(`✗ ${style}: compilation failed`)
-    failed++
-  }
-}
-
-console.log(`\nDone. ${STYLES.length - failed}/${STYLES.length} styles compiled.`)
-
-if (failed > 0) {
-  process.exit(1)
-}