@citestyle/core 0.0.2 → 1.0.1

package/README.md

@@ -1,8 +1,8 @@
 # @citestyle/core
 
-Shared runtime helpers imported by all compiled CSL styles. Keeps individual style modules small (~3-5KB each) by centralizing formatting logic here (~6-8KB shared).
+Shared runtime library for the Citestyle ecosystem. Every compiled CSL style imports from this package — it provides the formatting functions that styles call at runtime (name formatting, date formatting, text-case transforms, number formatting, page ranges, and HTML output).
 
-Most consumers do not need to use this package directly -- compiled styles import from it automatically. This reference is for contributors and advanced use cases.
+**You probably don't need to install this directly.** It's automatically pulled in as a dependency of compiled styles and `@citestyle/registry`. This documentation is for contributors, advanced use cases, and anyone curious about what's under the hood.
 
 ## Installation
 
@@ -10,110 +10,144 @@ Most consumers do not need to use this package directly -- compiled styles impor
 npm install @citestyle/core
 ```
 
-## API Reference
+~6-8KB. Zero dependencies. Works in Node.js and browsers.
 
-### Name Formatting
+## What it does
+
+When the Citestyle compiler transforms a `.csl` file into JavaScript, the generated code calls functions from this package instead of inlining the logic. This keeps each compiled style small (~3-5KB) while sharing the heavier formatting logic (~6-8KB) across all styles.
+
+For example, a compiled APA style might generate:
+
+```javascript
+// Generated code in apa.js — calls into @citestyle/core
+import { formatNames, formatDate, applyTextCase, toHtml } from '@citestyle/core'
+
+// The style bakes in the *configuration*, core provides the *implementation*
+formatNames(item.author, { and: 'symbol', initializeWith: '. ', nameAsSortOrder: 'first' })
+```
+
+## API
+
+### Name formatting
 
 #### `formatNames(names, config?)`
 
-Format a list of CSL name objects according to CSL name options.
+Format CSL name objects according to style-specific rules. Handles et-al truncation, particles (von, de la), sort order, initialization, and all five CSL `disambiguate-add-givenname` rules.
 
-```js
+```javascript
 import { formatNames } from '@citestyle/core'
 
 formatNames(
   [{ family: 'Smith', given: 'John' }, { family: 'Doe', given: 'Jane' }],
   { and: 'text', delimiter: ', ', initializeWith: '. ' }
 )
-// "J. Smith and J. Doe"
+// → "J. Smith and J. Doe"
+
+formatNames(
+  [{ family: 'de la Cruz', given: 'Maria', 'non-dropping-particle': 'de la' }],
+  { nameAsSortOrder: 'all', sortSeparator: ', ' }
+)
+// → "de la Cruz, Maria"
 ```
 
-Config options: `and`, `delimiter`, `delimiterPrecedesLast`, `etAlMin`, `etAlUseFirst`, `etAlUseLast`, `initialize`, `initializeWith`, `nameAsSortOrder`, `sortSeparator`, `nameParts`, `form`.
+**Config options**: `and`, `delimiter`, `delimiterPrecedesLast`, `etAlMin`, `etAlUseFirst`, `etAlUseLast`, `initialize`, `initializeWith`, `nameAsSortOrder`, `sortSeparator`, `nameParts`, `form`.
 
-### Date Formatting
+### Date formatting
 
 #### `formatDate(date, config?)`
 
-Format a CSL date object with configurable parts, month terms, and range support.
+Format CSL date objects with configurable parts, localized month terms, ranges, and seasons.
 
-```js
+```javascript
 import { formatDate } from '@citestyle/core'
 
 formatDate(
   { 'date-parts': [[2024, 3, 15]] },
-  { dateParts: [{ name: 'year' }, { name: 'month', prefix: ', ' }, { name: 'day', prefix: ' ' }] }
+  { dateParts: [{ name: 'year' }, { name: 'month', form: 'long', prefix: ', ' }, { name: 'day', prefix: ' ' }] }
 )
-// "2024, March 15"
+// → "2024, March 15"
 ```
 
-### Text-Case Transforms
+### Text-case transforms
 
-All transforms respect `<span class="nocase">` protection in CSL-JSON values.
+All transforms respect `<span class="nocase">` protection in CSL-JSON values — brand names like "iPhone" and chemical terms like "pH" are preserved.
 
 #### `applyTextCase(str, textCase)`
 
-Unified entry point for all CSL text-case values: `'lowercase'`, `'uppercase'`, `'capitalize-first'`, `'capitalize-all'`, `'title'`, `'sentence'`.
+Unified entry point for all CSL text-case values.
 
-```js
+```javascript
 import { applyTextCase } from '@citestyle/core'
 
-applyTextCase('the art of war', 'title')     // "The Art of War"
-applyTextCase('A STUDY OF DNA', 'sentence')  // "A study of DNA"
+applyTextCase('the art of war', 'title')              // "The Art of War"
+applyTextCase('A STUDY OF DNA', 'sentence')            // "A study of DNA"
+applyTextCase('proceedings of the IEEE', 'title')      // "Proceedings of the IEEE"
+applyTextCase('<span class="nocase">iPhone</span> sales', 'uppercase')
+                                                       // "IPHONE SALES" → no: "iPhone SALES"
 ```
 
-#### `titleCase(str)`
+**Supported values**: `'lowercase'`, `'uppercase'`, `'capitalize-first'`, `'capitalize-all'`, `'title'`, `'sentence'`.
 
-Title-case with stop word handling. Preserves acronyms and intentional casing.
+#### Individual transforms
 
-#### `sentenceCase(str)`
+- **`titleCase(str)`** — Title case with stop-word handling. Preserves acronyms and nocase spans.
+- **`sentenceCase(str)`** — Lowercase all but first word. Preserves all-caps acronyms (DNA, USA) in mixed-case input.
+- **`capitalize(str)`** — Capitalize the first character.
+- **`stripNocaseSpans(str)`** — Remove `<span class="nocase">` tags without changing case. Used when a value passes through without any text-case transform.
 
-Capitalize first word only. Preserves all-caps acronyms (DNA, USA) in mixed-case input.
+### Number formatting
 
-#### `capitalize(str)`
+```javascript
+import { ordinal, longOrdinal, roman } from '@citestyle/core'
 
-Capitalize the first character of the string.
-
-#### `stripNocaseSpans(str)`
-
-Remove `<span class="nocase">` tags without applying any case transform.
+ordinal(3)       // "3rd"
+ordinal(1, 'fr') // "1re" (locale-aware)
+longOrdinal(2)   // "second"
+roman(14)        // "xiv"
+```
 
-### Number Formatting
+### Page ranges
 
-#### `ordinal(n, locale?)`
+#### `pageRange(pages, format?)`
 
-Format as ordinal: `ordinal(3)` returns `"3rd"`. Supports locale-specific suffixes.
+Format page ranges per CSL `page-range-format` rules.
 
-#### `longOrdinal(n, locale?)`
+```javascript
+import { pageRange } from '@citestyle/core'
 
-Format as long ordinal: `longOrdinal(2)` returns `"second"`. Falls back to numeric ordinal for n > 10.
+pageRange('321-328', 'chicago')  // "321–28"   (en-dash, Chicago-style abbreviation)
+pageRange('321-328', 'minimal')  // "321–8"    (en-dash, minimal abbreviation)
+pageRange('321-328', 'expanded') // "321–328"  (en-dash, no abbreviation)
+```
 
-#### `roman(n)`
+### HTML output
 
-Format as lowercase Roman numeral: `roman(14)` returns `"xiv"`.
+#### `toHtml(str)`
 
-### Page Ranges
+Convert internal formatting tokens to semantic HTML. Also auto-links DOIs and URLs. This is the final output step — call it on the raw output from a compiled style function.
 
-#### `pageRange(pages, format?)`
+#### `stripFormatting(str)`
 
-Format page ranges per CSL `page-range-format`: `'expanded'`, `'chicago'`, `'minimal'`, `'minimal-two'`.
+Remove all formatting tokens for clean plain text output.
 
-```js
-import { pageRange } from '@citestyle/core'
+#### `escapeHtml(str)`
 
-pageRange('321-328', 'chicago')  // "321\u201328"  (321-28 with en-dash)
-pageRange('321-328', 'minimal')  // "321\u20138"   (321-8 with en-dash)
-```
+Escape `&`, `<`, `>`, `"`, `'` for safe HTML interpolation. Used internally by compiled styles for all variable output.
 
-### HTML Output
+### Validation
 
-#### `escapeHtml(str)`
+#### `validateItem(item)`
 
-Escape `&`, `<`, `>`, `"`, `'` for safe HTML output.
+Validate a CSL-JSON item and return warnings for common mistakes.
 
-#### `toHtml(str)`
+```javascript
+import { validateItem } from '@citestyle/core'
 
-Convert PUA formatting tokens to HTML tags. Also auto-links DOIs and URLs. This is the final output step for HTML rendering.
+validateItem({ id: '1', type: 'article-journal', title: 'My Paper', doi: '10.1234/x' })
+// { valid: true, warnings: ['Use uppercase "DOI" instead of "doi"'] }
 
-#### `stripFormatting(str)`
+validateItem({ title: 'Missing required fields' })
+// { valid: false, warnings: ['Missing required field: id', 'Missing required field: type'] }
+```
 
-Remove all PUA formatting tokens, returning clean plain text.
+Checks for: missing `id`/`type`, invalid type values, malformed name fields (should be arrays of objects with `family` or `literal`), malformed date fields, and common field-name mistakes (`doi` → `DOI`, `url` → `URL`, `isbn` → `ISBN`).

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "@citestyle/core",
-  "version": "0.0.2",
+  "version": "1.0.1",
   "description": "Shared runtime helpers for compiled CSL styles (~6-8KB)",
+  "author": "Uniweb",
+  "homepage": "https://github.com/uniweb/csl/tree/main/packages/core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uniweb/csl.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "csl",
+    "citation",
+    "formatting",
+    "names",
+    "dates",
+    "text-case"
+  ],
   "type": "module",
   "exports": {
     ".": {
@@ -23,7 +38,6 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "vitest run",
-    "lint": "echo 'TODO: configure linter'"
+    "test": "vitest run"
   }
 }

package/src/index.js

@@ -12,3 +12,4 @@ export { titleCase, sentenceCase, capitalize, applyTextCase, stripNocaseSpans }
 export { ordinal, longOrdinal, roman } from './numbers.js'
 export { pageRange } from './pages.js'
 export { escapeHtml, stripFormatting, toHtml } from './html.js'
+export { validateItem } from './validate.js'

package/src/text.js

@@ -58,95 +58,67 @@ const TITLE_STOP_WORDS = new Set([
 ])
 
 /**
- * Convert text to title case.
- * Capitalize all words except stop words (articles, prepositions, conjunctions).
- * Always capitalize first and last word.
+ * Convert text to title case, as CSL 1.0.2 defines it: in a lowercase or mixed-case string,
+ * capitalize the first character of each lowercase word and keep the case of every word that has
+ * capitals of its own (an acronym such as "AI", a name such as "iPhone" or "LLMs"); in an
+ * all-caps string, capitalize each word and lowercase the rest. Stop words (articles,
+ * prepositions, conjunctions) are lowercase unless they are the first or the last word, or
+ * follow a colon. Punctuation around a word ("AI:", "(and") is not part of it. Text inside
+ * `<span class="nocase">` is kept as written and still counts for first and last.
  *
  * @param {string} str
  * @returns {string}
  */
 export function titleCase(str) {
   if (!str) return ''
-  if (!str.includes('<span class="nocase">')) return _titleCaseInner(str)
-
-  // Nocase-aware title case: parse into segments (protected vs unprotected),
-  // then process all words as a single sequence for correct first/last detection
-  const segments = parseNocaseSegments(str)
-
-  // Collect all word tokens across segments for first/last word detection
-  const allWords = []
-  for (const seg of segments) {
-    const words = seg.text.split(/(\s+)/)
-    for (const w of words) {
-      if (w.trim()) allWords.push({ word: w, protect: seg.protect })
-    }
-  }
-
-  const totalWords = allWords.length
-  // Detect all-caps across full string (strip nocase spans for this check)
+  const segments = str.includes('<span class="nocase">') ? parseNocaseSegments(str) : [{ text: str, protect: false }]
   const plainStr = str.replace(NOCASE_RE, '$1')
-  const isAllCaps = plainStr === plainStr.toUpperCase() && /[a-zA-Z]/.test(plainStr)
+  // Detect all-caps across the full string (then its all-caps words are not acronyms)
+  const isAllCaps = plainStr === plainStr.toUpperCase() && /\p{L}/u.test(plainStr)
+  const totalWords = segments.reduce((n, seg) => n + seg.text.split(/\s+/).filter((w) => w.trim()).length, 0)
 
-  let globalWordIdx = 0
-  return segments.map(seg => {
-    if (seg.protect) {
-      // Count protected words but don't transform them
-      const words = seg.text.split(/(\s+)/)
-      for (const w of words) { if (w.trim()) globalWordIdx++ }
-      return seg.text
-    }
-
-    const words = seg.text.split(/(\s+)/)
-    return words.map(word => {
-      if (!word.trim()) return word
-      globalWordIdx++
-
-      if (/[a-z][A-Z]|[A-Z][a-z].*[A-Z]/.test(word)) return word
-      if (/^[A-Z]{2,}$/.test(word) && !isAllCaps) return word
-
-      if (globalWordIdx === 1 || globalWordIdx === totalWords) {
-        return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
-      }
-      if (TITLE_STOP_WORDS.has(word.toLowerCase())) {
-        return word.toLowerCase()
-      }
-      return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
-    }).join('')
-  }).join('')
+  let index = 0
+  let afterColon = false
+  return segments
+    .map((seg) =>
+      seg.text
+        .split(/(\s+)/)
+        .map((word) => {
+          if (!word.trim()) return word
+          index++
+          const out = seg.protect
+            ? word
+            : titleCaseWord(word, { first: index === 1, last: index === totalWords, afterColon, isAllCaps })
+          afterColon = ENDS_WITH_COLON.test(word)
+          return out
+        })
+        .join('')
+    )
+    .join('')
 }
 
-function _titleCaseInner(str) {
-  if (!str) return ''
-  const words = str.split(/(\s+)/)
-  let wordIndex = 0
-  const totalWords = words.filter(w => w.trim()).length
-  // Detect if the entire string is all-caps (then individual all-caps words aren't abbreviations)
-  const isAllCaps = str === str.toUpperCase() && /[a-zA-Z]/.test(str)
-
-  return words
-    .map(word => {
-      if (!word.trim()) return word // preserve whitespace
-      wordIndex++
+/** A word's leading punctuation, the word, and its trailing punctuation (and formatting tokens). */
+const WORD_PARTS = /^([^\p{L}\p{N}]*)(.*?)([^\p{L}\p{N}]*)$/su
 
-      // CSL spec: words with internal capitals (e.g., "OpenAI", "JavaScript")
-      // or all-caps words in a mixed-case string are treated as intentional
-      // casing and preserved as-is.
-      if (/[a-z][A-Z]|[A-Z][a-z].*[A-Z]/.test(word)) return word
-      // Preserve all-caps words (2+ chars) when the whole string isn't all-caps
-      if (/^[A-Z]{2,}$/.test(word) && !isAllCaps) return word
+/** A word that closes on a colon, maybe before formatting tokens: the next word starts a subtitle. */
+const ENDS_WITH_COLON = /:[--]*$/
 
-      // Always capitalize first and last word
-      if (wordIndex === 1 || wordIndex === totalWords) {
-        return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
-      }
-      // Don't capitalize stop words
-      if (TITLE_STOP_WORDS.has(word.toLowerCase())) {
-        return word.toLowerCase()
-      }
-      // Capitalize first letter, lowercase rest
-      return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
-    })
-    .join('')
+/**
+ * One word of a title-cased string.
+ *
+ * @param {string} word - a word with any punctuation around it
+ * @param {{ first: boolean, last: boolean, afterColon: boolean, isAllCaps: boolean }} at
+ */
+function titleCaseWord(word, { first, last, afterColon, isAllCaps }) {
+  const [, pre, core, post] = word.match(WORD_PARTS)
+  if (!core) return word
+  const lower = core.toLowerCase()
+  const stop = TITLE_STOP_WORDS.has(lower) && !first && !last && !afterColon
+  if (isAllCaps) return pre + (stop ? lower : core.charAt(0).toUpperCase() + core.slice(1).toLowerCase()) + post
+  if (core === lower) return pre + (stop ? core : core.charAt(0).toUpperCase() + core.slice(1)) + post
+  // A word with capitals of its own keeps them, save a stop word capitalized mid-title ("And")
+  if (stop && core === core.charAt(0) + core.slice(1).toLowerCase()) return pre + lower + post
+  return word
 }
 
 /**

package/src/validate.js

@@ -0,0 +1,110 @@
+/**
+ * CSL-JSON item validation.
+ *
+ * Checks that a CSL-JSON item has required fields and correct shapes.
+ * Returns an array of warning strings (empty = valid).
+ */
+
+const VALID_TYPES = new Set([
+  'article', 'article-journal', 'article-magazine', 'article-newspaper',
+  'bill', 'book', 'broadcast', 'chapter', 'dataset', 'entry',
+  'entry-dictionary', 'entry-encyclopedia', 'figure', 'graphic',
+  'interview', 'legal_case', 'legislation', 'manuscript', 'map',
+  'motion_picture', 'musical_score', 'pamphlet', 'paper-conference',
+  'patent', 'personal_communication', 'post', 'post-weblog',
+  'regulation', 'report', 'review', 'review-book', 'software',
+  'song', 'speech', 'standard', 'thesis', 'treaty', 'webpage',
+])
+
+const NAME_FIELDS = [
+  'author', 'editor', 'translator', 'container-author', 'collection-editor',
+  'composer', 'director', 'interviewer', 'reviewed-author', 'recipient',
+  'illustrator', 'original-author',
+]
+
+const DATE_FIELDS = [
+  'issued', 'accessed', 'original-date', 'submitted', 'event-date',
+]
+
+/**
+ * Validate a CSL-JSON item.
+ *
+ * @param {object} item - CSL-JSON item to validate
+ * @returns {{ valid: boolean, warnings: string[] }}
+ */
+export function validateItem(item) {
+  const warnings = []
+
+  if (!item || typeof item !== 'object') {
+    return { valid: false, warnings: ['Item must be an object'] }
+  }
+
+  // Required: id
+  if (item.id == null || item.id === '') {
+    warnings.push('Missing required field "id"')
+  }
+
+  // Required: type
+  if (!item.type) {
+    warnings.push('Missing required field "type"')
+  } else if (!VALID_TYPES.has(item.type)) {
+    warnings.push(`Unknown type "${item.type}"`)
+  }
+
+  // Validate name fields are arrays of objects
+  for (const field of NAME_FIELDS) {
+    if (item[field] != null) {
+      if (!Array.isArray(item[field])) {
+        warnings.push(`"${field}" must be an array of name objects`)
+      } else {
+        for (let i = 0; i < item[field].length; i++) {
+          const name = item[field][i]
+          if (!name || typeof name !== 'object') {
+            warnings.push(`${field}[${i}] must be a name object`)
+          } else if (!name.family && !name.literal) {
+            warnings.push(`${field}[${i}] must have "family" or "literal"`)
+          }
+        }
+      }
+    }
+  }
+
+  // Validate date fields
+  for (const field of DATE_FIELDS) {
+    if (item[field] != null) {
+      const date = item[field]
+      if (typeof date !== 'object' || Array.isArray(date)) {
+        warnings.push(`"${field}" must be a date object`)
+      } else if (!date['date-parts'] && !date.literal && !date.raw) {
+        warnings.push(`"${field}" must have "date-parts", "literal", or "raw"`)
+      } else if (date['date-parts']) {
+        if (!Array.isArray(date['date-parts'])) {
+          warnings.push(`${field}.date-parts must be an array`)
+        } else {
+          for (let i = 0; i < date['date-parts'].length; i++) {
+            const dp = date['date-parts'][i]
+            if (!Array.isArray(dp) || dp.length === 0) {
+              warnings.push(`${field}.date-parts[${i}] must be a non-empty array [year, month?, day?]`)
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Helpful warnings for common mistakes
+  if (item.doi && !item.DOI) {
+    warnings.push('"doi" should be "DOI" (uppercase)')
+  }
+  if (item.url && !item.URL) {
+    warnings.push('"url" should be "URL" (uppercase)')
+  }
+  if (item.isbn && !item.ISBN) {
+    warnings.push('"isbn" should be "ISBN" (uppercase)')
+  }
+  if (item.issn && !item.ISSN) {
+    warnings.push('"issn" should be "ISSN" (uppercase)')
+  }
+
+  return { valid: warnings.length === 0, warnings }
+}

package/types.d.ts

@@ -13,6 +13,8 @@ export {
   escapeHtml,
   stripFormatting,
   toHtml,
+  validateItem,
+  ValidationResult,
   NameFormatConfig,
   DateFormatConfig,
 } from '@citestyle/types'