@uniweb/scholar 0.1.0

package/src/bibliography/utils/authors.js

@@ -0,0 +1,277 @@
+/**
+ * Author Name Utilities
+ *
+ * Functions for parsing and formatting author names in various citation styles.
+ *
+ * @module @uniweb/scholar/bibliography/utils/authors
+ */
+
+/**
+ * Parse a single author name string into structured parts
+ *
+ * @param {string} name - Author name (e.g., "Smith, John A." or "John A. Smith")
+ * @returns {{ family: string, given: string, suffix?: string }}
+ */
+export function parseAuthorName(name) {
+  if (!name || typeof name !== 'string') {
+    return { family: '', given: '' }
+  }
+
+  const trimmed = name.trim()
+
+  // Check for "Last, First" format
+  if (trimmed.includes(',')) {
+    const parts = trimmed.split(',').map((p) => p.trim())
+    const family = parts[0]
+    const givenAndSuffix = parts.slice(1).join(' ').trim()
+
+    // Check for suffix (Jr., Sr., III, etc.)
+    const suffixMatch = givenAndSuffix.match(/\s+(Jr\.?|Sr\.?|III?|IV|V)$/i)
+    if (suffixMatch) {
+      return {
+        family,
+        given: givenAndSuffix.slice(0, suffixMatch.index).trim(),
+        suffix: suffixMatch[1],
+      }
+    }
+
+    return { family, given: givenAndSuffix }
+  }
+
+  // "First Last" format - last word is family name
+  const words = trimmed.split(/\s+/)
+  if (words.length === 1) {
+    return { family: words[0], given: '' }
+  }
+
+  // Check if last word is a suffix
+  const lastWord = words[words.length - 1]
+  if (/^(Jr\.?|Sr\.?|III?|IV|V)$/i.test(lastWord)) {
+    return {
+      family: words[words.length - 2] || '',
+      given: words.slice(0, -2).join(' '),
+      suffix: lastWord,
+    }
+  }
+
+  return {
+    family: words[words.length - 1],
+    given: words.slice(0, -1).join(' '),
+  }
+}
+
+/**
+ * Parse a string of multiple authors
+ *
+ * @param {string} authorString - Authors separated by "and", ";", or "&"
+ * @returns {Array<{ family: string, given: string, suffix?: string }>}
+ */
+export function parseAuthorString(authorString) {
+  if (!authorString || typeof authorString !== 'string') {
+    return []
+  }
+
+  // Split by "and", ";", or "&"
+  const authors = authorString
+    .split(/\s+and\s+|;\s*|&\s*/i)
+    .map((a) => a.trim())
+    .filter(Boolean)
+
+  return authors.map(parseAuthorName)
+}
+
+/**
+ * Get author initials
+ *
+ * @param {string} given - Given name(s)
+ * @param {Object} [options]
+ * @param {boolean} [options.periods=true] - Include periods after initials
+ * @param {boolean} [options.spaces=true] - Include spaces between initials
+ * @returns {string}
+ */
+export function getInitials(given, options = {}) {
+  const { periods = true, spaces = true } = options
+
+  if (!given) return ''
+
+  const names = given.split(/\s+/)
+  const initials = names
+    .map((name) => name.charAt(0).toUpperCase())
+    .map((initial) => (periods ? `${initial}.` : initial))
+
+  return initials.join(spaces ? ' ' : '')
+}
+
+/**
+ * Format authors for APA style
+ *
+ * @param {Array} authors - Array of parsed author objects
+ * @param {number} [maxAuthors=20] - Maximum authors before using et al.
+ * @returns {string}
+ */
+export function formatApaAuthors(authors, maxAuthors = 20) {
+  if (!authors?.length) return ''
+
+  const formatOne = (author) => {
+    const initials = getInitials(author.given, { periods: true, spaces: true })
+    const suffix = author.suffix ? `, ${author.suffix}` : ''
+    return initials
+      ? `${author.family}${suffix}, ${initials}`
+      : author.family + suffix
+  }
+
+  if (authors.length === 1) {
+    return formatOne(authors[0])
+  }
+
+  if (authors.length === 2) {
+    return `${formatOne(authors[0])} & ${formatOne(authors[1])}`
+  }
+
+  if (authors.length <= maxAuthors) {
+    const allButLast = authors.slice(0, -1).map(formatOne).join(', ')
+    return `${allButLast}, & ${formatOne(authors[authors.length - 1])}`
+  }
+
+  // More than maxAuthors: first 19, ..., last
+  const first19 = authors.slice(0, 19).map(formatOne).join(', ')
+  return `${first19}, ... ${formatOne(authors[authors.length - 1])}`
+}
+
+/**
+ * Format authors for MLA style
+ *
+ * @param {Array} authors - Array of parsed author objects
+ * @returns {string}
+ */
+export function formatMlaAuthors(authors) {
+  if (!authors?.length) return ''
+
+  const formatFirst = (author) => {
+    const suffix = author.suffix ? `, ${author.suffix}` : ''
+    return author.given
+      ? `${author.family}${suffix}, ${author.given}`
+      : author.family + suffix
+  }
+
+  const formatSubsequent = (author) => {
+    const suffix = author.suffix ? `, ${author.suffix}` : ''
+    return author.given
+      ? `${author.given} ${author.family}${suffix}`
+      : author.family + suffix
+  }
+
+  if (authors.length === 1) {
+    return formatFirst(authors[0])
+  }
+
+  if (authors.length === 2) {
+    return `${formatFirst(authors[0])}, and ${formatSubsequent(authors[1])}`
+  }
+
+  if (authors.length === 3) {
+    return `${formatFirst(authors[0])}, ${formatSubsequent(authors[1])}, and ${formatSubsequent(authors[2])}`
+  }
+
+  // 4+ authors: first author et al.
+  return `${formatFirst(authors[0])}, et al.`
+}
+
+/**
+ * Format authors for Chicago style (author-date)
+ *
+ * @param {Array} authors - Array of parsed author objects
+ * @returns {string}
+ */
+export function formatChicagoAuthors(authors) {
+  if (!authors?.length) return ''
+
+  const formatOne = (author, isFirst = false) => {
+    const suffix = author.suffix ? `, ${author.suffix}` : ''
+    if (isFirst) {
+      return author.given
+        ? `${author.family}${suffix}, ${author.given}`
+        : author.family + suffix
+    }
+    return author.given
+      ? `${author.given} ${author.family}${suffix}`
+      : author.family + suffix
+  }
+
+  if (authors.length === 1) {
+    return formatOne(authors[0], true)
+  }
+
+  if (authors.length === 2) {
+    return `${formatOne(authors[0], true)} and ${formatOne(authors[1])}`
+  }
+
+  if (authors.length === 3) {
+    return `${formatOne(authors[0], true)}, ${formatOne(authors[1])}, and ${formatOne(authors[2])}`
+  }
+
+  // 4+ authors: first author et al.
+  return `${formatOne(authors[0], true)} et al.`
+}
+
+/**
+ * Format authors for IEEE style
+ *
+ * @param {Array} authors - Array of parsed author objects
+ * @returns {string}
+ */
+export function formatIeeeAuthors(authors) {
+  if (!authors?.length) return ''
+
+  const formatOne = (author) => {
+    const initials = getInitials(author.given, { periods: true, spaces: true })
+    const suffix = author.suffix ? ` ${author.suffix}` : ''
+    return initials
+      ? `${initials} ${author.family}${suffix}`
+      : author.family + suffix
+  }
+
+  if (authors.length === 1) {
+    return formatOne(authors[0])
+  }
+
+  if (authors.length === 2) {
+    return `${formatOne(authors[0])} and ${formatOne(authors[1])}`
+  }
+
+  // 3+ authors in IEEE: first author et al. in citations, all in references
+  const allButLast = authors.slice(0, -1).map(formatOne).join(', ')
+  return `${allButLast}, and ${formatOne(authors[authors.length - 1])}`
+}
+
+/**
+ * Format authors for a specific style
+ *
+ * @param {Array|string} authors - Authors array or string
+ * @param {Object} [options]
+ * @param {string} [options.style='apa'] - Citation style
+ * @param {number} [options.max=20] - Max authors before et al.
+ * @returns {string}
+ */
+export function formatAuthors(authors, options = {}) {
+  const { style = 'apa', max = 20 } = options
+
+  // Parse if string
+  const parsed =
+    typeof authors === 'string' ? parseAuthorString(authors) : authors
+
+  if (!parsed?.length) return ''
+
+  switch (style) {
+    case 'apa':
+      return formatApaAuthors(parsed, max)
+    case 'mla':
+      return formatMlaAuthors(parsed)
+    case 'chicago':
+      return formatChicagoAuthors(parsed)
+    case 'ieee':
+      return formatIeeeAuthors(parsed)
+    default:
+      return formatApaAuthors(parsed, max)
+  }
+}

package/src/bibliography/utils/dates.js

@@ -0,0 +1,228 @@
+/**
+ * Date Formatting Utilities
+ *
+ * Functions for formatting dates in various citation styles.
+ *
+ * @module @uniweb/scholar/bibliography/utils/dates
+ */
+
+/**
+ * Month names for formatting
+ */
+const MONTHS_FULL = [
+  'January',
+  'February',
+  'March',
+  'April',
+  'May',
+  'June',
+  'July',
+  'August',
+  'September',
+  'October',
+  'November',
+  'December',
+]
+
+const MONTHS_SHORT = [
+  'Jan.',
+  'Feb.',
+  'Mar.',
+  'Apr.',
+  'May',
+  'June',
+  'July',
+  'Aug.',
+  'Sep.',
+  'Oct.',
+  'Nov.',
+  'Dec.',
+]
+
+/**
+ * Parse a date from various formats
+ *
+ * @param {string|number|Date|Object} date - Date input
+ * @returns {{ year?: number, month?: number, day?: number }}
+ */
+export function parseDate(date) {
+  if (!date) return {}
+
+  // Already structured
+  if (typeof date === 'object' && !(date instanceof Date)) {
+    return {
+      year: date.year ?? date.Year,
+      month: date.month ?? date.Month,
+      day: date.day ?? date.Day,
+    }
+  }
+
+  // JavaScript Date
+  if (date instanceof Date) {
+    return {
+      year: date.getFullYear(),
+      month: date.getMonth() + 1,
+      day: date.getDate(),
+    }
+  }
+
+  // Number (year only)
+  if (typeof date === 'number') {
+    return { year: date }
+  }
+
+  // String parsing
+  const str = String(date).trim()
+
+  // ISO format: YYYY-MM-DD
+  const isoMatch = str.match(/^(\d{4})(?:-(\d{1,2})(?:-(\d{1,2}))?)?/)
+  if (isoMatch) {
+    return {
+      year: parseInt(isoMatch[1], 10),
+      month: isoMatch[2] ? parseInt(isoMatch[2], 10) : undefined,
+      day: isoMatch[3] ? parseInt(isoMatch[3], 10) : undefined,
+    }
+  }
+
+  // Year only
+  const yearMatch = str.match(/^\d{4}$/)
+  if (yearMatch) {
+    return { year: parseInt(str, 10) }
+  }
+
+  // Month Year: "January 2024", "Jan 2024"
+  const monthYearMatch = str.match(
+    /^(\w+)\s+(\d{4})$/
+  )
+  if (monthYearMatch) {
+    const monthName = monthYearMatch[1].toLowerCase()
+    const monthIndex = MONTHS_FULL.findIndex(
+      (m) => m.toLowerCase().startsWith(monthName.slice(0, 3))
+    )
+    return {
+      year: parseInt(monthYearMatch[2], 10),
+      month: monthIndex !== -1 ? monthIndex + 1 : undefined,
+    }
+  }
+
+  return {}
+}
+
+/**
+ * Format date for APA style
+ *
+ * @param {Object} date - Parsed date object
+ * @returns {string}
+ */
+export function formatApaDate(date) {
+  const parsed = parseDate(date)
+
+  if (!parsed.year) return 'n.d.'
+
+  if (parsed.month && parsed.day) {
+    return `${parsed.year}, ${MONTHS_FULL[parsed.month - 1]} ${parsed.day}`
+  }
+
+  if (parsed.month) {
+    return `${parsed.year}, ${MONTHS_FULL[parsed.month - 1]}`
+  }
+
+  return String(parsed.year)
+}
+
+/**
+ * Format date for MLA style
+ *
+ * @param {Object} date - Parsed date object
+ * @returns {string}
+ */
+export function formatMlaDate(date) {
+  const parsed = parseDate(date)
+
+  if (!parsed.year) return ''
+
+  if (parsed.month && parsed.day) {
+    return `${parsed.day} ${MONTHS_SHORT[parsed.month - 1]} ${parsed.year}`
+  }
+
+  if (parsed.month) {
+    return `${MONTHS_SHORT[parsed.month - 1]} ${parsed.year}`
+  }
+
+  return String(parsed.year)
+}
+
+/**
+ * Format date for Chicago style
+ *
+ * @param {Object} date - Parsed date object
+ * @returns {string}
+ */
+export function formatChicagoDate(date) {
+  const parsed = parseDate(date)
+
+  if (!parsed.year) return 'n.d.'
+
+  if (parsed.month && parsed.day) {
+    return `${MONTHS_FULL[parsed.month - 1]} ${parsed.day}, ${parsed.year}`
+  }
+
+  if (parsed.month) {
+    return `${MONTHS_FULL[parsed.month - 1]} ${parsed.year}`
+  }
+
+  return String(parsed.year)
+}
+
+/**
+ * Format date for IEEE style
+ *
+ * @param {Object} date - Parsed date object
+ * @returns {string}
+ */
+export function formatIeeeDate(date) {
+  const parsed = parseDate(date)
+
+  if (!parsed.year) return ''
+
+  if (parsed.month) {
+    return `${MONTHS_SHORT[parsed.month - 1]} ${parsed.year}`
+  }
+
+  return String(parsed.year)
+}
+
+/**
+ * Format date for a specific style
+ *
+ * @param {any} date - Date input
+ * @param {Object} [options]
+ * @param {string} [options.style='apa'] - Citation style
+ * @returns {string}
+ */
+export function formatDate(date, options = {}) {
+  const { style = 'apa' } = options
+
+  switch (style) {
+    case 'apa':
+      return formatApaDate(date)
+    case 'mla':
+      return formatMlaDate(date)
+    case 'chicago':
+      return formatChicagoDate(date)
+    case 'ieee':
+      return formatIeeeDate(date)
+    default:
+      return formatApaDate(date)
+  }
+}
+
+/**
+ * Get year from date
+ *
+ * @param {any} date - Date input
+ * @returns {number|undefined}
+ */
+export function getYear(date) {
+  return parseDate(date).year
+}

package/src/bibliography/utils/index.js

@@ -0,0 +1,8 @@
+/**
+ * Bibliography Utilities
+ *
+ * @module @uniweb/scholar/bibliography/utils
+ */
+
+export * from './authors.js'
+export * from './dates.js'

package/src/citations/Bibliography.jsx

@@ -0,0 +1,129 @@
+/**
+ * Bibliography Component
+ *
+ * Renders a formatted list of references that have been cited in the document.
+ *
+ * @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
+ *
+ * @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])
+
+  // 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])
+
+  if (!formattedRefs.length) {
+    return null
+  }
+
+  // Use numbered list for IEEE style
+  const isNumeric = style === 'ieee'
+
+  return (
+    <section className={className} {...props}>
+      {showTitle && (
+        <h2
+          style={{
+            fontSize: '1.5rem',
+            fontWeight: '600',
+            marginBottom: '1rem',
+          }}
+        >
+          {title}
+        </h2>
+      )}
+
+      {isNumeric ? (
+        <ol
+          style={{
+            listStyleType: 'decimal',
+            paddingLeft: '2rem',
+            lineHeight: '1.8',
+          }}
+        >
+          {formattedRefs.map((ref) => (
+            <li
+              key={ref.id}
+              id={`ref-${ref.id}`}
+              className={itemClassName}
+              style={{
+                marginBottom: '0.75rem',
+              }}
+            >
+              {ref.formatted}
+            </li>
+          ))}
+        </ol>
+      ) : (
+        <div
+          style={{
+            lineHeight: '1.8',
+          }}
+        >
+          {formattedRefs.map((ref) => (
+            <p
+              key={ref.id}
+              id={`ref-${ref.id}`}
+              className={itemClassName}
+              style={{
+                marginBottom: '0.75rem',
+                paddingLeft: '2rem',
+                textIndent: '-2rem',
+              }}
+            >
+              {ref.formatted}
+            </p>
+          ))}
+        </div>
+      )}
+    </section>
+  )
+}
+
+export default Bibliography