@citestyle/registry 0.0.2 → 1.0.0

package/README.md

@@ -1,6 +1,8 @@
 # @citestyle/registry
 
-Citation registry that manages cross-citation state for a compiled CSL style. Handles citation numbering, bibliography sorting, year-suffix disambiguation, name disambiguation, cite collapsing, and subsequent-author-substitute.
+Citation registry for managing cross-reference state across a document. When you have multiple citations and need them to interact — numbered references, year-suffix disambiguation (Smith 2024a, 2024b), cite collapsing ([1-3, 5]), sorted bibliographies — the registry handles it.
+
+For one-off formatting where citations don't interact, this package also exports a simpler `format()` API that needs no setup.
 
 ## Installation
 
@@ -8,16 +10,14 @@ Citation registry that manages cross-citation state for a compiled CSL style. Ha
 npm install @citestyle/registry
 ```
 
-## Usage
+## Quick start
 
-```js
+```javascript
 import { createRegistry } from '@citestyle/registry'
 import * as apa from '@citestyle/styles/apa'
 
-// Create a registry bound to a compiled style
 const registry = createRegistry(apa)
 
-// Add items (assigns citation numbers, triggers disambiguation)
 registry.addItems([
   {
     id: 'smith2024',
@@ -40,84 +40,129 @@ registry.addItems([
   },
 ])
 
-// Format an inline citation
-const citation = registry.cite([{ id: 'smith2024' }])
-console.log(citation.text) // (Smith, 2024)
-console.log(citation.html) // <span class="csl-citation">(Smith, 2024)</span>
+// Inline citation
+registry.cite([{ id: 'smith2024' }])
+// → { text: '(Smith, 2024)', html: '<span class="csl-citation">...</span>' }
 
-// Citation with locator
-const withPage = registry.cite([
-  { id: 'smith2024', locator: '105', label: 'page' },
-])
-console.log(withPage.text) // (Smith, 2024, p. 105)
+// Citation with page locator
+registry.cite([{ id: 'smith2024', locator: '105', label: 'page' }])
+// → { text: '(Smith, 2024, p. 105)', html: '...' }
 
-// Multi-cite
-const multi = registry.cite([
-  { id: 'smith2024' },
-  { id: 'doe2023' },
-])
-console.log(multi.text) // (Doe, 2023; Smith, 2024)
+// Multi-cite (sorted per style rules)
+registry.cite([{ id: 'smith2024' }, { id: 'doe2023' }])
+// → { text: '(Doe, 2023; Smith, 2024)', html: '...' }
 
-// Get the full bibliography (sorted per style rules)
+// Full bibliography — sorted, numbered, disambiguated
 const entries = registry.getBibliography()
-for (const entry of entries) {
-  console.log(entry.text) // Plain text
-  console.log(entry.html) // Semantic HTML with CSS classes
-}
+entries[0].text   // Plain text
+entries[0].html   // Semantic HTML with CSS classes and linked DOIs
+entries[0].parts  // Decomposed fields for custom layouts
+entries[0].links  // Extracted DOI, URL links
+```
+
+## Simple API (no registry)
+
+When you just need to format one or a few items and don't need cross-reference features:
 
-// Check registry size
-console.log(registry.size) // 2
+```javascript
+import { format, formatAll, formatCitation } from '@citestyle/registry'
+import * as apa from '@citestyle/styles/apa'
+
+// Single bibliography entry
+const entry = format(apa, item)
+// → { html, text, parts, links }
+
+// Multiple entries (sorted per style rules, auto-numbered)
+const entries = formatAll(apa, [item1, item2, item3])
+
+// Single inline citation
+const cite = formatCitation(apa, [{ item, locator: '42', label: 'page' }])
+// → { html, text }
 ```
 
-## API
+Use `createRegistry()` instead when you need any of the cross-reference features below.
 
-### `createRegistry(style, options?)`
+## When to use the registry vs. `format()`
 
-Create a new registry for a compiled CSL style.
+| Feature | `format()` | `createRegistry()` |
+|---|---|---|
+| Format a bibliography entry | Yes | Yes |
+| Format a citation | Yes | Yes |
+| Sort bibliography | Yes | Yes |
+| Citation numbering (IEEE, Vancouver) | No | Yes |
+| Year-suffix disambiguation (2024a, 2024b) | No | Yes |
+| Name disambiguation (expand initials/names) | No | Yes |
+| Cite collapsing ([1-3] or "Smith 2020, 2021") | No | Yes |
+| Subsequent-author-substitute (em-dash) | No | Yes |
 
-- `style` -- A compiled style module (must export `bibliography` or `citation`)
-- `options.subsequentAuthorSubstitute` (string) -- Override the style's substitute string (e.g., `"---"`)
+**Rule of thumb**: use `format()` for publication lists, portfolio pages, and anywhere each entry stands alone. Use `createRegistry()` for documents — papers, articles, blog posts — where citations reference and interact with each other.
 
-Returns a `Registry` object.
+## API
+
+### `createRegistry(style, options?)`
+
+Create a new registry bound to a compiled style.
 
-### Registry Methods
+- `style` — A compiled style module (from `@citestyle/styles/*` or your own compiled `.js`)
+- `options.subsequentAuthorSubstitute` (string) — Override the style's substitute string (e.g., `"---"`)
 
-#### `addItems(items)`
+### `registry.addItems(items)`
 
-Add CSL-JSON items to the registry. Items are stored by `id` and assigned citation numbers in insertion order. Duplicate IDs update the existing item.
+Add CSL-JSON items. Items are stored by `id` and assigned citation numbers in insertion order. Adding an item with a duplicate ID updates the existing entry.
 
-#### `getItem(id)`
+### `registry.getItem(id)`
 
 Look up a single item by ID. Returns `undefined` if not found.
 
-#### `cite(cites, ctx?)`
+### `registry.cite(cites, ctx?)`
 
-Format a citation cluster. Each cite object can include:
+Format a citation cluster. Each cite can include:
 
 | Property | Type | Description |
 |---|---|---|
-| `id` | string | Item ID (resolved from registry) |
+| `id` | string | Item ID (looked up from registry) |
 | `item` | CslItem | Pre-resolved item (bypasses lookup) |
-| `locator` | string | Locator value (e.g., page number) |
-| `label` | string | Locator label (`'page'`, `'chapter'`, etc.) |
-| `prefix` | string | Text before the citation |
-| `suffix` | string | Text after the citation |
+| `locator` | string | Locator value (page number, chapter, etc.) |
+| `label` | string | Locator label: `'page'`, `'chapter'`, `'section'`, etc. |
+| `prefix` | string | Text inserted before the citation |
+| `suffix` | string | Text appended after the citation |
 
 Returns `{ text: string, html: string }`.
 
-#### `getBibliography(ctx?)`
+### `registry.getBibliography(ctx?)`
+
+Get the full formatted bibliography. Items are sorted per the style's sort rules. Returns an array of `FormattedEntry` objects:
+
+```javascript
+{
+  text: string,     // Plain text
+  html: string,     // Semantic HTML with CSS classes and auto-linked DOIs
+  parts: object,    // Decomposed fields (authors, year, title, ...)
+  links: object,    // Extracted links (doi, url)
+}
+```
+
+### `registry.size`
+
+Read-only property: number of items in the registry.
+
+### `format(style, item, ctx?)`
+
+Format a single bibliography entry without a registry. Returns `{ text, html, parts, links }`.
+
+### `formatAll(style, items, ctx?)`
 
-Get the formatted bibliography. Items are sorted per the style's sort rules. Returns an array of `FormattedEntry` objects, each with `{ text, html, parts, links }`.
+Format multiple bibliography entries. Applies the style's sort order and assigns citation numbers. Returns an array of `{ text, html, parts, links }`.
 
-#### `size`
+### `formatCitation(style, cites, ctx?)`
 
-Read-only property returning the number of items in the registry.
+Format a single citation cluster without a registry. Each cite must include an `item` property (not an `id`, since there's no registry to look it up from). Returns `{ text, html }`.
 
-## Features
+## What the registry handles automatically
 
-- **Citation numbering**: Numeric styles (IEEE, Vancouver) get auto-assigned numbers
-- **Bibliography sorting**: Uses the style's compiled sort comparator
-- **Year-suffix**: Detects author+year collisions and assigns a/b/c suffixes
-- **Name disambiguation**: `disambiguate-add-givenname` (5 rules) and `disambiguate-add-names`
-- **Cite collapsing**: Numeric ranges (`[1-3, 5]`) and author-date grouping (`Smith, 2020, 2021`)
-- **Subsequent-author-substitute**: Replaces repeated authors in bibliography (e.g., with em-dash)
+- **Citation numbering** — Numeric styles (IEEE, Vancouver) get auto-assigned `[1]`, `[2]`, etc. in insertion order
+- **Bibliography sorting** — Uses the style's compiled sort comparator (alphabetical for APA, insertion-order for IEEE, etc.)
+- **Year-suffix disambiguation** — When two items share the same author(s) and year, the registry assigns suffixes: Smith (2024a), Smith (2024b)
+- **Name disambiguation** — Expands initials or adds names to distinguish ambiguous citations, following the style's `disambiguate-add-givenname` rules (5 rule variants supported)
+- **Cite collapsing** — Numeric ranges: `[1, 2, 3, 5]` → `[1-3, 5]`. Author-date grouping: `(Smith 2020; Smith 2021)` → `(Smith 2020, 2021)`
+- **Subsequent-author-substitute** — Replaces repeated authors in the bibliography with a dash or other substitute string, per the style's rules

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "@citestyle/registry",
-  "version": "0.0.2",
-  "description": "Citation registry: year-suffixes, numbering, sorting (~5-8KB)",
+  "version": "1.0.0",
+  "description": "Citation registry: year-suffixes, numbering, sorting, disambiguation (~5-8KB)",
+  "author": "Uniweb",
+  "homepage": "https://github.com/uniweb/csl/tree/main/packages/registry",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uniweb/csl.git",
+    "directory": "packages/registry"
+  },
+  "keywords": [
+    "csl",
+    "citation",
+    "registry",
+    "bibliography",
+    "disambiguation",
+    "year-suffix"
+  ],
   "type": "module",
   "exports": {
     ".": {
@@ -15,8 +30,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@citestyle/core": "0.0.2",
-    "@citestyle/types": "0.0.2"
+    "@citestyle/core": "1.0.0",
+    "@citestyle/types": "1.0.0"
   },
   "devDependencies": {
     "vitest": "^3.1.1"
@@ -26,7 +41,6 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "vitest run --passWithNoTests",
-    "lint": "echo 'TODO: configure linter'"
+    "test": "vitest run --passWithNoTests"
   }
 }

package/src/format.js

@@ -0,0 +1,70 @@
+/**
+ * Simple formatting API — format items without a full registry.
+ *
+ * Use these for one-off formatting where you don't need cross-reference
+ * features (year-suffix, citation numbering, disambiguation, collapsing).
+ * For documents with multiple citations, use createRegistry() instead.
+ */
+
+/**
+ * Format a single bibliography entry.
+ *
+ * @param {import('@citestyle/types').CompiledStyle} style - A compiled CSL style module
+ * @param {import('@citestyle/types').CslItem} item - CSL-JSON item
+ * @param {import('@citestyle/types').FormatContext} [ctx] - Optional format context
+ * @returns {import('@citestyle/types').FormattedEntry}
+ */
+export function format(style, item, ctx = {}) {
+  if (!style?.bibliography) {
+    throw new Error('format() requires a compiled style with a bibliography() function')
+  }
+  return style.bibliography(item, ctx)
+}
+
+/**
+ * Format multiple bibliography entries with basic sorting.
+ *
+ * Items are sorted using the style's sort comparator (if any) and assigned
+ * citation numbers in order. Does NOT perform year-suffix disambiguation,
+ * name disambiguation, or subsequent-author-substitute — use createRegistry()
+ * for those features.
+ *
+ * @param {import('@citestyle/types').CompiledStyle} style - A compiled CSL style module
+ * @param {import('@citestyle/types').CslItem[]} items - CSL-JSON items
+ * @param {import('@citestyle/types').FormatContext} [ctx] - Optional format context
+ * @returns {import('@citestyle/types').FormattedEntry[]}
+ */
+export function formatAll(style, items, ctx = {}) {
+  if (!style?.bibliography) {
+    throw new Error('formatAll() requires a compiled style with a bibliography() function')
+  }
+  let sorted = [...items]
+  if (style.bibliographySort) {
+    sorted.sort(style.bibliographySort)
+  }
+  // Assign citation numbers (shallow-clone to avoid mutating user's items)
+  sorted = sorted.map((item, i) => ({ ...item, 'citation-number': i + 1 }))
+  return sorted.map(item => style.bibliography(item, ctx))
+}
+
+/**
+ * Format a single inline citation.
+ *
+ * @param {import('@citestyle/types').CompiledStyle} style - A compiled CSL style module
+ * @param {import('@citestyle/types').CiteRef[]} cites - Citation references with items
+ * @param {import('@citestyle/types').FormatContext} [ctx] - Optional format context
+ * @returns {import('@citestyle/types').FormattedCitation}
+ */
+export function formatCitation(style, cites, ctx = {}) {
+  if (!style?.citation) {
+    throw new Error('formatCitation() requires a compiled style with a citation() function')
+  }
+  // Assign citation numbers if not already set (shallow-clone to avoid mutating user's items)
+  const safeCites = cites.map((cite, i) => {
+    if (cite.item && cite.item['citation-number'] == null) {
+      return { ...cite, item: { ...cite.item, 'citation-number': i + 1 } }
+    }
+    return cite
+  })
+  return style.citation(safeCites, ctx)
+}

package/src/index.js

@@ -8,6 +8,10 @@
  * - Citation number tracking (numeric styles)
  * - Bibliography sorting (using compiled comparator)
  * - Subsequent-author-substitute
+ *
+ * Also provides simple format/formatAll/formatCitation helpers for
+ * one-off formatting without a full registry.
  */
 
 export { createRegistry } from './registry.js'
+export { format, formatAll, formatCitation } from './format.js'

package/types.d.ts

@@ -1 +1 @@
-export { createRegistry, Registry, RegistryOptions } from '@citestyle/types'
+export { createRegistry, format, formatAll, formatCitation, Registry, RegistryOptions } from '@citestyle/types'