@uniweb/scholar 0.2.0 → 0.2.2

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

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 (