@uniweb/scholar 0.2.0 → 0.2.1

package/src/citations/Citation.jsx

@@ -1,44 +1,15 @@
 /**
  * Citation Component
  *
- * Renders an inline citation that links to the bibliography.
+ * Renders an inline citation using @citestyle/registry for proper
+ * author-date formatting, year-suffix disambiguation, numeric citations,
+ * and cite collapsing.
  *
  * @module @uniweb/scholar/citations/Citation
  */
 
 import React, { useMemo } from 'react'
 import { useCitation } from './CitationProvider.jsx'
-import { getYear } from '../bibliography/utils/dates.js'
-
-/**
- * Format author names for inline citation
- *
- * @param {Array} authors - Array of author objects
- * @param {string} style - Citation style
- * @returns {string}
- */
-function formatInlineAuthors(authors, style) {
-  if (!authors?.length) return ''
-
-  const getName = (a) => {
-    if (typeof a === 'string') return a.split(',')[0].trim()
-    return a.family || a.lastName || ''
-  }
-
-  if (authors.length === 1) {
-    return getName(authors[0])
-  }
-
-  if (authors.length === 2) {
-    if (style === 'apa') {
-      return `${getName(authors[0])} & ${getName(authors[1])}`
-    }
-    return `${getName(authors[0])} and ${getName(authors[1])}`
-  }
-
-  // 3+ authors
-  return `${getName(authors[0])} et al.`
-}
 
 /**
  * Citation - Inline citation component
@@ -46,11 +17,10 @@ function formatInlineAuthors(authors, style) {
  * @param {Object} props
  * @param {string} [props.id] - Single reference ID to cite
  * @param {Array<string>} [props.ids] - Multiple reference IDs to cite
- * @param {string} [props.page] - Page number(s)
+ * @param {string} [props.locator] - Page, chapter, or other locator
+ * @param {string} [props.label] - Locator label (e.g., 'page', 'chapter')
  * @param {string} [props.prefix] - Text before citation (e.g., "see")
  * @param {string} [props.suffix] - Text after citation
- * @param {boolean} [props.suppressAuthor] - Show only year (for narrative citations)
- * @param {string} [props.format='parenthetical'] - Format: 'parenthetical', 'narrative', or 'numeric'
  * @param {string} [props.className] - Additional CSS classes
  *
  * @example
@@ -58,138 +28,58 @@ function formatInlineAuthors(authors, style) {
  * <Citation id="smith2024" />
  *
  * @example
- * // Narrative citation: Smith (2024)
- * <Citation id="smith2024" format="narrative" />
- *
- * @example
- * // With page number: (Smith, 2024, p. 42)
- * <Citation id="smith2024" page="42" />
+ * // With page locator: (Smith, 2024, p. 42)
+ * <Citation id="smith2024" locator="42" label="page" />
  *
  * @example
  * // Multiple sources: (Smith, 2024; Jones, 2023)
  * <Citation ids={['smith2024', 'jones2023']} />
  *
  * @example
- * // IEEE-style numeric: [1]
- * <Citation id="smith2024" format="numeric" />
+ * // With prefix: (see Smith, 2024)
+ * <Citation id="smith2024" prefix="see" />
  */
 export function Citation({
   id,
   ids,
-  page,
+  locator,
+  label = 'page',
   prefix,
   suffix,
-  suppressAuthor = false,
-  format = 'parenthetical',
   className,
   ...props
 }) {
-  const { cite, getReference, style } = useCitation()
-
-  // Get all IDs to cite
-  const allIds = useMemo(() => {
-    if (ids?.length) return ids
-    if (id) return [id]
-    return []
-  }, [id, ids])
-
-  // Cite all references and get their info
-  const citations = useMemo(() => {
-    return allIds.map((refId) => {
-      const number = cite(refId)
-      const reference = getReference(refId)
-      return { id: refId, number, reference }
-    })
-  }, [allIds, cite, getReference])
-
-  // Format the citation text
-  const citationText = useMemo(() => {
-    if (!citations.length) return '??'
-
-    // Numeric format (IEEE style)
-    if (format === 'numeric' || style === 'ieee') {
-      const numbers = citations.map((c) => c.number).join(', ')
-      return `[${numbers}]`
-    }
-
-    // Author-date formats
-    const parts = citations.map((c) => {
-      if (!c.reference) return c.id
-
-      const authors = c.reference.authors || []
-      const year = getYear(c.reference.year || c.reference.date)
-      const authorStr = formatInlineAuthors(authors, style)
-
-      if (suppressAuthor) {
-        return year || 'n.d.'
-      }
-
-      if (!year) {
-        return authorStr || c.id
-      }
-
-      return `${authorStr}, ${year}`
-    })
-
-    let text = parts.join('; ')
-
-    // Add page number
-    if (page) {
-      const pagePrefix = page.includes('-') || page.includes('–') ? 'pp.' : 'p.'
-      text += `, ${pagePrefix} ${page}`
-    }
-
-    // Add prefix/suffix
-    if (prefix) text = `${prefix} ${text}`
-    if (suffix) text = `${text}, ${suffix}`
-
-    // Wrap in parentheses for parenthetical format
-    if (format === 'parenthetical') {
-      return `(${text})`
-    }
-
-    return text
-  }, [citations, format, style, suppressAuthor, page, prefix, suffix])
-
-  // For narrative format, we need to split author and year
-  if (format === 'narrative' && citations.length === 1 && citations[0].reference) {
-    const c = citations[0]
-    const authors = c.reference.authors || []
-    const year = getYear(c.reference.year || c.reference.date)
-    const authorStr = formatInlineAuthors(authors, style)
-
-    let yearPart = year || 'n.d.'
-    if (page) {
-      const pagePrefix = page.includes('-') || page.includes('–') ? 'pp.' : 'p.'
-      yearPart += `, ${pagePrefix} ${page}`
-    }
-
-    return (
-      <span className={className} {...props}>
-        {prefix && `${prefix} `}
-        {authorStr}{' '}
-        <a
-          href={`#ref-${c.id}`}
-          style={{ textDecoration: 'none' }}
-        >
-          ({yearPart})
-        </a>
-        {suffix && ` ${suffix}`}
-      </span>
-    )
-  }
+  const { cite } = useCitation()
+
+  // Build cite references array
+  const citeRefs = useMemo(() => {
+    const allIds = ids?.length ? ids : id ? [id] : []
+    return allIds.map((refId, i) => ({
+      id: refId,
+      // Only the first cite gets the locator/prefix/suffix
+      ...(i === 0 && locator ? { locator, label } : {}),
+      ...(i === 0 && prefix ? { prefix } : {}),
+      ...(i === allIds.length - 1 && suffix ? { suffix } : {}),
+    }))
+  }, [id, ids, locator, label, prefix, suffix])
+
+  // Format through the registry — handles disambiguation, collapsing, numbering
+  const result = useMemo(() => {
+    if (!citeRefs.length) return { text: '??', html: '??' }
+    return cite(citeRefs)
+  }, [citeRefs, cite])
+
+  // Link to bibliography entry
+  const firstId = citeRefs[0]?.id
 
-  // Single link for all citations
-  const firstId = citations[0]?.id
   return (
     <a
       href={firstId ? `#ref-${firstId}` : undefined}
       className={className}
       style={{ textDecoration: 'none' }}
+      dangerouslySetInnerHTML={{ __html: result.html }}
       {...props}
-    >
-      {citationText}
-    </a>
+    />
   )
 }
 

package/src/citations/CitationProvider.jsx

@@ -1,14 +1,18 @@
 /**
  * Citation Provider Component
  *
- * Provides context for managing citations throughout a document.
- * Tracks which references have been cited and their order.
+ * Provides citation context powered by @citestyle/registry.
+ * Handles year-suffix disambiguation, bibliography sorting, cite collapsing,
+ * and numeric citation numbering — all automatically.
  *
  * @module @uniweb/scholar/citations/CitationProvider
  */
 
-import React, { createContext, useContext, useState, useMemo, useCallback } from 'react'
-import { parseBibtex } from '../bibliography/parsers/bibtex.js'
+import React, { createContext, useContext, useMemo, useCallback } from 'react'
+import { createRegistry } from '@citestyle/registry'
+import { parseBibtex } from '../bibliography/parsers/index.js'
+import { compiledStyles } from '../bibliography/formatters/index.js'
+import { toCslJson } from '../bibliography/normalize.js'
 
 /**
  * Citation context
@@ -18,7 +22,15 @@ export const CitationContext = createContext(null)
 /**
  * Hook to access citation context
  *
- * @returns {{ cite: Function, getCitation: Function, references: Array, style: string, cited: Map }}
+ * @returns {{
+ *   registry: Object,
+ *   cite: Function,
+ *   getBibliography: Function,
+ *   getReference: Function,
+ *   references: Array,
+ *   style: string,
+ *   styleMeta: Object
+ * }}
  */
 export function useCitation() {
   const ctx = useContext(CitationContext)
@@ -28,113 +40,99 @@ export function useCitation() {
   return ctx
 }
 
+/**
+ * Normalize references to CSL-JSON items.
+ * Accepts: BibTeX string, array of Scholar pubs, array of CSL-JSON items.
+ */
+function normalizeReferences(references) {
+  if (!references) return []
+
+  // BibTeX string → parse to CSL-JSON
+  if (typeof references === 'string') {
+    return parseBibtex(references)
+  }
+
+  if (!Array.isArray(references)) return []
+
+  // Detect if items are already CSL-JSON (have `issued` or `container-title`)
+  // or Scholar-shaped (have `authors`, `journal`, `year` as number)
+  return references.map((ref) => {
+    if (ref.issued || ref['container-title'] || ref['date-parts']) {
+      // Already CSL-JSON — ensure it has an id
+      return { id: ref.id || ref.citationKey || 'unknown', ...ref }
+    }
+    // Scholar-shaped → convert
+    return toCslJson(ref)
+  })
+}
+
 /**
  * CitationProvider - Manages citation state for a document
  *
+ * Uses @citestyle/registry for proper disambiguation, sorting, and numbering.
+ *
  * @param {Object} props
- * @param {Array|string} props.references - Array of reference objects or BibTeX string
- * @param {string} [props.style='apa'] - Citation style (apa, mla, chicago, ieee)
+ * @param {Array|string} props.references - Array of publications (Scholar or CSL-JSON) or BibTeX string
+ * @param {string} [props.style='apa'] - Citation style name
  * @param {React.ReactNode} props.children
  *
  * @example
- * <CitationProvider references={refs} style="apa">
+ * <CitationProvider references={pubs} style="apa">
  *   <p>According to <Citation id="smith2024" />, this is true.</p>
  *   <Bibliography />
  * </CitationProvider>
  */
 export function CitationProvider({ references, style = 'apa', children }) {
-  // Track cited references in order
-  const [cited, setCited] = useState(new Map())
-
-  // Parse references if BibTeX string
-  const refs = useMemo(() => {
-    if (!references) return []
-    if (typeof references === 'string') {
-      return parseBibtex(references)
-    }
-    if (Array.isArray(references)) {
-      return references
+  // Resolve compiled style
+  const compiled = useMemo(
+    () => compiledStyles[style.toLowerCase()] || compiledStyles.apa,
+    [style]
+  )
+
+  // Normalize all references to CSL-JSON
+  const cslItems = useMemo(
+    () => normalizeReferences(references),
+    [references]
+  )
+
+  // Create registry — handles disambiguation, sorting, numbering
+  const registry = useMemo(() => {
+    const reg = createRegistry(compiled)
+    if (cslItems.length) {
+      reg.addItems(cslItems)
     }
-    return []
-  }, [references])
-
-  // Create a lookup map by id
-  const refsById = useMemo(() => {
-    const map = new Map()
-    refs.forEach((ref) => {
-      if (ref.id) map.set(ref.id, ref)
-      if (ref.citationKey) map.set(ref.citationKey, ref)
-    })
-    return map
-  }, [refs])
-
-  /**
-   * Cite a reference by id
-   * Returns the citation number (order in which it was first cited)
-   */
+    return reg
+  }, [compiled, cslItems])
+
+  // Convenience: format an inline citation cluster
   const cite = useCallback(
-    (id) => {
-      // Check if already cited
-      if (cited.has(id)) {
-        return cited.get(id)
-      }
-
-      // Add to cited list
-      const number = cited.size + 1
-      setCited((prev) => {
-        if (prev.has(id)) return prev
-        const next = new Map(prev)
-        next.set(id, number)
-        return next
-      })
-
-      return number
-    },
-    [cited]
+    (cites, ctx) => registry.cite(cites, ctx),
+    [registry]
   )
 
-  /**
-   * Get citation info without citing
-   */
-  const getCitation = useCallback(
-    (id) => {
-      return {
-        number: cited.get(id),
-        reference: refsById.get(id),
-        isCited: cited.has(id),
-      }
-    },
-    [cited, refsById]
+  // Convenience: get the full formatted bibliography
+  const getBibliography = useCallback(
+    (ctx) => registry.getBibliography(ctx),
+    [registry]
   )
 
-  /**
-   * Get reference by id
-   */
+  // Look up a CSL-JSON item by id
   const getReference = useCallback(
-    (id) => refsById.get(id),
-    [refsById]
+    (id) => registry.getItem(id),
+    [registry]
   )
 
-  /**
-   * Get all cited references in citation order
-   */
-  const getCitedReferences = useCallback(() => {
-    const sorted = Array.from(cited.entries()).sort((a, b) => a[1] - b[1])
-    return sorted.map(([id]) => refsById.get(id)).filter(Boolean)
-  }, [cited, refsById])
-
   const value = useMemo(
     () => ({
+      registry,
       cite,
-      getCitation,
+      getBibliography,
       getReference,
-      getCitedReferences,
-      references: refs,
-      refsById,
+      references: cslItems,
       style,
-      cited,
+      styleMeta: compiled.meta,
     }),
-    [cite, getCitation, getReference, getCitedReferences, refs, refsById, style, cited]
+    [registry, cite, getBibliography, getReference, cslItems, style, compiled]
   )
 
   return (

package/src/components/AuthorList.jsx

@@ -2,15 +2,66 @@
  * AuthorList Component
  *
  * Renders a formatted list of authors with optional ORCID links.
+ * Works with both Scholar-shaped author objects and CSL-JSON name objects.
  *
  * @module @uniweb/scholar/components/AuthorList
  */
 
 import React from 'react'
-import { formatAuthors } from '../bibliography/utils/authors.js'
 
 /**
- * AuthorList - Formatted author names
+ * Format a single author name for display.
+ *
+ * @param {{ family: string, given?: string, suffix?: string }} author
+ * @param {boolean} invertFirst - Show as "Last, First" (true) or "First Last" (false)
+ * @returns {string}
+ */
+function formatName(author, invertFirst = false) {
+  if (typeof author === 'string') return author
+
+  const family = author.family || ''
+  const given = author.given || ''
+  const suffix = author.suffix ? `, ${author.suffix}` : ''
+
+  if (!given) return family + suffix
+
+  return invertFirst
+    ? `${family}${suffix}, ${given}`
+    : `${given} ${family}${suffix}`
+}
+
+/**
+ * Format an array of authors into a display string.
+ *
+ * @param {Array} authors - Author objects
+ * @param {Object} options
+ * @param {string} [options.style='apa']
+ * @returns {string}
+ */
+function formatAuthorsText(authors, { style = 'apa' } = {}) {
+  if (!authors?.length) return ''
+
+  const useAmpersand = style === 'apa'
+  const invertFirst = style === 'apa' || style === 'chicago' || style === 'mla'
+
+  if (authors.length === 1) {
+    return formatName(authors[0], invertFirst)
+  }
+
+  if (authors.length === 2) {
+    const sep = useAmpersand ? ' & ' : ' and '
+    return formatName(authors[0], invertFirst) + sep + formatName(authors[1])
+  }
+
+  // 3+ authors
+  const allButLast = authors.slice(0, -1).map((a, i) => formatName(a, i === 0 && invertFirst))
+  const last = formatName(authors[authors.length - 1])
+  const sep = useAmpersand ? ', & ' : ', and '
+  return allButLast.join(', ') + sep + last
+}
+
+/**
+ * AuthorList - Formatted author names with optional ORCID links
  *
  * @param {Object} props
  * @param {Array|string} props.authors - Authors array or string
@@ -21,9 +72,6 @@ import { formatAuthors } from '../bibliography/utils/authors.js'
  *
  * @example
  * <AuthorList authors={[{ family: 'Smith', given: 'John', orcid: '0000-0001-2345-6789' }]} />
- *
- * @example
- * <AuthorList authors="Smith, John and Doe, Jane" style="mla" />
  */
 export function AuthorList({
   authors,
@@ -33,71 +81,48 @@ export function AuthorList({
   className,
   ...props
 }) {
-  // If authors is a string, just format it
+  // String authors — just display
   if (typeof authors === 'string') {
     return (
       <span className={className} {...props}>
-        {formatAuthors(authors, { style })}
+        {authors}
       </span>
     )
   }
 
-  // If no array or empty, return nothing
-  if (!authors?.length) {
-    return null
-  }
+  if (!authors?.length) return null
 
-  // Check if any author has ORCID
+  // If no ORCID to show, use simple formatted string
   const hasOrcid = showOrcid && authors.some((a) => a.orcid)
 
-  // If no ORCID to show, use simple formatted string
   if (!hasOrcid) {
     return (
       <span className={className} {...props}>
-        {formatAuthors(authors, { style })}
+        {formatAuthorsText(authors, { style })}
       </span>
     )
   }
 
   // Render with ORCID links
+  const useAmpersand = style === 'apa'
+
   return (
     <span className={className} {...props}>
       {authors.map((author, index) => {
         const isLast = index === authors.length - 1
         const isSecondToLast = index === authors.length - 2
+        const isFirst = index === 0
+        const invertFirst = isFirst && (style === 'apa' || style === 'chicago' || style === 'mla')
 
-        // Format name based on style and position
-        let name
-        if (typeof author === 'string') {
-          name = author
-        } else {
-          const suffix = author.suffix ? `, ${author.suffix}` : ''
-          if (style === 'apa') {
-            // APA: Last, F.
-            const initials = author.given
-              ? author.given
-                  .split(/\s+/)
-                  .map((n) => `${n.charAt(0)}.`)
-                  .join(' ')
-              : ''
-            name = initials
-              ? `${author.family}${suffix}, ${initials}`
-              : author.family + suffix
-          } else {
-            // Default: First Last
-            name = author.given
-              ? `${author.given} ${author.family}${suffix}`
-              : author.family + suffix
-          }
-        }
+        const name = formatName(author, invertFirst)
 
         // Determine separator
         let sep = ''
         if (!isLast) {
           if (authors.length === 2) {
-            sep = style === 'apa' ? ' & ' : ' and '
+            sep = useAmpersand ? ' & ' : ' and '
           } else if (isSecondToLast) {
-            sep = style === 'apa' ? ', & ' : ', and '
+            sep = useAmpersand ? ', & ' : ', and '
           } else {
             sep = separator
           }

package/src/components/BibtexBlock.jsx

@@ -7,7 +7,7 @@
  */
 
 import React, { useState } from 'react'
-import { exportBibtex } from '../bibliography/parsers/bibtex.js'
+import { exportBibtex } from '../bibliography/parsers/index.js'
 
 /**
  * BibtexBlock - Display copyable BibTeX entry