diff --git a/components/simple-transcription/ARCHITECTURE.md b/components/simple-transcription/ARCHITECTURE.md new file mode 100644 index 00000000..57f6e349 --- /dev/null +++ b/components/simple-transcription/ARCHITECTURE.md @@ -0,0 +1,115 @@ +# Transcription Interface Architecture + +This document explains the current TPEN transcription interface structure, ownership boundaries, and data/event flow. + +## Scope + +This describes the interface loaded from: + +- interfaces/transcription/index.html +- components/simple-transcription/index.js +- components/projects/project-header.js + +## Component Inventory + +Top-level composition: + +1. tpen-simple-transcription +2. tpen-project-header +3. tpen-transcription-block +4. tpen-workspace-tools + +**Note**: `tpen-line-image` and `tpen-image-fragment` are used by `tpen-transcription-interface` (`interfaces/transcription/index.js`), not by `tpen-simple-transcription`. This component handles image display inline via raw `` elements and the `adjustImages()` method. + +Header composition: + +1. project title display +2. canvas selector (select) +3. tpen-layer-selector +4. tpen-column-selector +5. line indicator +6. navigation controls (home, manage project, profile) + +Workspace composition: + +1. focused line image viewport (`#imgTop` — raw `` with custom zoom/pan via `adjustImages()`) +2. transcription input workspace (`tpen-transcription-block`) +3. workspace tools launcher/controls (`tpen-workspace-tools`) +4. remaining image fragment panel (`#imgBottom` — raw `` showing the rest of the canvas) + +## Visual Regions + +The interface is intentionally split into 3 regions: + +1. Header: navigation and context controls +2. Workspace: line-focused transcription work area +3. Split-screen tools panel: optional right-pane tools + +See the diagram reference in DIAGRAMS.md for detailed flow diagrams. + +## Data Truth Locations + +The table below defines ownership for key state. + +| Data | Source of truth | Primary readers | Mutated by | +| --- | --- | --- | --- | +| Active project graph (layers/pages/columns) | TPEN.activeProject | header, selectors, interface shell | project load/update flows | +| Current page selection | URL query pageID and TPEN.screen.pageInQuery | header, interface, selectors | header canvas selector, page navigation | +| Active line index | TPEN.activeLineIndex | header line indicator, interface, tools | tpen-transcription-block (`moveToLine()`), column selector | +| Interface UI mode (split-screen/tool selection) | tpen-simple-transcription local state | interface shell and tool pane | splitscreen events and UI interactions | +| Annotation page items for column ordering | component-local cached page object | column selector, transcription logic | vault fetch + ordering utility | + +## Minimal Knowledge Boundaries + +### Page Shell + +- Knows which top-level interface element to mount. +- Does not own transcription state. + +### Interface Shell (tpen-simple-transcription) + +- Owns orchestration state: active page data, active line, split-screen status. +- Coordinates events among header, workspace, and tools. +- Does not implement selector internals or tool internals. + +### Header (tpen-project-header) + +- Owns navigation controls and contextual display (project title, line indicator). +- Emits navigation changes through URL/event interactions. +- Does not render transcription content. + +### Selectors (layer, column, page/canvas) + +- Convert user input into selection events. +- Do not manage rendering of line content. + +### Workspace Components + +- tpen-transcription-block handles line transcription interactions. +- Image display (`#imgTop`, `#imgBottom`) is handled directly by tpen-simple-transcription via `adjustImages()`, `highlightActiveLine()`, and `resetImagePositions()`. +- tpen-workspace-tools handles tool launch and workspace actions. +- These components should not own global routing. + +### Transcription Block (tpen-transcription-block) + +- Owns line input rendering and text editing. +- Primary mutator of `TPEN.activeLineIndex` via `moveToLine()`. +- Emits line navigation events (`tpen-transcription-previous-line`, `tpen-transcription-next-line`) via `TPEN.eventDispatcher`. +- Does not manage image positioning or split-screen state. + +## Event Contracts (Core) + +Common orchestration events in the current implementation: + +- tpen-layer-changed +- tpen-column-selected +- tpen-transcription-previous-line +- tpen-transcription-next-line +- tpen-active-line-updated +- tools-dismiss +- splitscreen-toggle + +## Notes + +- Current header implementation includes layer and column selectors plus a canvas selector. +- The standalone tpen-page-selector exists as a reusable component but is not the primary selector in this specific header implementation. diff --git a/components/simple-transcription/DIAGRAMS.md b/components/simple-transcription/DIAGRAMS.md new file mode 100644 index 00000000..c20ba4ba --- /dev/null +++ b/components/simple-transcription/DIAGRAMS.md @@ -0,0 +1,71 @@ +# Transcription Interface Diagrams + +This file contains diagram-first references for external linking. + +## Composition Diagram + +```mermaid +flowchart TD + A[interfaces/transcription/index.html] --> B[tpen-simple-transcription] + + B --> C[tpen-project-header] + B --> D[Workspace Left Pane] + B --> E[Split-screen Right Pane] + + C --> C1[tpen-layer-selector] + C --> C2[tpen-column-selector] + C --> C3[Canvas selector] + C --> C4[Line indicator] + + D --> D1["#imgTop (focused line image)"] + D --> D2[tpen-transcription-block] + D --> D3[tpen-workspace-tools] + D --> D4["#imgBottom (remaining canvas)"] +``` + +## Data Ownership Diagram + +```mermaid +flowchart LR + P[TPEN.activeProject] --> H[tpen-project-header] + P --> L[tpen-layer-selector] + P --> C[tpen-column-selector] + P --> S[tpen-simple-transcription] + + U[URL pageID and TPEN.screen.pageInQuery] --> H + U --> S + U --> C + + A[TPEN.activeLineIndex] --> H + A --> S + + SSTATE[Interface local state: split-screen and active tool] --> S + + V[vault annotation/page cache] --> C + V --> S +``` + +## Event Flow Diagram + +```mermaid +flowchart TD + L[tpen-layer-selector] -- tpen-layer-changed --> S[tpen-simple-transcription] + C[tpen-column-selector] -- tpen-column-selected --> S + W[tpen-workspace-tools] -- splitscreen-toggle --> S + W -- tools-dismiss --> S + + T[tpen-transcription-block] -- tpen-transcription-next-line / previous-line --> S + T -- tpen-transcription-next-line / previous-line --> H[tpen-project-header] + + H -- URL pageID updates --> U[Browser URL] +``` + +## External Link Target + +Recommended issue link target: + +- components/simple-transcription/ARCHITECTURE.md + +Secondary diagram-only link: + +- components/simple-transcription/DIAGRAMS.md