:rocket: Astro TEI - React

An Astro component for publishing TEI as Custom Elements powered by CETEIcean.

This utility provides the React version of CETEIcean's default behaviors and provides a way of mapping your own React components to TEI elements via React TEI Router.

We recommend using the companion Astro TEI Component to pre-process a TEI string on the server side (during SSR or SSG) with the utility processTEI(). The React components included in this package are best used to provide reactive components starting from the pre-processed DOM, which can themselves be pre-rendered or hydrated following React's and Astro's conventions.

Installation

We recommend using this together with astro-tei and jsdom.

npm install @astro-tei/react astro-tei jsdom --save-dev

Basic Usage

You will want to load TEI data and pre-process it before passing it to the React component. We suggest relying on Astro TEI component to handle this process, as shown below.

The Astro TEI Component provides the utility processTEI() to pre-process the TEI and return a JSDOM serializable object.

---
import { TeiBaseStyle, processTei } from 'astro-tei';
import BasicRouter from '@astro-tei/react';

// Load TEI data with a dynamic import.
// One could also use Node's library fs to get the file's content.
const teiFile = (await import("someTEI.xml?raw")).default;

// processTEI() will pre-process the TEI and return a
// `JSDOM` serializable object.
const jdom = processTei(teiFile);
const teiDom = jdom.window.document;

// We need both the TEI in both DOM and string version to 
// fully support server and client behaviors.
// The pre-processed DOM object is only available on the server side,
// so the string serialization is necessary for client side operations.
const tei = jdom.serialize();

// We also need a list of element names to register as Custom Elements.
// The list is generated by CETEIcean and is available on the root element.
const elements = teiDom.documentElement.getAttribute("data-elements").split(",");
---

<!-- CETEIcean's default example CSS is bundled in another component
  for convenience and can be optionally added as shown above.
  Other custom styles can be added by importing CSS files or
  through your preferred method. -->
<TeiBaseStyle/>

<!-- BasicRouter provides CETEIcean's default behaviors as React components
  that can all be rendered on the server.
  For new components that need to run client-side code, use client:*,
  e.g. client:load (see more instructions below). -->
<BasicRouter doc={teiDom} data={tei} elements={elements} />

Adding custom React components

In order to provide your own React components, you'll need to wrap <BasicRouter> in a React component that can import and map (route) your components to TEI element names. In Astro, import your wrapper component instead of <BasicRouter>.

import React from "react";
import BasicRouter from '@astro-tei/react';

// You can still use the Default Behaviors!
import { DefaultBehaviors } from "@astro-tei/react";
import type { DefaultBehaviors } from "@astro-tei/react";

// Here is a custom component for tei-pb with some fun reactivity!
import Pb from './pb';

interface Props {
  doc: Document
  data: string
  elements: string[]
}

export default function TEI({doc, data, elements}: Props) {
  const {
    Tei,
    Eg,
    Graphic,
    List,
    Note,
    Ptr,
    Ref,
    TeiHeader
  } = DefaultBehaviors;

  const routes: Routes = {
    "tei-tei": Tei,
    "teieg-egxml": Eg,
    "tei-graphic": Graphic,
    "tei-list": List,
    "tei-note": Note,
    "tei-ptr": Ptr,
    "tei-ref": Ref,
    "tei-teiheader": TeiHeader,
    "tei-pb": Pb,
  };

  // Provide a client-side DOM for hydration.
  // This isn't needed when the code runs on the server because the DOM is already provided via the props.
  const usableDoc = typeof DOMParser !== 'undefined' ? (new DOMParser()).parseFromString(data, "text/xml") : doc;

  // Pass the new Routes to BasicRouter; here you can also add more React for handling State, Context, and more!
  return <BasicRouter doc={usableDoc} elements={elements} routes={routes} />
}