@citestyle/core 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proximify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @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).
+
+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.
+
+## Installation
+
+```bash
+npm install @citestyle/core
+```
+
+## API Reference
+
+### Name Formatting
+
+#### `formatNames(names, config?)`
+
+Format a list of CSL name objects according to CSL name options.
+
+```js
+import { formatNames } from '@citestyle/core'
+
+formatNames(
+  [{ family: 'Smith', given: 'John' }, { family: 'Doe', given: 'Jane' }],
+  { and: 'text', delimiter: ', ', initializeWith: '. ' }
+)
+// "J. Smith and J. Doe"
+```
+
+Config options: `and`, `delimiter`, `delimiterPrecedesLast`, `etAlMin`, `etAlUseFirst`, `etAlUseLast`, `initialize`, `initializeWith`, `nameAsSortOrder`, `sortSeparator`, `nameParts`, `form`.
+
+### Date Formatting
+
+#### `formatDate(date, config?)`
+
+Format a CSL date object with configurable parts, month terms, and range support.
+
+```js
+import { formatDate } from '@citestyle/core'
+
+formatDate(
+  { 'date-parts': [[2024, 3, 15]] },
+  { dateParts: [{ name: 'year' }, { name: 'month', prefix: ', ' }, { name: 'day', prefix: ' ' }] }
+)
+// "2024, March 15"
+```
+
+### Text-Case Transforms
+
+All transforms respect `<span class="nocase">` protection in CSL-JSON values.
+
+#### `applyTextCase(str, textCase)`
+
+Unified entry point for all CSL text-case values: `'lowercase'`, `'uppercase'`, `'capitalize-first'`, `'capitalize-all'`, `'title'`, `'sentence'`.
+
+```js
+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"
+```
+
+#### `titleCase(str)`
+
+Title-case with stop word handling. Preserves acronyms and intentional casing.
+
+#### `sentenceCase(str)`
+
+Capitalize first word only. Preserves all-caps acronyms (DNA, USA) in mixed-case input.
+
+#### `capitalize(str)`
+
+Capitalize the first character of the string.
+
+#### `stripNocaseSpans(str)`
+
+Remove `<span class="nocase">` tags without applying any case transform.
+
+### Number Formatting
+
+#### `ordinal(n, locale?)`
+
+Format as ordinal: `ordinal(3)` returns `"3rd"`. Supports locale-specific suffixes.
+
+#### `longOrdinal(n, locale?)`
+
+Format as long ordinal: `longOrdinal(2)` returns `"second"`. Falls back to numeric ordinal for n > 10.
+
+#### `roman(n)`
+
+Format as lowercase Roman numeral: `roman(14)` returns `"xiv"`.
+
+### Page Ranges
+
+#### `pageRange(pages, format?)`
+
+Format page ranges per CSL `page-range-format`: `'expanded'`, `'chicago'`, `'minimal'`, `'minimal-two'`.
+
+```js
+import { pageRange } from '@citestyle/core'
+
+pageRange('321-328', 'chicago')  // "321\u201328"  (321-28 with en-dash)
+pageRange('321-328', 'minimal')  // "321\u20138"   (321-8 with en-dash)
+```
+
+### HTML Output
+
+#### `escapeHtml(str)`
+
+Escape `&`, `<`, `>`, `"`, `'` for safe HTML output.
+
+#### `toHtml(str)`
+
+Convert PUA formatting tokens to HTML tags. Also auto-links DOIs and URLs. This is the final output step for HTML rendering.
+
+#### `stripFormatting(str)`
+
+Remove all PUA formatting tokens, returning clean plain text.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@citestyle/core",
+  "version": "0.0.2",
+  "description": "Shared runtime helpers for compiled CSL styles (~6-8KB)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "types.d.ts",
+    "README.md"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run",
+    "lint": "echo 'TODO: configure linter'"
+  }
+}

package/src/dates.js

@@ -0,0 +1,119 @@
+/**
+ * Date formatting engine.
+ *
+ * Handles: localized and non-localized date forms, date-part formatting,
+ * date ranges, seasons.
+ *
+ * @param {import('@citestyle/types').CslDate} date
+ * @param {object} config - Style-specific config baked in by compiler
+ * @param {Array<{name: string, form?: string, prefix?: string, suffix?: string, rangeDelimiter?: string}>} [config.dateParts]
+ *   - Date parts to render, in order
+ * @param {object} [config.monthTerms] - Locale month terms { '1': 'January', ... }
+ * @param {object} [config.seasonTerms] - Locale season terms { '1': 'Spring', ... }
+ * @returns {string} Formatted date string
+ */
+export function formatDate(date, config = {}) {
+  if (!date) return ''
+
+  // Handle literal dates
+  if (date.literal) return date.literal
+
+  const parts = date['date-parts']
+  if (!parts || !parts.length || !parts[0].length) return ''
+
+  const {
+    dateParts = [{ name: 'year' }],
+    monthTerms = DEFAULT_MONTHS,
+    seasonTerms = DEFAULT_SEASONS,
+  } = config
+
+  const dp = parts[0]
+  const year = dp[0]
+  const month = dp.length > 1 ? dp[1] : undefined
+  const day = dp.length > 2 ? dp[2] : undefined
+
+  // Check for date range (two date-parts arrays)
+  const hasRange = parts.length > 1 && parts[1].length > 0
+  const dp2 = hasRange ? parts[1] : null
+  const year2 = dp2 ? dp2[0] : undefined
+  const month2 = dp2 && dp2.length > 1 ? dp2[1] : undefined
+  const day2 = dp2 && dp2.length > 2 ? dp2[2] : undefined
+
+  // Format each requested date part
+  const result = []
+  for (const partCfg of dateParts) {
+    const val = formatDatePart(partCfg, { year, month, day, date }, { monthTerms, seasonTerms })
+    if (val === '') continue
+
+    let out = val
+    if (hasRange) {
+      const val2 = formatDatePart(partCfg, {
+        year: year2, month: month2, day: day2, date,
+      }, { monthTerms, seasonTerms })
+      if (val2 && val2 !== val) {
+        const rangeDelim = partCfg.rangeDelimiter || '\u2013'
+        out = val + rangeDelim + val2
+      }
+    }
+
+    if (partCfg.prefix) out = partCfg.prefix + out
+    if (partCfg.suffix) out = out + partCfg.suffix
+    result.push(out)
+  }
+
+  return result.join('')
+}
+
+/**
+ * Format a single date part.
+ */
+function formatDatePart(cfg, vals, terms) {
+  const { name, form } = cfg
+  const { year, month, day, date } = vals
+
+  if (name === 'year') {
+    if (year == null) return ''
+    let y = String(year)
+    if (form === 'short') {
+      y = y.slice(-2)
+    }
+    return y
+  }
+
+  if (name === 'month') {
+    if (date && date.season) {
+      return terms.seasonTerms[String(date.season)] || ''
+    }
+    if (month == null) return ''
+    if (form === 'numeric') return String(month)
+    if (form === 'numeric-leading-zeros') return String(month).padStart(2, '0')
+    if (form === 'short') return (terms.monthTerms[String(month)] || '').slice(0, 3)
+    // Default: long form
+    return terms.monthTerms[String(month)] || ''
+  }
+
+  if (name === 'day') {
+    if (day == null) return ''
+    if (form === 'numeric-leading-zeros') return String(day).padStart(2, '0')
+    if (form === 'ordinal') return ordinalDay(day)
+    return String(day)
+  }
+
+  return ''
+}
+
+function ordinalDay(n) {
+  const s = ['th', 'st', 'nd', 'rd']
+  const v = n % 100
+  return n + (s[(v - 20) % 10] || s[v] || s[0])
+}
+
+const DEFAULT_MONTHS = {
+  '1': 'January', '2': 'February', '3': 'March', '4': 'April',
+  '5': 'May', '6': 'June', '7': 'July', '8': 'August',
+  '9': 'September', '10': 'October', '11': 'November', '12': 'December',
+}
+
+const DEFAULT_SEASONS = {
+  '1': 'Spring', '2': 'Summer', '3': 'Autumn', '4': 'Winter',
+}

package/src/html.js

@@ -0,0 +1,131 @@
+/**
+ * HTML escaping for safe output.
+ *
+ * Every variable interpolation in the structured HTML output must be
+ * escaped to prevent XSS. This is the single function for that.
+ *
+ * @param {string} str - Raw string to escape
+ * @returns {string} HTML-safe string
+ */
+export function escapeHtml(str) {
+  if (!str) return ''
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;')
+}
+
+/**
+ * Formatting tokens — Unicode Private Use Area characters embedded in
+ * text output by compiled styles to mark formatting spans. These are
+ * invisible in plain text and get converted to HTML tags by toHtml().
+ *
+ * Font formatting tokens (U+E000-E007):
+ *   U+E000/E001 = italic start/end
+ *   U+E002/E003 = bold start/end
+ *   U+E004/E005 = small-caps start/end
+ *   U+E006/E007 = underline start/end
+ *
+ * Semantic span tokens (U+E020-E022):
+ *   U+E020 = semantic span start (followed by class name until U+E021)
+ *   U+E021 = separator between class name and content
+ *   U+E022 = semantic span end
+ *
+ * Example: \uE020title\uE021My Book Title\uE022
+ *   → stripFormatting: "My Book Title"
+ *   → toHtml: '<span class="csl-title">My Book Title</span>'
+ */
+const FMT_REGEX = /[\uE000-\uE007]/g
+const SEM_OPEN_REGEX = /\uE020[^\uE021]*\uE021/g
+const SEM_CLOSE = /\uE022/g
+
+/**
+ * Strip formatting tokens from text output.
+ *
+ * @param {string} str - Text with embedded formatting tokens
+ * @returns {string} Clean plain text
+ */
+export function stripFormatting(str) {
+  if (!str) return ''
+  return str
+    .replace(SEM_OPEN_REGEX, '')  // strip semantic open markers + class names
+    .replace(FMT_REGEX, '')        // strip font formatting tokens
+    .replace(SEM_CLOSE, '')        // strip semantic close markers
+}
+
+/**
+ * Convert a formatted text string to semantic HTML.
+ *
+ * Processing order matters — auto-linking must happen while PUA tokens
+ * are still in the string (before they become HTML tags that would
+ * interfere with URL matching), then tokens are converted to HTML.
+ *
+ * 1. Escapes HTML entities (XSS protection)
+ * 2. Auto-links DOI URLs (while PUA tokens still present)
+ * 3. Auto-links other URLs (while PUA tokens still present)
+ * 4. Converts formatting tokens to HTML tags (italic, bold, etc.)
+ * 5. Converts semantic tokens to CSS-classed spans
+ *
+ * @param {string} str - Text with optional formatting tokens
+ * @returns {string} HTML string
+ */
+export function toHtml(str) {
+  if (!str) return ''
+
+  // Escape HTML entities first (tokens are PUA chars, unaffected)
+  let html = escapeHtml(str)
+
+  // Auto-link DOI URLs (before token conversion — PUA chars used as URL boundaries)
+  // The [^\s<)\uE000-\uE022] excludes PUA tokens from URL matching
+  html = html.replace(
+    /https:\/\/doi\.org\/[^\s<)\uE000-\uE022]+/g,
+    match => {
+      const cleaned = match.replace(/[.,;:]+$/, '')
+      const trailing = match.slice(cleaned.length)
+      return `<a class="csl-doi" href="${cleaned}">${cleaned}</a>${trailing}`
+    }
+  )
+
+  // Auto-link bare DOIs (e.g., "doi:10.1038/nn.2024" or "doi: 10.1038/nn.2024")
+  html = html.replace(
+    /(?<!href="|">)doi:\s*(10\.[^\s<)\uE000-\uE022]+)/gi,
+    (match, doi) => {
+      const cleaned = doi.replace(/[.,;:]+$/, '')
+      const trailing = doi.slice(cleaned.length)
+      const prefix = match.slice(0, match.indexOf('10.'))
+      return `${prefix}<a class="csl-doi" href="https://doi.org/${cleaned}">${cleaned}</a>${trailing}`
+    }
+  )
+
+  // Auto-link remaining URLs (exclude PUA tokens from URL boundaries)
+  html = html.replace(
+    /(?<!href="|">)https?:\/\/[^\s<)\uE000-\uE022]+/g,
+    match => {
+      if (match.includes('doi.org/')) return match
+      const cleaned = match.replace(/[.,;:]+$/, '')
+      const trailing = match.slice(cleaned.length)
+      return `<a class="csl-url" href="${cleaned}">${cleaned}</a>${trailing}`
+    }
+  )
+
+  // Convert formatting tokens to HTML tags
+  html = html
+    .replace(/\uE000/g, '<i>')
+    .replace(/\uE001/g, '</i>')
+    .replace(/\uE002/g, '<b>')
+    .replace(/\uE003/g, '</b>')
+    .replace(/\uE004/g, '<span class="csl-sc">')
+    .replace(/\uE005/g, '</span>')
+    .replace(/\uE006/g, '<span class="csl-ul">')
+    .replace(/\uE007/g, '</span>')
+
+  // Convert semantic span tokens to CSS-classed spans
+  html = html.replace(/\uE020([^\uE021]*)\uE021/g, (_, cls) =>
+    `<span class="csl-${cls}">`
+  )
+  html = html.replace(/\uE022/g, '</span>')
+
+  return html
+}

package/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * @citestyle/core
+ *
+ * Shared runtime helpers imported by all compiled CSL styles.
+ * Keeps individual style modules small (~3-5KB) by centralizing
+ * complex formatting logic here (~6-8KB shared).
+ */
+
+export { formatNames } from './names.js'
+export { formatDate } from './dates.js'
+export { titleCase, sentenceCase, capitalize, applyTextCase, stripNocaseSpans } from './text.js'
+export { ordinal, longOrdinal, roman } from './numbers.js'
+export { pageRange } from './pages.js'
+export { escapeHtml, stripFormatting, toHtml } from './html.js'

package/src/names.js

@@ -0,0 +1,268 @@
+/**
+ * Name formatting engine.
+ *
+ * Handles: et-al truncation, delimiter-precedes-last, name-as-sort-order,
+ * initialize-with, name particles (von, de la), name-part formatting,
+ * substitute fallback chains.
+ *
+ * @param {import('@citestyle/types').CslName[]} names
+ * @param {object} config - Style-specific config baked in by compiler
+ * @param {string} [config.and] - 'text'|'symbol' → "and"|"&"
+ * @param {string} [config.delimiter=', '] - Delimiter between names
+ * @param {string} [config.delimiterPrecedesLast='contextual'] - 'contextual'|'always'|'never'|'after-inverted-name'
+ * @param {string} [config.delimiterPrecedesEtAl='contextual'] - 'contextual'|'always'|'never'|'after-inverted-name'
+ * @param {number} [config.etAlMin] - Min names to trigger et-al
+ * @param {number} [config.etAlUseFirst] - Names to show before et-al
+ * @param {boolean} [config.etAlUseLast] - Show "…, Last" pattern (no "and")
+ * @param {boolean} [config.initialize=true] - Abbreviate given names
+ * @param {string} [config.initializeWith] - String after initials (e.g. '. ')
+ * @param {string} [config.nameAsSortOrder] - 'first'|'all' → "Family, Given" ordering
+ * @param {string} [config.sortSeparator=', '] - Separator in inverted names
+ * @param {string} [config.andTerm='and'] - Resolved locale "and" term
+ * @param {string} [config.etAlTerm='et al.'] - Resolved locale "et-al" term
+ * @param {Array} [config.nameParts] - Per-part formatting [{name:'family', textCase:'uppercase', ...}]
+ * @returns {string} Formatted name string
+ */
+export function formatNames(names, config = {}) {
+  if (!names || !names.length) return ''
+
+  const {
+    and,
+    delimiter = ', ',
+    delimiterPrecedesLast = 'contextual',
+    delimiterPrecedesEtAl = 'contextual',
+    etAlMin,
+    etAlUseFirst,
+    etAlUseLast = false,
+    initialize = true,
+    initializeWith,
+    nameAsSortOrder,
+    sortSeparator = ', ',
+    andTerm = 'and',
+    etAlTerm = 'et al.',
+    form = 'long',
+    nameParts = [],
+  } = config
+
+  // Determine if et-al truncation applies
+  // Disambiguation override: registry may increase etAlUseFirst to show more names
+  const effectiveEtAlMin = config._disambig?.etAlMin ?? etAlMin
+  const effectiveEtAlUseFirst = config._disambig?.etAlUseFirst ?? etAlUseFirst
+  let truncated = false
+  let displayNames = names
+  if (effectiveEtAlMin && effectiveEtAlUseFirst && names.length >= effectiveEtAlMin) {
+    truncated = true
+    if (etAlUseLast && names.length > effectiveEtAlUseFirst + 1) {
+      // Show first N, then last (ellipsis added during join)
+      displayNames = [
+        ...names.slice(0, effectiveEtAlUseFirst),
+        names[names.length - 1],
+      ]
+    } else {
+      displayNames = names.slice(0, effectiveEtAlUseFirst)
+    }
+  }
+
+  // Handle form="count" — return number of names
+  if (form === 'count') return String(displayNames.length)
+
+  // Disambiguation config (set by registry for name disambiguation)
+  const disambig = config._disambig
+
+  // Format individual names
+  const formatted = displayNames.map((name, i) => {
+    // Determine effective form/initialize for this name position
+    let nameForm = form
+    let nameInit = initialize
+    let nameInitWith = initializeWith
+
+    if (disambig && nameForm === 'short') {
+      // Check if this name index should be expanded
+      const expand = disambig.expandAll || (disambig.expandIndices && disambig.expandIndices.includes(i))
+      if (expand) {
+        nameForm = 'long'
+        if (disambig.withInitials) {
+          nameInit = true
+          nameInitWith = disambig.initializeWith ?? initializeWith ?? '. '
+        } else {
+          nameInit = false // show full given names
+        }
+      }
+    }
+
+    // form="short" — family name only
+    if (nameForm === 'short') {
+      if (name.literal) return name.literal
+      let family = buildFamilyWithParticles(name)
+      family = applyNamePartFormatting(family, 'family', nameParts)
+      return family
+    }
+
+    return formatSingleName(name, {
+      initialize: nameInit,
+      initializeWith: nameInitWith,
+      nameAsSortOrder,
+      sortSeparator,
+      index: i,
+      nameParts,
+    })
+  })
+
+  // Join names with delimiters
+  if (formatted.length === 0) return ''
+  if (formatted.length === 1 && !truncated) {
+    return formatted[0]
+  }
+
+  // Handle et-al-use-last: "A, B, … Z" pattern (no "and" connector)
+  if (truncated && etAlUseLast) {
+    const init = formatted.slice(0, -1) // first N names
+    const last = formatted[formatted.length - 1]
+    return (init.length > 0 ? init.join(delimiter) + delimiter : '') + '\u2026 ' + last
+  }
+
+  // Handle et-al case (no "and" connector, just "et al." after names)
+  if (truncated) {
+    const joined = formatted.join(delimiter)
+    // delimiter-precedes-et-al controls separator before "et al."
+    const dpea = delimiterPrecedesEtAl || 'contextual'
+    let useDelim
+    if (dpea === 'always') useDelim = true
+    else if (dpea === 'never') useDelim = false
+    else if (dpea === 'after-inverted-name') useDelim = !!nameAsSortOrder
+    else useDelim = formatted.length > 1 // contextual
+    return joined + (useDelim ? delimiter : ' ') + etAlTerm
+  }
+
+  // Normal multi-name join
+  const andStr = and === 'symbol' ? '&' : and === 'text' ? andTerm : null
+
+  if (!andStr) {
+    return formatted.join(delimiter)
+  }
+
+  if (formatted.length === 2) {
+    // Two names: "A & B" or "A, & B"
+    const useDelim = delimiterPrecedesLast === 'always' ||
+      (delimiterPrecedesLast === 'after-inverted-name' && nameAsSortOrder)
+    const sep = useDelim ? delimiter + andStr + ' ' : ' ' + andStr + ' '
+    return formatted[0] + sep + formatted[1]
+  }
+
+  // Three or more names
+  const init = formatted.slice(0, -1)
+  const last = formatted[formatted.length - 1]
+
+  const useDelimBeforeLast = delimiterPrecedesLast === 'always' ||
+    delimiterPrecedesLast === 'after-inverted-name' ||
+    (delimiterPrecedesLast === 'contextual' && formatted.length > 2)
+
+  const sep = useDelimBeforeLast ? delimiter + andStr + ' ' : ' ' + andStr + ' '
+  return init.join(delimiter) + sep + last
+}
+
+/**
+ * Format a single name.
+ */
+function formatSingleName(name, opts) {
+  const { initialize, initializeWith, nameAsSortOrder, sortSeparator = ', ', index, nameParts = [] } = opts
+
+  // Literal names (institutional, etc.)
+  if (name.literal) return name.literal
+
+  let family = buildFamilyWithParticles(name)
+  let given = name.given || ''
+
+  // Initialize given names (e.g., "John Andrew" → "J. A.")
+  // initializeWith can be "" (empty string) for styles like Vancouver → "JA"
+  if (initialize && initializeWith != null && given) {
+    given = initializeGiven(given, initializeWith)
+  }
+
+  // Apply name-part formatting (text-case, font formatting)
+  family = applyNamePartFormatting(family, 'family', nameParts)
+  given = applyNamePartFormatting(given, 'given', nameParts)
+
+  if (!given) return family
+
+  // Determine sort order (inverted: "Family, Given" vs. normal: "Given Family")
+  const invert = nameAsSortOrder === 'all' ||
+    (nameAsSortOrder === 'first' && index === 0)
+
+  if (invert) {
+    return family + sortSeparator + given
+  }
+  return given + ' ' + family
+}
+
+/**
+ * Build family name with particles.
+ * E.g., { family: 'Beethoven', 'non-dropping-particle': 'van' } → 'van Beethoven'
+ */
+function buildFamilyWithParticles(name) {
+  let family = name.family || ''
+  const ndp = name['non-dropping-particle']
+  const dp = name['dropping-particle']
+  const suffix = name.suffix
+
+  if (ndp) family = ndp + ' ' + family
+  if (dp) family = dp + ' ' + family
+  if (suffix) family = family + ' ' + suffix
+
+  return family
+}
+
+/**
+ * Apply name-part formatting (text-case and font formatting) to a name part.
+ *
+ * @param {string} str - The name part string
+ * @param {string} partName - 'family' or 'given'
+ * @param {Array} nameParts - Array of name-part configs
+ * @returns {string} Formatted name part
+ */
+function applyNamePartFormatting(str, partName, nameParts) {
+  if (!str || !nameParts || nameParts.length === 0) return str
+
+  const cfg = nameParts.find(np => np.name === partName)
+  if (!cfg) return str
+
+  // Apply text-case
+  if (cfg.textCase === 'uppercase') str = str.toUpperCase()
+  else if (cfg.textCase === 'lowercase') str = str.toLowerCase()
+  else if (cfg.textCase === 'capitalize-first') str = str.charAt(0).toUpperCase() + str.slice(1)
+  else if (cfg.textCase === 'capitalize-all') str = str.split(' ').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')
+
+  // Apply font formatting using PUA tokens
+  if (cfg.fontStyle === 'italic') str = '\uE000' + str + '\uE001'
+  if (cfg.fontWeight === 'bold') str = '\uE002' + str + '\uE003'
+  if (cfg.fontVariant === 'small-caps') str = '\uE004' + str + '\uE005'
+
+  return str
+}
+
+/**
+ * Initialize given names.
+ * "John Andrew" with ". " → "J. A."
+ * "Jean-Pierre" with ". " → "J.-P."
+ */
+function initializeGiven(given, initWith) {
+  const trimmedInit = initWith.trimEnd()
+  // When initializeWith is empty (""), join initials without space (e.g., "JA")
+  // When it has content (". "), join with space (e.g., "J. A.")
+  const joinWith = initWith === '' ? '' : ' '
+
+  return given
+    .split(/\s+/)
+    .filter(Boolean)
+    .map(part => {
+      // Handle hyphenated names: "Jean-Pierre" → "J.-P."
+      if (part.includes('-')) {
+        return part
+          .split('-')
+          .map(sub => sub ? sub.charAt(0).toUpperCase() + trimmedInit : '')
+          .join('-')
+      }
+      return part.charAt(0).toUpperCase() + trimmedInit
+    })
+    .join(joinWith)
+}

package/src/numbers.js

@@ -0,0 +1,97 @@
+/**
+ * Number formatting: ordinal, long-ordinal, roman numerals.
+ */
+
+/**
+ * Format number as ordinal (1st, 2nd, 3rd, 4th, ...).
+ *
+ * @param {number} n
+ * @param {object} [locale] - Locale ordinal config (for non-English)
+ * @param {object} [locale.terms] - Ordinal terms from locale
+ * @returns {string}
+ */
+export function ordinal(n, locale) {
+  if (n == null) return ''
+  n = Number(n)
+  if (isNaN(n)) return String(n)
+
+  // Use locale-specific ordinal terms if provided
+  if (locale && locale.terms) {
+    const suffix = resolveOrdinalTerm(n, locale.terms)
+    if (suffix != null) return n + suffix
+  }
+
+  // English default
+  const s = ['th', 'st', 'nd', 'rd']
+  const v = Math.abs(n) % 100
+  return n + (s[(v - 20) % 10] || s[v] || s[0])
+}
+
+/**
+ * Resolve ordinal suffix from locale terms.
+ * CSL locales can define: ordinal, ordinal-00 through ordinal-99
+ */
+function resolveOrdinalTerm(n, terms) {
+  const abs = Math.abs(n)
+  // Try specific: ordinal-01, ordinal-02, ...
+  const padded = String(abs % 100).padStart(2, '0')
+  if (terms['ordinal-' + padded] != null) return terms['ordinal-' + padded]
+  // Try last digit: ordinal-01, ordinal-02, ordinal-03, ordinal-04
+  const lastDigit = String(abs % 10).padStart(2, '0')
+  if (terms['ordinal-' + lastDigit] != null) return terms['ordinal-' + lastDigit]
+  // Fallback to generic ordinal
+  if (terms['ordinal'] != null) return terms['ordinal']
+  return null
+}
+
+/**
+ * Format number as long ordinal (first, second, third, ...).
+ * Falls back to ordinal for numbers > 10.
+ *
+ * @param {number} n
+ * @param {object} [locale]
+ * @returns {string}
+ */
+export function longOrdinal(n, locale) {
+  if (n == null) return ''
+  n = Number(n)
+
+  // Check locale long-ordinal terms
+  if (locale && locale.terms) {
+    const padded = String(Math.abs(n) % 100).padStart(2, '0')
+    const term = locale.terms['long-ordinal-' + padded]
+    if (term) return term
+  }
+
+  // English defaults for 1-10
+  const LONG = ['', 'first', 'second', 'third', 'fourth', 'fifth',
+    'sixth', 'seventh', 'eighth', 'ninth', 'tenth']
+  if (n >= 1 && n <= 10) return LONG[n]
+
+  // Fall back to numeric ordinal
+  return ordinal(n, locale)
+}
+
+/**
+ * Format number as roman numeral.
+ *
+ * @param {number} n
+ * @returns {string}
+ */
+export function roman(n) {
+  if (n == null) return ''
+  n = Number(n)
+  if (isNaN(n) || n <= 0) return String(n)
+
+  const values = [1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1]
+  const symbols = ['M', 'CM', 'D', 'CD', 'C', 'XC', 'L', 'XL', 'X', 'IX', 'V', 'IV', 'I']
+
+  let result = ''
+  for (let i = 0; i < values.length; i++) {
+    while (n >= values[i]) {
+      result += symbols[i]
+      n -= values[i]
+    }
+  }
+  return result.toLowerCase()
+}

package/src/pages.js

@@ -0,0 +1,78 @@
+/**
+ * Page range formatting.
+ *
+ * Supports expanded, chicago, minimal, and minimal-two algorithms
+ * per the CSL page-range-format attribute.
+ *
+ * @param {string} pages - Raw page string (e.g., "321-328")
+ * @param {string} [format] - 'chicago'|'expanded'|'minimal'|'minimal-two'
+ * @returns {string} Formatted page range
+ */
+export function pageRange(pages, format) {
+  if (!pages) return ''
+
+  // Normalize hyphens to en-dash for output
+  const normalized = pages.replace(/\s*[-\u2013]\s*/, '\u2013')
+
+  if (!format || format === 'expanded') {
+    // Expanded: show full numbers (321–328)
+    return normalized
+  }
+
+  // Try to parse as numeric range
+  const match = pages.match(/^(\d+)\s*[-\u2013]\s*(\d+)$/)
+  if (!match) return normalized // Non-numeric range, pass through
+
+  const first = match[1]
+  const last = match[2]
+
+  if (format === 'minimal') {
+    return first + '\u2013' + minimalEnd(first, last, 1)
+  }
+
+  if (format === 'minimal-two') {
+    return first + '\u2013' + minimalEnd(first, last, 2)
+  }
+
+  if (format === 'chicago') {
+    return first + '\u2013' + chicagoEnd(first, last)
+  }
+
+  return normalized
+}
+
+/**
+ * Minimal format: remove shared leading digits, keep at least `minDigits` digits.
+ */
+function minimalEnd(first, last, minDigits) {
+  let i = 0
+  while (i < first.length && i < last.length - minDigits && first[i] === last[i]) {
+    i++
+  }
+  return last.slice(i)
+}
+
+/**
+ * Chicago page range algorithm (16th ed. 9.64):
+ * - 1-99: use all digits (3-10, 71-72, 96-117)
+ * - 100+: if second number ≤ 109 (in its hundred), use changed part only (100-104 → 100-104)
+ * - For x01-x09: use changed part only (1496-1504 → 1496–504)
+ * - Otherwise: use at least 2 digits (321-328 → 321–28, 1087-1089 → 1087–89)
+ */
+function chicagoEnd(first, last) {
+  const f = parseInt(first, 10)
+  const l = parseInt(last, 10)
+
+  // Less than 100: use all digits
+  if (f < 100) return last
+
+  // 100s: if both in same hundred and last ends in 00-09, use all digits
+  const fHundred = Math.floor(f / 100)
+  const lHundred = Math.floor(l / 100)
+  if (fHundred === lHundred && (l % 100) >= 0 && (l % 100) <= 9) {
+    return last
+  }
+
+  // Use at least 2 digits
+  return minimalEnd(first, last, 2)
+}

package/src/text.js

@@ -0,0 +1,311 @@
+/**
+ * Text-case transforms.
+ *
+ * CSL text-case values: lowercase, uppercase, capitalize-first,
+ * capitalize-all, title, sentence.
+ *
+ * Nocase span support: CSL-JSON values may contain
+ * `<span class="nocase">...</span>` to protect text from case transforms.
+ * Protected regions are preserved as-is during transformation, then the
+ * span tags are stripped from the final output. Protected regions may
+ * contain PUA formatting tokens (U+E000-E007, U+E020-E022).
+ */
+
+// Regex to split on nocase spans — captures the protected content
+const NOCASE_RE = /<span class="nocase">([\s\S]*?)<\/span>/g
+
+/**
+ * Apply a case transform while respecting nocase spans.
+ * Splits the string on nocase boundaries, applies the transform to
+ * unprotected segments only, then joins everything back together.
+ *
+ * @param {string} str - Input string (may contain nocase spans)
+ * @param {function} transform - Case transform function for unprotected text
+ * @returns {string} Transformed string with nocase spans stripped
+ */
+function withNocaseProtection(str, transform) {
+  if (!str) return ''
+  if (!str.includes('<span class="nocase">')) return transform(str)
+
+  const parts = []
+  let lastIndex = 0
+  let match
+  const re = new RegExp(NOCASE_RE.source, 'g')
+
+  while ((match = re.exec(str)) !== null) {
+    // Unprotected text before this span
+    if (match.index > lastIndex) {
+      parts.push({ text: str.slice(lastIndex, match.index), protect: false })
+    }
+    // Protected content (strip the span tags, keep content)
+    parts.push({ text: match[1], protect: true })
+    lastIndex = re.lastIndex
+  }
+
+  // Remaining unprotected text after last span
+  if (lastIndex < str.length) {
+    parts.push({ text: str.slice(lastIndex), protect: false })
+  }
+
+  return parts.map(p => p.protect ? p.text : transform(p.text)).join('')
+}
+
+// Words that should not be capitalized in title case (unless first/last word)
+const TITLE_STOP_WORDS = new Set([
+  'a', 'an', 'and', 'as', 'at', 'but', 'by', 'down', 'for', 'from',
+  'in', 'into', 'nor', 'of', 'on', 'onto', 'or', 'over', 'so',
+  'the', 'till', 'to', 'up', 'via', 'with', 'yet',
+])
+
+/**
+ * Convert text to title case.
+ * Capitalize all words except stop words (articles, prepositions, conjunctions).
+ * Always capitalize first and last word.
+ *
+ * @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 plainStr = str.replace(NOCASE_RE, '$1')
+  const isAllCaps = plainStr === plainStr.toUpperCase() && /[a-zA-Z]/.test(plainStr)
+
+  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('')
+}
+
+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++
+
+      // 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
+
+      // 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('')
+}
+
+/**
+ * Parse a string into nocase-protected and unprotected segments.
+ */
+function parseNocaseSegments(str) {
+  const parts = []
+  let lastIndex = 0
+  let match
+  const re = new RegExp(NOCASE_RE.source, 'g')
+  while ((match = re.exec(str)) !== null) {
+    if (match.index > lastIndex) {
+      parts.push({ text: str.slice(lastIndex, match.index), protect: false })
+    }
+    parts.push({ text: match[1], protect: true })
+    lastIndex = re.lastIndex
+  }
+  if (lastIndex < str.length) {
+    parts.push({ text: str.slice(lastIndex), protect: false })
+  }
+  return parts
+}
+
+/**
+ * Convert text to sentence case.
+ * Lowercase all words except the first word and proper nouns.
+ * (We can't reliably detect proper nouns, so we only capitalize
+ * the first word and words after ": ".)
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function sentenceCase(str) {
+  if (!str) return ''
+  if (!str.includes('<span class="nocase">')) return _sentenceCaseInner(str)
+
+  // Nocase-aware: parse into segments, process as single sequence
+  const segments = parseNocaseSegments(str)
+  // Detect all-caps from unprotected segments only (nocase content shouldn't affect detection)
+  const unprotectedText = segments.filter(s => !s.protect).map(s => s.text).join('')
+  const isAllCaps = unprotectedText === unprotectedText.toUpperCase() && /[a-zA-Z]/.test(unprotectedText)
+
+  let globalWordIdx = 0
+  let afterColon = false
+  return segments.map(seg => {
+    if (seg.protect) {
+      // Count words in protected segments but don't transform
+      const words = seg.text.split(/(\s+)/)
+      for (const w of words) {
+        if (w.trim()) {
+          globalWordIdx++
+          afterColon = w.endsWith(':')
+        }
+      }
+      return seg.text
+    }
+
+    const words = seg.text.split(/(\s+)/)
+    return words.map(word => {
+      if (!word.trim()) return word
+      globalWordIdx++
+
+      // First word or after colon: capitalize
+      if (globalWordIdx === 1 || afterColon) {
+        afterColon = word.endsWith(':')
+        return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+      }
+
+      if (word.endsWith(':')) afterColon = true
+
+      // Preserve all-caps acronyms when string isn't entirely uppercase
+      if (/^[A-Z]{2,}$/.test(word) && !isAllCaps) return word
+      // Preserve mixed-case words
+      if (/[a-z][A-Z]|[A-Z][a-z].*[A-Z]/.test(word)) return word
+
+      return word.toLowerCase()
+    }).join('')
+  }).join('')
+}
+
+function _sentenceCaseInner(str) {
+  if (!str) return ''
+  const isAllCaps = str === str.toUpperCase() && /[a-zA-Z]/.test(str)
+  const words = str.split(/(\s+)/)
+  let wordIndex = 0
+  let afterColon = false
+
+  const result = words.map(word => {
+    if (!word.trim()) return word
+    wordIndex++
+
+    // Preserve all-caps words (acronyms) when string isn't entirely uppercase
+    if (/^[A-Z]{2,}$/.test(word) && !isAllCaps && wordIndex > 1) return word
+    // Preserve mixed-case words (e.g., "iPhone", "McDonald")
+    if (/[a-z][A-Z]|[A-Z][a-z].*[A-Z]/.test(word) && wordIndex > 1) return word
+
+    // First word or after colon: capitalize
+    if (wordIndex === 1 || afterColon) {
+      afterColon = false
+      // First word all-caps in non-all-caps string: capitalize normally
+      return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+    }
+
+    if (word.endsWith(':')) {
+      afterColon = true
+    }
+
+    return word.toLowerCase()
+  }).join('')
+
+  return result
+}
+
+/**
+ * Capitalize first character of string.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function capitalize(str) {
+  return withNocaseProtection(str, _capitalizeInner)
+}
+
+function _capitalizeInner(str) {
+  if (!str) return ''
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+/**
+ * Apply any CSL text-case transform with nocase protection.
+ * This is the single entry point used by compiled styles — routes to
+ * the appropriate transform function with nocase span handling.
+ *
+ * @param {string} str - Input string (may contain nocase spans)
+ * @param {string} textCase - CSL text-case value
+ * @returns {string}
+ */
+export function applyTextCase(str, textCase) {
+  if (!str || !textCase) return str || ''
+  switch (textCase) {
+    case 'lowercase': return withNocaseProtection(str, s => s.toLowerCase())
+    case 'uppercase': return withNocaseProtection(str, s => s.toUpperCase())
+    case 'capitalize-first': return capitalize(str)
+    case 'capitalize-all': return withNocaseProtection(str, s => s.split(' ').map(w => _capitalizeInner(w)).join(' '))
+    case 'title': return titleCase(str)
+    case 'sentence': return sentenceCase(str)
+    default: return str
+  }
+}
+
+/**
+ * Strip nocase spans from a string without applying any case transform.
+ * Used for values that pass through without text-case but may contain
+ * nocase spans from CSL-JSON input.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function stripNocaseSpans(str) {
+  if (!str || typeof str !== 'string') return str || ''
+  return str.replace(NOCASE_RE, '$1')
+}

package/types.d.ts

@@ -0,0 +1,18 @@
+export {
+  formatNames,
+  formatDate,
+  applyTextCase,
+  titleCase,
+  sentenceCase,
+  capitalize,
+  stripNocaseSpans,
+  ordinal,
+  longOrdinal,
+  roman,
+  pageRange,
+  escapeHtml,
+  stripFormatting,
+  toHtml,
+  NameFormatConfig,
+  DateFormatConfig,
+} from '@citestyle/types'