Skip to content

Commit fb32da2

Browse files
ClementDreptinClementDreptin
authored
Merge pull request #201 from istex/chore/doc
Chore: add documentation and improve UI
2 parents d71c8b0 + 4100cff commit fb32da2

13 files changed

Lines changed: 1070 additions & 85 deletions

‎docs/demo-architecture.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Demo Architecture
2+
3+
**Type**: Reference documentation
4+
5+
This document describes the architecture of **@istex/viewer-demo**, a React application that demonstrates the capabilities of the `@istex/react-tei` viewer component. The demo provides two ways to visualize TEI documents: file upload and ARK identifier lookup.
6+
7+
## Purpose
8+
9+
The demo application serves multiple purposes:
10+
11+
- **Showcase** viewer features and capabilities
12+
- **Reference implementation** for integrating the viewer
13+
- **Testing environment** for development and debugging
14+
- **User documentation** through working examples
15+
16+
## Viewer Modules
17+
18+
### File Viewer Module
19+
20+
**Location**: [modules/file-viewer/](../packages/demo/src/modules/file-viewer/)
21+
22+
**Purpose**: Allows users to upload and view TEI documents from their local system
23+
24+
**Features**:
25+
26+
- Upload TEI XML documents via file picker
27+
- Upload enrichment files (Unitex, Multicat, NB, TEEFT)
28+
- Persist uploaded files in component state
29+
- Display documents using the `@istex/react-tei` Viewer
30+
31+
**User flow**:
32+
33+
1. User selects TEI document file
34+
2. Optionally selects enrichment files
35+
3. Files are read and stored in ViewerContext
36+
4. Navigate to viewer page
37+
5. Viewer component renders the document
38+
39+
### ARK Viewer Module
40+
41+
**Location**: [modules/ark-viewer/](../packages/demo/src/modules/ark-viewer/)
42+
43+
**Purpose**: Load and display documents by their ARK (Archival Resource Key) identifier
44+
45+
**Features**:
46+
47+
- Fetch documents from remote sources using ARK IDs
48+
- Loading states during document retrieval
49+
- Error handling for missing or invalid documents
50+
- Sample TEI and enrichment XML files for testing
51+
52+
**User flow**:
53+
54+
1. User enters ARK identifier or follows link
55+
2. Router loader initiates document fetch
56+
3. Loading indicator displayed
57+
4. Document rendered or error shown
58+
59+
## Internationalization
60+
61+
**Location**: [i18n/](../packages/demo/src/i18n/)
62+
63+
Provides language detection based on browser settings, with translation resources for English and French.
64+
65+
## Build Configuration
66+
67+
**File**: [vite.config.ts](../packages/demo/vite.config.ts)
68+
69+
Configured for GitHub Pages deployment at `/istex-view/` with development server on port 3000.
70+
71+
## Routing Structure
72+
73+
**Router type**: Hash-based (`createHashRouter`) for compatibility with static hosting (GitHub Pages).
74+
75+
## Design Patterns
76+
77+
The demo uses context-based state management, route-based code splitting with React Router loaders, and component composition. The clean separation between file-based and ARK-based viewing modes demonstrates flexible integration patterns for the `@istex/react-tei` viewer component.

‎docs/repository-architecture.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Repository Architecture
2+
3+
This document describes the monorepo structure, package organization, and development tools used in the Istex TEI Viewer project. The primary goal is to **make the TEI viewer reusable in other applications** while maintaining a demo application and comprehensive test suite.
4+
5+
## Why a Monorepo?
6+
7+
A monorepo approach allows us to:
8+
9+
- Keep the core viewer library and demo application in sync
10+
- Share TypeScript configurations and development tools
11+
- Test changes across all packages simultaneously
12+
- Simplify the release process for the reusable library
13+
14+
## Package Structure
15+
16+
### 📦 [@istex/react-tei](../packages/react-tei/)
17+
18+
**The core library** - Reusable TEI viewer React component:
19+
20+
- **Purpose**: Provide a React component to visualize and enrich TEI (Text Encoding Initiative) documents
21+
- **Package type**: React library (ES module)
22+
- **Exports**: The package exposes all source files via `./*` exports for maximum flexibility.
23+
24+
### 🎨 [@istex/viewer-demo](../packages/demo/)
25+
26+
The **Demonstration application** showcasing the TEI viewer capabilities:
27+
28+
- **Purpose**:
29+
- Demonstrate viewer features and usage patterns
30+
- Serve as an integration reference for developers
31+
- Provide a testing environment for the core library
32+
- **Package type**: React application built with Vite
33+
34+
See [Demo Architecture](./demo-architecture.md) for detailed information.
35+
36+
### 🧪 [@istex/e2e](../packages/e2e/)
37+
38+
The **End-to-end test suite** ensuring viewer functionality in real scenarios:
39+
40+
- **Purpose**: Validate that the viewer works correctly with various TEI documents and enrichments
41+
- **Package type**: Playwright test suite
42+
43+
See [Testing Guide](./testing.md) for how to run and write tests.
44+
45+
## Configuration Files
46+
47+
All packages share base configurations:
48+
49+
- [tsconfig.base.json](../tsconfig.base.json): Base TypeScript config
50+
- [biome.json](../biome.json): Linting and formatting rules
51+
- [vitest.config.ts](../vitest.config.ts): Test configuration
52+
53+
Each package extends these with its own `tsconfig.json` and build configuration.
54+
55+
## Workspace Configuration
56+
57+
See [pnpm-workspace.yaml](../pnpm-workspace.yaml) for workspace definition. Inter-package dependencies use the `workspace:^` protocol.
58+
59+
## Dependency Management
60+
61+
The project uses pnpm's [catalog feature](https://pnpm.io/catalogs) to manage shared dependency versions across packages, ensuring version consistency for React, TypeScript, Material-UI, and other shared dependencies.
62+
63+
## Development Workflow
64+
65+
### Working Across Packages
66+
67+
The `workspace:^` protocol creates symlinks between packages during development:
68+
69+
- Changes in `react-tei` are immediately available in `demo`
70+
- No need to rebuild or reinstall after changes
71+
- Hot Module Replacement works across package boundaries
72+
73+
### Turbo Cache
74+
75+
Turbo caches build outputs for faster subsequent builds:
76+
77+
- Cache is stored in `node_modules/.cache/turbo/`
78+
- Clear cache if builds seem stale: `pnpm turbo run build --force`
79+
- CI builds start with empty cache
80+
81+
### Common Development Tasks
82+
83+
**Adding a new npm dependency**:
84+
85+
```sh
86+
cd packages/react-tei
87+
pnpm add library-name
88+
```
89+
90+
**Adding a dev dependency (all packages)**:
91+
92+
```sh
93+
# Update catalog in root package.json
94+
pnpm add -D -w dev-tool-name
95+
```
96+
97+
**Removing a dependency**:
98+
99+
```sh
100+
cd packages/react-tei
101+
pnpm remove library-name
102+
```
103+
104+
**Checking bundle size**:
105+
106+
```sh
107+
cd packages/demo
108+
pnpm build
109+
# Check dist/ folder size
110+
```
111+
112+
## Monorepo Tips for Maintainers
113+
114+
### Import Path Guidelines
115+
116+
**Within same package**: Use relative imports
117+
118+
```tsx
119+
import { helper } from './utils/helper';
120+
```
121+
122+
**Cross-package**: Use package name
123+
124+
```tsx
125+
import { Viewer } from '@istex/react-tei/Viewer';
126+
```
127+
128+
**Never**: Import internal files from other packages
129+
130+
```tsx
131+
// ❌ Wrong
132+
import { internal } from '@istex/react-tei/src/internal';
133+
134+
// ✅ Correct
135+
import { internal } from '@istex/react-tei/internal';
136+
```
137+
138+
### Managing Breaking Changes
139+
140+
If changing `react-tei` public API:
141+
142+
1. Update `demo` app to use new API
143+
2. Update E2E tests if affected
144+
3. Document breaking change
145+
4. Consider deprecation period
146+
5. Bump major version

‎docs/supported-tags.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Supported TEI Tags
2+
3+
This document lists all TEI tags supported by the istex-view viewer.
4+
5+
## Sections
6+
7+
- **Body**: Main document body
8+
- **Footnotes**: Footnotes sidebar section
9+
- **Bibref**: Bibliographic references sidebar section
10+
- **Authors**: Authors sidebar section
11+
- **Source**: Source sidebar section
12+
- **\***: Supported in all applicable sections
13+
14+
## All Supported Tags
15+
16+
| Tag | Description | Sections | Component |
17+
| --- | ----------- | -------- | --------- |
18+
| `addName` | Additional name | Authors, Bibref | [PersNamePart.tsx](../packages/react-tei/src/SidePanel/authors/PersNamePart.tsx) |
19+
| `affiliation` | Author affiliation | Authors | Nothing |
20+
| `author` | Author element | Bibref | NoOp |
21+
| `bibl` | Bibliographic reference | Body, Bibref | [Bibl.tsx](../packages/react-tei/src/SidePanel/bibliographicReferences/Bibl.tsx) |
22+
| `biblScope` | Bibliographic scope (volume, pages, etc.) | Body, Bibref | NoOp |
23+
| `biblStruct` | Structured bibliographic reference | Bibref | [BiblStruct.tsx](../packages/react-tei/src/SidePanel/bibliographicReferences/BiblStruct.tsx) |
24+
| `body` | Document body container | Body | NoOp |
25+
| `date` | Date element | Body, Footnotes, Bibref | [DateTag.tsx](../packages/react-tei/src/tags/DateTag.tsx) |
26+
| `div` | Division/section | Body | [Div.tsx](../packages/react-tei/src/tags/Div.tsx) |
27+
| `email` | Email address | Authors | Nothing |
28+
| `emph` | Emphasized text | Body, Footnotes, Bibref | [Emph.tsx](../packages/react-tei/src/tags/Emph.tsx) |
29+
| `figure` | Figure with graphics or tables | Body | [Figure.tsx](../packages/react-tei/src/tags/Figure.tsx) |
30+
| `floatingText` | Floating text element | Body | [FloatingText.tsx](../packages/react-tei/src/tags/floatingText/FloatingText.tsx) |
31+
| `forename` | First name | Authors, Bibref | [PersNamePart.tsx](../packages/react-tei/src/SidePanel/authors/PersNamePart.tsx) |
32+
| `formula` | Mathematical formula with notation or rendering | Body, Footnotes, Bibref | [Formula.tsx](../packages/react-tei/src/tags/Formula.tsx) |
33+
| `genName` | Generational name (Jr., Sr., etc.) | Authors, Bibref | [PersNamePart.tsx](../packages/react-tei/src/SidePanel/authors/PersNamePart.tsx) |
34+
| `graphic` | Graphic element (used in formulas) | Body, Footnotes, Bibref | [Graphic.tsx](../packages/react-tei/src/tags/Graphic.tsx) |
35+
| `head` | Heading element | Body | [Head.tsx](../packages/react-tei/src/tags/Head.tsx) |
36+
| `hi` | Highlighted text (various renditions) | Body, Footnotes, Bibref | [Hi.tsx](../packages/react-tei/src/tags/Hi.tsx) |
37+
| `highlight` | Enrichment highlight | Body | [Highlight.tsx](../packages/react-tei/src/tags/Highlight.tsx) |
38+
| `highlightedText` | Text highlighted by enrichment | Body | NoOp |
39+
| `idno` | Identifier number | Source | [SourceIdno.tsx](../packages/react-tei/src/SidePanel/source/SourceIdno.tsx) |
40+
| `l` | Line (in verse) | Footnotes | [L.tsx](../packages/react-tei/src/tags/L.tsx) |
41+
| `lg` | Line group (verse stanza) | Footnotes | [Lg.tsx](../packages/react-tei/src/tags/Lg.tsx) |
42+
| `list` | List element (ordered/unordered) | Body | [List.tsx](../packages/react-tei/src/tags/list/List.tsx) |
43+
| `math` | MathML root element | Body, Footnotes, Bibref | [MathMLTag.tsx](../packages/react-tei/src/tags/formula/mathml/MathMLTag.tsx) |
44+
| MathML tags | All MathML tags (203 total) | Body, Footnotes, Bibref | [MathMLTag.tsx](../packages/react-tei/src/tags/formula/mathml/MathMLTag.tsx) |
45+
| `name` | Generic name element | Authors, Bibref | [Name.tsx](../packages/react-tei/src/SidePanel/authors/Name.tsx) |
46+
| `nameLink` | Name linking particle (de, von, etc.) | Authors, Bibref | [PersNamePart.tsx](../packages/react-tei/src/SidePanel/authors/PersNamePart.tsx) |
47+
| `note` | Note/footnote element | Footnotes, Bibref | [Note.tsx](../packages/react-tei/src/SidePanel/footNotes/Note.tsx) |
48+
| `orgName` | Organization name | Authors, Bibref | [PersNamePart.tsx](../packages/react-tei/src/SidePanel/authors/PersNamePart.tsx) |
49+
| `p` | Paragraph | Body, Footnotes | [P.tsx](../packages/react-tei/src/tags/P.tsx) |
50+
| `persName` | Personal name | Authors, Bibref | [PersName.tsx](../packages/react-tei/src/SidePanel/authors/PersName.tsx) |
51+
| `pubPlace` | Publication place | Bibref | NoOp |
52+
| `publisher` | Publisher | Bibref | NoOp |
53+
| `quote` | Quoted text block | Body, Footnotes, Bibref | [Quote.tsx](../packages/react-tei/src/tags/Quote.tsx) |
54+
| `ref` | Reference (footnote, bibliographic, URL, table) | Body, Footnotes, Bibref | [Ref.tsx](../packages/react-tei/src/tags/Ref.tsx) |
55+
| `roleName` | Role name | Authors, Bibref | [PersNamePart.tsx](../packages/react-tei/src/SidePanel/authors/PersNamePart.tsx) |
56+
| `s` | Sentence | Body | NoOp |
57+
| `sc` | Small capitals | Body | NoOp |
58+
| `series` | Series information | Bibref | NoOp |
59+
| `surname` | Last name | Authors, Bibref | [PersNamePart.tsx](../packages/react-tei/src/SidePanel/authors/PersNamePart.tsx) |
60+
| `table` | Table element | Body | [Table.tsx](../packages/react-tei/src/tags/Table.tsx) |
61+
| `title` | Title element | Body, Bibref | [Title.tsx](../packages/react-tei/src/tags/Title.tsx) |
62+
63+
See [mathMLTagNames.ts](../packages/react-tei/src/tags/formula/mathml/mathMLTagNames.ts) for the complete list of 203 supported MathML tags.
64+
65+
## Reference Types
66+
67+
The `ref` tag supports multiple reference types via the `@type` attribute:
68+
69+
- `bibr`: Bibliographic reference
70+
- `fn`: Footnote reference
71+
- `url`/`uri`: URL/URI reference
72+
- `fig`/`figure`: Figure reference
73+
- `table`: Table reference
74+
- `table-fn`: Table footnote reference
75+
76+
## Notes
77+
78+
- `NoOp` components render their children without additional styling or behavior
79+
- `Nothing` components render nothing (children are hidden)
80+
- Math tags (formula, graphic, and all MathML tags) are available in all contexts

0 commit comments

Comments
 (0)