@citestyle/core 0.0.2 → 1.0.0

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.0",
   "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/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'