@uniweb/scholar 0.2.1 → 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.1",
-  "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",
@@ -44,10 +43,20 @@
     "@citestyle/bibtex": "^1.0.0",
     "@citestyle/core": "^1.0.0",
     "@citestyle/registry": "^1.0.0",
-    "@citestyle/styles": "^1.0.0",
-    "katex": "^0.16.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/index.js

@@ -11,8 +11,12 @@
  * @module @uniweb/scholar
  */
 
-// Math components
-export { Math, Equation, EquationRef, loadKatex } from './math/index.js'
+// Math components — scholar no longer ships a math renderer. Plain
+// LaTeX in markdown (`$x$`, `$$x$$`, fenced ```math) is compiled to
+// MathML by the content pipeline and rendered natively by the browser.
+// <Equation> / <EquationRef> cover numbered cross-referenceable
+// equations, consuming pre-compiled MathML via `content.math`.
+export { Equation, EquationRef } from './math/index.js'
 
 // Bibliography — formatting, parsing, normalization
 export {

package/src/math/Equation.jsx

@@ -1,31 +1,49 @@
 /**
  * Equation Component
  *
- * Renders a numbered equation with an optional label for cross-referencing.
- * Equations are numbered sequentially within a CitationProvider context.
+ * Renders a numbered display equation from pre-compiled MathML.
+ *
+ * The MathML is produced by Uniweb's content pipeline at build time
+ * (see @uniweb/content-reader/math). This component does no math
+ * rendering of its own — it wraps the MathML string with numbering and
+ * cross-reference machinery, which means it is fully SSR-safe and adds
+ * zero runtime math library cost to sites.
+ *
+ * Authors write labeled display equations in markdown:
+ *
+ *   ```math:einstein
+ *   E = mc^2
+ *   ```
+ *
+ * A foundation's section component then iterates `content.math` and
+ * renders each labeled entry through <Equation>:
+ *
+ *   <EquationProvider>
+ *     {content.math.map(m => (
+ *       <Equation key={m.id} id={m.id} mathml={m.mathml} />
+ *     ))}
+ *   </EquationProvider>
  *
  * @module @uniweb/scholar/math/Equation
  */
 
-import React, { useEffect, useState, useContext, useId } from 'react'
-import { loadKatex } from './katex-loader.js'
+import React, { useContext, useEffect, useId } from 'react'
 
 /**
- * Context for tracking equation numbers
- * Exported for use by EquationRef
+ * Context for tracking equation numbers. Exported for use by EquationRef.
  */
 export const EquationContext = React.createContext(null)
 
 /**
- * Provider for equation numbering
- * Wrap your content with this to enable automatic equation numbering.
+ * Provider for equation numbering. Wrap section content with this to
+ * enable automatic sequential numbering across all <Equation> instances.
  *
  * @param {Object} props
  * @param {React.ReactNode} props.children
  * @param {number} [props.startNumber=1] - Starting equation number
  */
 export function EquationProvider({ children, startNumber = 1 }) {
-  const [equations, setEquations] = useState(new Map())
+  const [equations, setEquations] = React.useState(new Map())
   const counterRef = React.useRef(startNumber)
 
   const register = React.useCallback((id) => {
@@ -39,7 +57,7 @@ export function EquationProvider({ children, startNumber = 1 }) {
 
   const getNumber = React.useCallback(
     (id) => equations.get(id),
-    [equations]
+    [equations],
   )
 
   return (
@@ -50,77 +68,35 @@ export function EquationProvider({ children, startNumber = 1 }) {
 }
 
 /**
- * Hook to access equation context
+ * Hook for foundation code that needs direct access to the numbering
+ * context (e.g., to render a list of all equations on a page).
  */
 export function useEquations() {
   return useContext(EquationContext)
 }
 
 /**
- * Equation - Numbered display equation with optional label
+ * Equation — numbered display equation rendered from pre-compiled MathML.
  *
  * @param {Object} props
- * @param {string} props.children - LaTeX expression
- * @param {string} [props.id] - Unique identifier for cross-referencing
- * @param {string} [props.label] - Custom label (defaults to equation number)
- * @param {string} [props.className] - Additional CSS classes
- *
- * @example
- * <EquationProvider>
- *   <Equation id="einstein">E = mc^2</Equation>
- *   <p>As shown in <EquationRef id="einstein" />, energy equals...</p>
- * </EquationProvider>
+ * @param {string} [props.id] - Identifier for cross-referencing. If omitted,
+ *   a stable React id is generated but will not be discoverable by <EquationRef>.
+ * @param {string} props.mathml - Pre-compiled MathML HTML string from the
+ *   content pipeline (e.g., `content.math[i].mathml`).
+ * @param {string} [props.label] - Override the auto-number with a custom label.
+ * @param {string} [props.className] - Additional CSS classes on the wrapper.
  */
-export function Equation({ children, id, label, className, ...props }) {
-  const [html, setHtml] = useState(null)
+export function Equation({ id, mathml, label, className, ...props }) {
+  const ctx = useContext(EquationContext)
   const generatedId = useId()
   const equationId = id || generatedId
-  const ctx = useContext(EquationContext)
-
-  // Extract LaTeX string from children
-  const latex = typeof children === 'string' ? children.trim() : ''
 
-  // Register equation for numbering
   useEffect(() => {
-    if (ctx) {
-      ctx.register(equationId)
-    }
+    if (ctx) ctx.register(equationId)
   }, [ctx, equationId])
 
-  // Get equation number
   const number = ctx?.getNumber(equationId)
-
-  // Render LaTeX
-  useEffect(() => {
-    if (!latex) return
-
-    let cancelled = false
-
-    async function render() {
-      const katex = await loadKatex()
-      if (cancelled || !katex) return
-
-      try {
-        const rendered = katex.renderToString(latex, {
-          displayMode: true,
-          throwOnError: false,
-        })
-        if (!cancelled) {
-          setHtml(rendered)
-        }
-      } catch (e) {
-        console.warn('[Equation] Render error:', e.message)
-      }
-    }
-
-    render()
-
-    return () => {
-      cancelled = true
-    }
-  }, [latex])
-
-  const displayLabel = label || (number ? `(${number})` : '')
+  const displayLabel = label !== undefined ? label : number ? `(${number})` : ''
 
   return (
     <div
@@ -135,16 +111,10 @@ export function Equation({ children, id, label, className, ...props }) {
       }}
       {...props}
     >
-      {/* Equation content */}
-      <div style={{ flex: 1, textAlign: 'center' }}>
-        {html ? (
-          <span dangerouslySetInnerHTML={{ __html: html }} />
-        ) : (
-          <code>{latex}</code>
-        )}
-      </div>
-
-      {/* Equation number */}
+      <div
+        style={{ flex: 1, textAlign: 'center' }}
+        dangerouslySetInnerHTML={{ __html: mathml || '' }}
+      />
       {displayLabel && (
         <span
           style={{

package/src/math/index.js

@@ -1,12 +1,27 @@
 /**
  * Math Module
  *
- * Components for rendering LaTeX math expressions using KaTeX.
+ * Numbered equations and cross-references, rendered from pre-compiled
+ * MathML produced by Uniweb's content pipeline.
+ *
+ * Plain inline and display math (`$x$`, `$$x$$`, fenced ```math) is
+ * handled entirely by the content pipeline — authors write LaTeX in
+ * markdown and the browser renders real MathML natively. No component
+ * wrapper needed. The former `<Math>` component (KaTeX-based) was
+ * removed in an earlier release.
+ *
+ * `<Equation>` and `<EquationRef>` remain for the distinct feature of
+ * numbered cross-referenceable equations. They consume `content.math`
+ * entries (which carry pre-compiled MathML and an optional id); scholar
+ * no longer ships a math renderer.
  *
  * @module @uniweb/scholar/math
  */
 
-export { Math } from './Math.jsx'
-export { Equation, EquationProvider, EquationContext, useEquations } from './Equation.jsx'
+export {
+  Equation,
+  EquationProvider,
+  EquationContext,
+  useEquations,
+} from './Equation.jsx'
 export { EquationRef } from './EquationRef.jsx'
-export { loadKatex, isKatexLoaded, renderLatex } from './katex-loader.js'

package/src/math/Math.jsx

@@ -1,115 +0,0 @@
-/**
- * Math Component
- *
- * Renders LaTeX math expressions using KaTeX.
- * Supports both inline and display (block) modes.
- *
- * @module @uniweb/scholar/math/Math
- */
-
-import React, { useEffect, useState } from 'react'
-import { loadKatex } from './katex-loader.js'
-
-/**
- * Math - Render LaTeX math expressions
- *
- * @param {Object} props
- * @param {string} props.children - LaTeX expression to render
- * @param {boolean} [props.display=false] - Display mode (block) vs inline
- * @param {string} [props.className] - Additional CSS classes
- *
- * @example
- * // Inline math
- * <Math>E = mc^2</Math>
- *
- * @example
- * // Display (block) math
- * <Math display>
- *   \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
- * </Math>
- */
-export function Math({ children, display = false, className, ...props }) {
-  const [html, setHtml] = useState(null)
-  const [error, setError] = useState(null)
-
-  // Extract LaTeX string from children
-  const latex = typeof children === 'string' ? children.trim() : ''
-
-  useEffect(() => {
-    if (!latex) return
-
-    let cancelled = false
-
-    async function render() {
-      const katex = await loadKatex()
-      if (cancelled || !katex) return
-
-      try {
-        const rendered = katex.renderToString(latex, {
-          displayMode: display,
-          throwOnError: false,
-          errorColor: '#cc0000',
-        })
-        if (!cancelled) {
-          setHtml(rendered)
-          setError(null)
-        }
-      } catch (e) {
-        if (!cancelled) {
-          setError(e.message)
-          setHtml(null)
-        }
-      }
-    }
-
-    render()
-
-    return () => {
-      cancelled = true
-    }
-  }, [latex, display])
-
-  // Error state
-  if (error) {
-    return (
-      <span
-        className={className}
-        style={{ color: '#cc0000', fontFamily: 'monospace' }}
-        title={error}
-        {...props}
-      >
-        {latex}
-      </span>
-    )
-  }
-
-  // Loading state - show raw LaTeX in code format
-  if (!html) {
-    return (
-      <code className={className} {...props}>
-        {latex}
-      </code>
-    )
-  }
-
-  // Rendered math
-  if (display) {
-    return (
-      <div
-        className={className}
-        dangerouslySetInnerHTML={{ __html: html }}
-        {...props}
-      />
-    )
-  }
-
-  return (
-    <span
-      className={className}
-      dangerouslySetInnerHTML={{ __html: html }}
-      {...props}
-    />
-  )
-}
-
-export default Math

package/src/math/katex-loader.js

@@ -1,105 +0,0 @@
-/**
- * KaTeX Lazy Loader
- *
- * Provides lazy loading of KaTeX with module-level caching.
- * KaTeX is only loaded when math rendering is actually needed.
- *
- * @module @uniweb/scholar/math/katex-loader
- */
-
-// Module-level state for singleton pattern
-let katexInstance = null
-let katexLoadPromise = null
-let cssInjected = false
-
-/**
- * CDN URL for KaTeX CSS (matches the katex version in package.json)
- */
-const KATEX_CSS_URL = 'https://cdn.jsdelivr.net/npm/katex@0.16.0/dist/katex.min.css'
-
-/**
- * Inject KaTeX CSS into the document head
- * Only injects once per page load
- */
-function injectKatexCSS() {
-  if (cssInjected || typeof document === 'undefined') return
-
-  const styleId = 'uniweb-katex-css'
-
-  // Check if already injected
-  if (document.getElementById(styleId)) {
-    cssInjected = true
-    return
-  }
-
-  const link = document.createElement('link')
-  link.id = styleId
-  link.rel = 'stylesheet'
-  link.href = KATEX_CSS_URL
-  link.crossOrigin = 'anonymous'
-  document.head.appendChild(link)
-
-  cssInjected = true
-}
-
-/**
- * Load KaTeX lazily
- *
- * Returns cached instance if already loaded, otherwise loads
- * KaTeX dynamically and injects its CSS.
- *
- * @returns {Promise<Object>} The KaTeX module
- */
-export async function loadKatex() {
-  if (katexInstance) return katexInstance
-  if (katexLoadPromise) return katexLoadPromise
-
-  katexLoadPromise = (async () => {
-    try {
-      const katex = await import('katex')
-      katexInstance = katex.default || katex
-
-      // Inject CSS when KaTeX is loaded
-      injectKatexCSS()
-
-      return katexInstance
-    } catch (error) {
-      console.warn('[scholar/math] Failed to load KaTeX:', error)
-      katexLoadPromise = null
-      return null
-    }
-  })()
-
-  return katexLoadPromise
-}
-
-/**
- * Check if KaTeX is already loaded
- *
- * @returns {boolean} True if KaTeX is loaded and ready
- */
-export function isKatexLoaded() {
-  return katexInstance !== null
-}
-
-/**
- * Render LaTeX to HTML string
- *
- * @param {string} latex - LaTeX string to render
- * @param {Object} options - KaTeX options
- * @returns {Promise<string|null>} Rendered HTML or null on error
- */
-export async function renderLatex(latex, options = {}) {
-  const katex = await loadKatex()
-  if (!katex) return null
-
-  try {
-    return katex.renderToString(latex, {
-      throwOnError: false,
-      ...options,
-    })
-  } catch (error) {
-    console.warn('[scholar/math] LaTeX render error:', error.message)
-    return null
-  }
-}