@uniweb/scholar 0.2.0 → 0.2.2

package/README.md

@@ -12,28 +12,21 @@ pnpm add @uniweb/scholar
 
 ## Features
 
-- **Math Rendering** - LaTeX equations with KaTeX (lazy-loaded)
+- **Numbered Equations** - Cross-referenceable display equations
 - **Bibliography** - Format references in APA, MLA, Chicago, and IEEE styles
 - **Citations** - Track inline citations with automatic bibliography generation
 - **BibTeX** - Parse and export BibTeX format
 - **UI Components** - Ready-to-use citation buttons, author lists, and DOI links
 
+> **Plain LaTeX math** (inline `$x$`, display `$$x$$`, fenced ```` ```math ````) is handled by Uniweb's content pipeline — the markdown parser compiles LaTeX to MathML Core at build time and the browser renders it natively. No runtime math library needed; no `<Math>` component required.
+
 ## Quick Start
 
-### Math Equations
+### Numbered Equations
 
 ```jsx
-import { Math, Equation, EquationRef, EquationProvider } from '@uniweb/scholar/math'
-
-// Inline math
-<p>The equation <Math>E = mc^2</Math> shows mass-energy equivalence.</p>
+import { Equation, EquationRef, EquationProvider } from '@uniweb/scholar/math'
 
-// Display (block) math
-<Math display>
-  \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
-</Math>
-
-// Numbered equations with cross-references
 <EquationProvider>
   <Equation id="einstein">E = mc^2</Equation>
   <p>As shown in <EquationRef id="einstein" />, energy equals mass times the speed of light squared.</p>
@@ -97,29 +90,49 @@ const bibtex = `
 
 ### Math Module
 
-#### `<Math>`
+Scholar does not ship a math renderer. Plain LaTeX in markdown is compiled to MathML by Uniweb's content pipeline and rendered natively by the browser — see the framework docs for the `$x$`, `$$x$$`, and ```math fence syntax.
 
-Renders inline or display LaTeX math.
+`<Equation>` and `<EquationRef>` cover the distinct feature of **numbered cross-referenceable equations**. They consume pre-compiled MathML from `content.math` and are fully SSR-safe.
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `string` | - | LaTeX expression |
-| `display` | `boolean` | `false` | Display mode (block) vs inline |
-| `className` | `string` | - | CSS classes |
+Label an equation in markdown with a `:<id>` suffix on the fence:
+
+````markdown
+```math:einstein
+E = mc^2
+```
+````
+
+Then in a foundation's section component:
+
+```jsx
+import { Equation, EquationProvider, EquationRef } from '@uniweb/scholar/math'
+
+function MyBlock({ content }) {
+  return (
+    <EquationProvider>
+      {content.math?.filter(m => m.id).map(m => (
+        <Equation key={m.id} id={m.id} mathml={m.mathml} />
+      ))}
+      <p>As shown in <EquationRef id="einstein" />, energy equals mc².</p>
+    </EquationProvider>
+  )
+}
+```
 
 #### `<Equation>`
 
-Renders a numbered equation with optional label.
+Numbered display equation rendered from pre-compiled MathML.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children` | `string` | - | LaTeX expression |
-| `id` | `string` | auto | Unique ID for cross-referencing |
-| `label` | `string` | - | Custom label (defaults to number) |
+| `id` | `string` | auto | Identifier for cross-referencing |
+| `mathml` | `string` | - | Pre-compiled MathML from `content.math[i].mathml` |
+| `label` | `string` | - | Override the auto-number with a custom label |
+| `className` | `string` | - | CSS classes on the wrapper |
 
 #### `<EquationRef>`
 
-Creates a reference link to a numbered equation.
+Link to a numbered equation within the same `<EquationProvider>`.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -128,7 +141,7 @@ Creates a reference link to a numbered equation.
 
 #### `<EquationProvider>`
 
-Context provider for equation numbering. Wrap content containing equations.
+Context provider for equation numbering. Wrap content containing equations and their references.
 
 ### Citations Module
 
@@ -280,17 +293,14 @@ import { DoiLink } from '@uniweb/scholar/components'
 
 ## Bundle Size
 
-The package uses lazy loading to minimize initial bundle size:
+Scholar ships no math renderer — MathML is pre-compiled upstream and rendered natively by the browser. Approximate subpath sizes:
 
 | Module | Size |
 |--------|------|
 | bibliography (formatters, parsers) | ~15KB |
-| math (without KaTeX) | ~5KB |
-| KaTeX (lazy-loaded on first use) | ~90KB |
-| citations | ~10KB |
-| components | ~8KB |
-
-KaTeX CSS is automatically injected when math rendering is first used.
+| math (numbered equations, refs)    | ~5KB  |
+| citations                          | ~10KB |
+| components                         | ~8KB  |
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uniweb/scholar",
-  "version": "0.2.0",
-  "description": "Academic content utilities for Uniweb - math rendering, bibliographic references, and inline citations",
+  "version": "0.2.2",
+  "description": "Academic content utilities for Uniweb - numbered equations with cross-references, bibliographic references, and inline citations",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
@@ -18,9 +18,8 @@
     "uniweb",
     "scholar",
     "academic",
-    "math",
-    "katex",
-    "latex",
+    "equations",
+    "mathml",
     "bibliography",
     "citations",
     "bibtex",
@@ -41,9 +40,23 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "katex": "^0.16.0"
+    "@citestyle/bibtex": "^1.0.0",
+    "@citestyle/core": "^1.0.0",
+    "@citestyle/registry": "^1.0.0",
+    "@citestyle/styles": "^1.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "jsdom": "^25.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

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])
+}