@jinntec/jinntap

v2.1.1

Published

2 months ago

![JinnTap Logo](site/public/jinntap-logo.png)

0High
0Medium
0Low

joernturner

larswindauer

wolfgangmm

tei xml editor tiptap web-component

JinnTap

Edit TEI XML documents using a rich text editor. JinnTap preserves the structure of the XML in the editor. There's no need for complex transformation steps from TEI to HTML and back. The representation of the document in the editor corresponds directly with the XML. TEI elements are converted to HTML custom elements, preserving all attributes and structural features.

JinnTap comes as a web component. While it can be used standalone, it is usually meant to be embedded into a larger application context such as TEI Publisher 10, which will include JinnTap and does allow saving and reloading documents. TP 10 has not been released yet.

Documentation

Full documentation — including a detailed tei-schema.json reference and a live editor — is published at https://jinnelements.github.io/jinn-tap/.

Work on the docs locally with:

npm run docs:dev            # Eleventy dev server with hot reload
npm run build:site          # build library + docs site into dist/

Installation

npm install @jinntec/jinntap

Development Setup

Prerequisites

Node.js (v16 or higher)
npm (v7 or higher)

Building the Project

# Install dependencies
npm install

# Build the library
npm run build

Local development

# Docs site with embedded TEI/JATS editors
npm run docs:dev

# Vite dev server for Cypress tests (serves test/*.html)
npm run dev

Running Tests

# Open Cypress test runner
npm run cypress:open

# Run tests in headless mode
npm run cypress:run

Usage

Basic Usage

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/font/bootstrap-icons.min.css">
	<!-- Import the general editor styles; document styles load from the schema `css` property -->
    <link rel="stylesheet" href="node_modules/@jinntec/jinntap/dist/jinn-tap.css" />
    <script type="module" src="node_modules/@jinntec/jinntap/dist/jinn-tap.es.js"></script>
</head>
<body>
    <jinn-tap></jinn-tap>
    <pre id="output"></pre>
    <script>
        document.addEventListener('DOMContentLoaded', () => {
            const editor = document.querySelector('jinn-tap');
            const output = document.querySelector('#output');

            editor.addEventListener('content-change', (event) => {
                output.textContent = event.detail.teiXml;
            });
        });
    </script>
</body>
</html>

With Initial Content

<jinn-tap content="<tei-div><tei-p>Initial content</tei-p></tei-div>"></jinn-tap>

JavaScript API

// Get the editor instance
const editor = document.querySelector('jinn-tap').tiptap;

// Set content programmatically
editor.commands.setContent('<tei-div><tei-p>New content</tei-p></tei-div>');

// Get content as HTML
const htmlContent = editor.getHTML();

// Get content as TEI XML
const teiXml = editor.teiXml;

// Focus the editor
editor.focus();

Keyboard Shortcuts

The editor supports the following keyboard shortcuts:

Text Formatting

Ctrl/Cmd + B - Toggle bold text (hi with rend="bold")
Ctrl/Cmd + I - Toggle italic text (hi with rend="italic")
Ctrl/Cmd + U - Toggle underline text (hi with rend="underline")

TEI Elements

Ctrl/Cmd + Shift + P - Insert TEI persName
Ctrl/Cmd + Shift + L - Toggle list
Ctrl/Cmd + Shift + U - Insert footnote
Tab - Indent list item
Shift + Tab - Outdent list item
Enter - Create new list item
Backspace at start of list item - Convert to paragraph

General

Ctrl/Cmd + C - Copy selected text
Ctrl/Cmd + V - Paste text
Ctrl/Cmd + X - Cut text
Ctrl/Cmd + Z - Undo
Ctrl/Cmd + Shift + Z - Redo

Events

The component dispatches the following events:

content-change

Fired when the editor content changes.

editor.addEventListener('content-change', (event) => {
    const { content, teiXml } = event.detail;
    // content: HTML content
    // teiXml: TEI XML content
});

License

GNU General Public License v3.0 or later — see LICENSE.