@uniweb/scholar 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/scholar",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Academic content utilities for Uniweb - math rendering, bibliographic references, and inline citations",
   "type": "module",
   "exports": {
@@ -41,9 +41,13 @@
     "node": ">=20.19"
   },
   "dependencies": {
+    "@citestyle/bibtex": "^1.0.0",
+    "@citestyle/core": "^1.0.0",
+    "@citestyle/registry": "^1.0.0",
+    "@citestyle/styles": "^1.0.0",
     "katex": "^0.16.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
   }
-}
+}

package/src/bibliography/formatters/index.js

@@ -1,39 +1,58 @@
 /**
  * Bibliography Formatters
  *
+ * Delegates to @citestyle/* compiled styles for reference formatting.
+ * Returns structured output: { html, text, parts, links }.
+ *
  * @module @uniweb/scholar/bibliography/formatters
  */
 
-export { formatApa } from './apa.js'
-export { formatMla } from './mla.js'
-export { formatChicago } from './chicago.js'
-export { formatIeee } from './ieee.js'
+import * as apa from '@citestyle/styles/apa'
+import * as mla from '@citestyle/styles/mla'
+import * as chicagoAD from '@citestyle/styles/chicago-author-date'
+import * as ieee from '@citestyle/styles/ieee'
+import * as harvard from '@citestyle/styles/harvard'
+import * as vancouver from '@citestyle/styles/vancouver'
+import { toCslJson } from '../normalize.js'
 
-import { formatApa } from './apa.js'
-import { formatMla } from './mla.js'
-import { formatChicago } from './chicago.js'
-import { formatIeee } from './ieee.js'
+/**
+ * Compiled styles keyed by short name.
+ * Each value is a compiled style module with bibliography(), citation(), meta.
+ */
+export const compiledStyles = {
+  apa,
+  mla,
+  chicago: chicagoAD,
+  ieee,
+  harvard,
+  vancouver,
+}
 
 /**
- * Available citation style formatters
+ * Human-readable labels for each style.
  */
-export const formatters = {
-  apa: formatApa,
-  mla: formatMla,
-  chicago: formatChicago,
-  ieee: formatIeee,
+const styleLabels = {
+  apa: 'APA (7th ed.)',
+  mla: 'MLA (9th ed.)',
+  chicago: 'Chicago (Author-Date)',
+  ieee: 'IEEE',
+  harvard: 'Harvard',
+  vancouver: 'Vancouver',
 }
 
 /**
- * Format a reference in a specific style
+ * Format a reference in a specific citation style.
+ *
+ * Accepts Scholar-shaped publication objects OR CSL-JSON items.
+ * Returns structured output from @citestyle — { html, text, parts, links }.
  *
- * @param {Object} publication - Publication data
+ * @param {Object} publication - Publication data (Scholar or CSL-JSON)
  * @param {Object} [options]
- * @param {string} [options.style='apa'] - Citation style (apa, mla, chicago, ieee)
- * @returns {string} Formatted reference string
+ * @param {string} [options.style='apa'] - Citation style name
+ * @returns {{ html: string, text: string, parts: Object, links: Object }}
  *
  * @example
- * const ref = formatReference({
+ * const entry = formatReference({
  *   type: 'article',
  *   authors: [{ family: 'Smith', given: 'John' }],
  *   year: 2024,
@@ -43,14 +62,34 @@ export const formatters = {
  *   pages: '1-10',
  *   doi: '10.1234/example'
  * }, { style: 'apa' })
+ *
+ * entry.text  // "Smith, J. (2024). A Study of Something. ..."
+ * entry.html  // "<span class=\"csl-entry\">Smith, J. (2024)..."
  */
 export function formatReference(publication, options = {}) {
   const { style = 'apa' } = options
 
-  const formatter = formatters[style.toLowerCase()]
-  if (!formatter) {
-    throw new Error(`Unknown citation style: ${style}. Available: ${Object.keys(formatters).join(', ')}`)
+  const compiled = compiledStyles[style.toLowerCase()]
+  if (!compiled) {
+    throw new Error(
+      `Unknown citation style: ${style}. Available: ${Object.keys(compiledStyles).join(', ')}`
+    )
   }
 
-  return formatter(publication, options)
+  const item = toCslJson(publication)
+  return compiled.bibliography(item, {})
+}
+
+/**
+ * Get metadata for all available citation styles.
+ * Useful for building UI style pickers.
+ *
+ * @returns {Array<{ id: string, label: string, class: string }>}
+ */
+export function getAvailableStyles() {
+  return Object.entries(compiledStyles).map(([id, style]) => ({
+    id,
+    label: styleLabels[id] || style.meta?.title || id,
+    class: style.meta?.class || 'in-text',
+  }))
 }

package/src/bibliography/index.js

@@ -1,42 +1,21 @@
 /**
  * Bibliography Module
  *
- * Utilities for formatting bibliographic references in various citation styles.
+ * Reference formatting powered by @citestyle/* compiled styles,
+ * BibTeX parsing and export, and data normalization utilities.
  *
  * @module @uniweb/scholar/bibliography
  */
 
-// Formatters
+// Formatters — citestyle-powered
 export {
   formatReference,
-  formatApa,
-  formatMla,
-  formatChicago,
-  formatIeee,
-  formatters,
+  getAvailableStyles,
+  compiledStyles,
 } from './formatters/index.js'
 
-// Parsers
+// Parsers — delegated to @citestyle/bibtex
 export { parseBibtex, exportBibtex } from './parsers/index.js'
 
-// Utilities
-export {
-  formatAuthors,
-  parseAuthorName,
-  parseAuthorString,
-  getInitials,
-  formatApaAuthors,
-  formatMlaAuthors,
-  formatChicagoAuthors,
-  formatIeeeAuthors,
-} from './utils/authors.js'
-
-export {
-  formatDate,
-  parseDate,
-  getYear,
-  formatApaDate,
-  formatMlaDate,
-  formatChicagoDate,
-  formatIeeeDate,
-} from './utils/dates.js'
+// Normalization — Scholar ↔ CSL-JSON bridge
+export { toCslJson, fromCslJson, mapType, unmapType } from './normalize.js'

package/src/bibliography/normalize.js

@@ -0,0 +1,234 @@
+/**
+ * Data Normalization Layer
+ *
+ * Bidirectional bridge between Scholar's publication objects (BibTeX-style
+ * field names) and CSL-JSON items (the format @citestyle/* expects).
+ *
+ * @module @uniweb/scholar/bibliography/normalize
+ */
+
+// Scholar type → CSL-JSON type
+const TYPE_TO_CSL = {
+  article: 'article-journal',
+  journal: 'article-journal',
+  book: 'book',
+  inbook: 'chapter',
+  incollection: 'chapter',
+  chapter: 'chapter',
+  inproceedings: 'paper-conference',
+  conference: 'paper-conference',
+  webpage: 'webpage',
+  website: 'webpage',
+  online: 'webpage',
+  thesis: 'thesis',
+  phdthesis: 'thesis',
+  mastersthesis: 'thesis',
+  report: 'report',
+  techreport: 'report',
+  misc: 'article', // sensible default
+}
+
+// CSL-JSON type → Scholar type (reverse mapping, picks first match)
+const TYPE_FROM_CSL = {
+  'article-journal': 'article',
+  book: 'book',
+  chapter: 'incollection',
+  'paper-conference': 'inproceedings',
+  webpage: 'webpage',
+  thesis: 'thesis',
+  report: 'report',
+  article: 'article',
+}
+
+/**
+ * Map a Scholar entry type to a CSL-JSON type.
+ *
+ * @param {string} scholarType
+ * @returns {string}
+ */
+export function mapType(scholarType) {
+  if (!scholarType) return 'article-journal'
+  return TYPE_TO_CSL[scholarType.toLowerCase()] || 'article-journal'
+}
+
+/**
+ * Map a CSL-JSON type back to a Scholar entry type.
+ *
+ * @param {string} cslType
+ * @returns {string}
+ */
+export function unmapType(cslType) {
+  if (!cslType) return 'article'
+  return TYPE_FROM_CSL[cslType] || cslType
+}
+
+/**
+ * Convert a Scholar publication object to a CSL-JSON item.
+ *
+ * Scholar uses BibTeX-style field names (`authors`, `journal`, `year`).
+ * Citestyle expects CSL-JSON (`author`, `container-title`, `issued`).
+ *
+ * @param {Object} pub - Scholar publication object
+ * @returns {Object} CSL-JSON item
+ */
+export function toCslJson(pub) {
+  if (!pub) return {}
+
+  // If it already looks like CSL-JSON (has `issued` or `container-title`),
+  // pass through with minimal normalization
+  if (pub.issued || pub['container-title']) {
+    return { id: pub.id || pub.citationKey || 'unknown', ...pub }
+  }
+
+  const item = {
+    id: pub.id || pub.citationKey || 'unknown',
+    type: mapType(pub.type),
+  }
+
+  // Authors — Scholar uses `authors` (array), CSL-JSON uses `author`
+  if (pub.authors?.length) {
+    item.author = pub.authors.map(normalizeName)
+  } else if (pub.author) {
+    // Already CSL-JSON shape
+    item.author = Array.isArray(pub.author)
+      ? pub.author.map(normalizeName)
+      : undefined
+  }
+
+  // Editors
+  if (pub.editors?.length) {
+    item.editor = pub.editors.map(normalizeName)
+  }
+
+  // Title
+  if (pub.title) item.title = pub.title
+
+  // Container title — Scholar uses `journal` or `bookTitle`
+  const container = pub.journal || pub.bookTitle || pub.containerTitle
+  if (container) item['container-title'] = container
+
+  // Date — Scholar uses `year` (number), CSL-JSON uses `issued`
+  if (pub.year) {
+    item.issued = { 'date-parts': [[Number(pub.year)]] }
+  } else if (pub.date) {
+    // Try to parse an ISO date string
+    const parts = String(pub.date).split('-').map(Number)
+    item.issued = { 'date-parts': [parts.filter((n) => !isNaN(n))] }
+  }
+
+  // Standard fields
+  if (pub.volume) item.volume = String(pub.volume)
+  if (pub.issue) item.issue = String(pub.issue)
+  if (pub.pages) item.page = pub.pages.replace('–', '-')
+  if (pub.page) item.page = pub.page
+  if (pub.doi) item.DOI = pub.doi.replace(/^https?:\/\/doi\.org\//, '')
+  if (pub.DOI) item.DOI = pub.DOI
+  if (pub.url) item.URL = pub.url
+  if (pub.URL) item.URL = pub.URL
+  if (pub.publisher) item.publisher = pub.publisher
+  if (pub.isbn) item.ISBN = pub.isbn
+  if (pub.issn) item.ISSN = pub.issn
+  if (pub.abstract) item.abstract = pub.abstract
+  if (pub.edition) item.edition = pub.edition
+
+  // Thesis-specific
+  if (pub.school || pub.institution) {
+    item.publisher = pub.school || pub.institution
+  }
+
+  return item
+}
+
+/**
+ * Convert a CSL-JSON item to a Scholar publication object.
+ *
+ * Used for backward compatibility when components expect Scholar-shaped
+ * objects (`pub.authors`, `pub.journal`, `pub.year`).
+ *
+ * @param {Object} item - CSL-JSON item
+ * @returns {Object} Scholar publication object
+ */
+export function fromCslJson(item) {
+  if (!item) return {}
+
+  const pub = {
+    id: item.id,
+    type: unmapType(item.type),
+  }
+
+  // Authors
+  if (item.author?.length) {
+    pub.authors = item.author.map((a) => ({
+      family: a.family || '',
+      given: a.given || '',
+      ...(a.suffix ? { suffix: a.suffix } : {}),
+    }))
+  }
+
+  // Editors
+  if (item.editor?.length) {
+    pub.editors = item.editor.map((a) => ({
+      family: a.family || '',
+      given: a.given || '',
+    }))
+  }
+
+  // Title
+  if (item.title) pub.title = item.title
+
+  // Container title → journal or bookTitle
+  if (item['container-title']) {
+    if (pub.type === 'article' || pub.type === 'journal') {
+      pub.journal = item['container-title']
+    } else {
+      pub.bookTitle = item['container-title']
+    }
+  }
+
+  // Date
+  if (item.issued?.['date-parts']?.[0]) {
+    pub.year = item.issued['date-parts'][0][0]
+  }
+
+  // Standard fields
+  if (item.volume) pub.volume = item.volume
+  if (item.issue) pub.issue = item.issue
+  if (item.page) pub.pages = item.page
+  if (item.DOI) pub.doi = item.DOI
+  if (item.URL) pub.url = item.URL
+  if (item.publisher) pub.publisher = item.publisher
+  if (item.ISBN) pub.isbn = item.ISBN
+  if (item.ISSN) pub.issn = item.ISSN
+  if (item.abstract) pub.abstract = item.abstract
+  if (item.edition) pub.edition = item.edition
+
+  return pub
+}
+
+/**
+ * Normalize a name object — ensures {family, given} shape.
+ * Handles strings, objects with various key patterns.
+ *
+ * @param {Object|string} name
+ * @returns {{ family: string, given: string, suffix?: string }}
+ */
+function normalizeName(name) {
+  if (typeof name === 'string') {
+    // "Last, First" or "First Last"
+    if (name.includes(',')) {
+      const [family, given] = name.split(',').map((s) => s.trim())
+      return { family, given }
+    }
+    const parts = name.trim().split(/\s+/)
+    return {
+      family: parts[parts.length - 1],
+      given: parts.slice(0, -1).join(' '),
+    }
+  }
+
+  return {
+    family: name.family || name.lastName || '',
+    given: name.given || name.firstName || '',
+    ...(name.suffix ? { suffix: name.suffix } : {}),
+  }
+}

package/src/bibliography/parsers/index.js

@@ -1,7 +1,41 @@
 /**
  * Bibliography Parsers
  *
+ * Delegates to @citestyle/bibtex for BibTeX parsing and export.
+ * Returns CSL-JSON items directly — no scholar-shaped wrapper.
+ *
  * @module @uniweb/scholar/bibliography/parsers
  */
 
-export { parseBibtex, exportBibtex } from './bibtex.js'
+import {
+  parseBibtex as csParseBibtex,
+  exportBibtex as csExportBibtex,
+} from '@citestyle/bibtex'
+import { toCslJson } from '../normalize.js'
+
+/**
+ * Parse a BibTeX string into an array of CSL-JSON items.
+ *
+ * @param {string} bibtex - BibTeX source string
+ * @returns {Array<Object>} Array of CSL-JSON items
+ */
+export const parseBibtex = csParseBibtex
+
+/**
+ * Export a single publication (Scholar or CSL-JSON) to BibTeX format.
+ *
+ * Wraps @citestyle/bibtex's exportBibtex, which expects an array of
+ * CSL-JSON items. This accepts a single Scholar-shaped pub for convenience.
+ *
+ * @param {Object} publication - Publication data (Scholar or CSL-JSON)
+ * @returns {string} BibTeX string
+ */
+export function exportBibtex(publication) {
+  if (!publication) return ''
+
+  // If it's a string, it's already BibTeX — pass through
+  if (typeof publication === 'string') return publication
+
+  const item = toCslJson(publication)
+  return csExportBibtex([item])
+}

package/src/citations/Bibliography.jsx

@@ -1,69 +1,49 @@
 /**
  * Bibliography Component
  *
- * Renders a formatted list of references that have been cited in the document.
+ * Renders a formatted list of references using @citestyle/registry.
+ * The registry handles sorting, year-suffix disambiguation, and
+ * subsequent-author-substitute (em-dash for repeated authors).
  *
  * @module @uniweb/scholar/citations/Bibliography
  */
 
 import React, { useMemo } from 'react'
 import { useCitation } from './CitationProvider.jsx'
-import { formatReference } from '../bibliography/formatters/index.js'
 
 /**
- * Bibliography - Renders the list of cited references
+ * Bibliography - Renders the list of references
  *
  * @param {Object} props
  * @param {string} [props.title='References'] - Section title
  * @param {boolean} [props.showTitle=true] - Whether to show the title
- * @param {boolean} [props.showAll=false] - Show all references, not just cited ones
  * @param {string} [props.className] - Additional CSS classes
  * @param {string} [props.itemClassName] - CSS classes for each item
  *
  * @example
  * <Bibliography title="Works Cited" />
- *
- * @example
- * // Show all references including uncited ones
- * <Bibliography showAll />
  */
 export function Bibliography({
   title = 'References',
   showTitle = true,
-  showAll = false,
   className,
   itemClassName,
   ...props
 }) {
-  const { getCitedReferences, references, style, cited } = useCitation()
-
-  // Get references to display
-  const refsToShow = useMemo(() => {
-    if (showAll) {
-      return references
-    }
-    return getCitedReferences()
-  }, [showAll, references, getCitedReferences])
+  const { getBibliography, styleMeta } = useCitation()
 
-  // Format references
-  const formattedRefs = useMemo(() => {
-    return refsToShow.map((ref) => {
-      const number = cited.get(ref.id) || cited.get(ref.citationKey)
-      return {
-        id: ref.id || ref.citationKey,
-        number,
-        formatted: formatReference(ref, { style }),
-        reference: ref,
-      }
-    })
-  }, [refsToShow, style, cited])
+  // Get the fully formatted bibliography from the registry.
+  // The registry applies: sorting, subsequent-author-substitute,
+  // year-suffix disambiguation, and citation numbering.
+  const entries = useMemo(() => getBibliography(), [getBibliography])
 
-  if (!formattedRefs.length) {
+  if (!entries.length) {
     return null
   }
 
-  // Use numbered list for IEEE style
-  const isNumeric = style === 'ieee'
+  // Use numbered list for numeric styles (IEEE, Vancouver, etc.)
+  const isNumeric = styleMeta?.class === 'note' ||
+    styleMeta?.collapse === 'citation-number'
 
   return (
     <section className={className} {...props}>
@@ -87,38 +67,30 @@ export function Bibliography({
             lineHeight: '1.8',
           }}
         >
-          {formattedRefs.map((ref) => (
+          {entries.map((entry, i) => (
             <li
-              key={ref.id}
-              id={`ref-${ref.id}`}
+              key={entry.parts?.id || i}
+              id={`ref-${entry.parts?.id || i}`}
               className={itemClassName}
-              style={{
-                marginBottom: '0.75rem',
-              }}
-            >
-              {ref.formatted}
-            </li>
+              style={{ marginBottom: '0.75rem' }}
+              dangerouslySetInnerHTML={{ __html: entry.html }}
+            />
           ))}
         </ol>
       ) : (
-        <div
-          style={{
-            lineHeight: '1.8',
-          }}
-        >
-          {formattedRefs.map((ref) => (
-            <p
-              key={ref.id}
-              id={`ref-${ref.id}`}
+        <div style={{ lineHeight: '1.8' }}>
+          {entries.map((entry, i) => (
+            <div
+              key={entry.parts?.id || i}
+              id={`ref-${entry.parts?.id || i}`}
               className={itemClassName}
               style={{
                 marginBottom: '0.75rem',
                 paddingLeft: '2rem',
                 textIndent: '-2rem',
               }}
-            >
-              {ref.formatted}
-            </p>
+              dangerouslySetInnerHTML={{ __html: entry.html }}
+            />
           ))}
         </div>
       )}