| 1 | # React Wrapper Notes |
| 2 | |
| 3 | This directory contains the `@revealjs/react` wrapper. Keep the guidance here high level and update it when the public API, source layout, or Reveal/React synchronization model changes. |
| 4 | |
| 5 | ## Current Layout |
| 6 | |
| 7 | - Source lives under `react/src/`. |
| 8 | - Components live in `react/src/components/` and use kebab-case filenames. |
| 9 | - Shared helpers live in `react/src/utils/`. |
| 10 | - Public exports are defined in `react/src/index.ts`. |
| 11 | - Shared types live in `react/src/types.ts`. |
| 12 | - The Reveal instance context lives in `react/src/reveal-context.ts`. |
| 13 | - Component tests are colocated with their components as `*.test.tsx`. |
| 14 | - Test setup remains in `react/src/__tests__/setup.ts`. |
| 15 | - The demo app lives in `react/demo/src/`. |
| 16 | |
| 17 | ## Source Of Truth |
| 18 | |
| 19 | - Implementation: |
| 20 | - `react/src/components/deck.tsx` |
| 21 | - `react/src/components/slide.tsx` |
| 22 | - `react/src/components/stack.tsx` |
| 23 | - `react/src/components/fragment.tsx` |
| 24 | - `react/src/components/code.tsx` |
| 25 | - `react/src/components/markdown.tsx` |
| 26 | - Shared helpers: |
| 27 | - `react/src/utils/slide-attributes.ts` |
| 28 | - `react/src/utils/markdown.ts` |
| 29 | - Behavioral tests: |
| 30 | - `react/src/components/deck.test.tsx` |
| 31 | - `react/src/components/slide.test.tsx` |
| 32 | - `react/src/components/fragment.test.tsx` |
| 33 | - `react/src/components/code.test.tsx` |
| 34 | - `react/src/components/markdown.test.tsx` |
| 35 | - Public-facing behavior summary: |
| 36 | - `react/README.md` |
| 37 | |
| 38 | ## Deck Lifecycle Invariants |
| 39 | |
| 40 | - `Deck` creates one `Reveal` instance on mount and destroys it on unmount. |
| 41 | - `Deck` must remain safe under React `StrictMode`; do not reintroduce double initialization. |
| 42 | - Event props are wired with `deck.on()` after initialization and cleaned up with `deck.off()` when callbacks change or the component unmounts. |
| 43 | |
| 44 | ## Sync Policy |
| 45 | |
| 46 | - `Reveal.sync()` is expensive. Call it rarely. |
| 47 | - `Deck` should only call `sync()` when the rendered slide structure changes. |
| 48 | - Example: slides added, removed, reordered, or regrouped into or out of vertical stacks. |
| 49 | - Ordinary React content updates inside an existing slide must not trigger a full deck sync. |
| 50 | - One deck-level sync is still expected once the deck is ready. |
| 51 | |
| 52 | ## Configure Policy |
| 53 | |
| 54 | - `config` is shallow-compared. |
| 55 | - Recreating a config object with the same shallow values must not call `configure()`. |
| 56 | - `configure()` should only run after the deck is initialized and ready. |
| 57 | - `configure()` performs its own Reveal-side sync, so the wrapper must avoid an immediate redundant `sync()` afterward. |
| 58 | |
| 59 | ## Component Responsibilities |
| 60 | |
| 61 | - `Deck` owns Reveal lifecycle, config application, event wiring, and structure-level sync. |
| 62 | - `Slide` owns slide-local attribute mapping and calls `syncSlide()` only when the effective slide `data-*` attributes change after mount. |
| 63 | - `Markdown` mirrors the core Reveal Markdown plugin behavior in React. |
| 64 | - It is responsible for markdown parsing, separator support, notes support, and comment-based `.slide:` and `.element:` attributes. |
| 65 | - It should keep markdown-specific DOM post-processing local rather than expanding deck-wide sync behavior. |
| 66 | - `Code` owns explicit code block rendering and Reveal highlight integration for non-markdown code blocks. |
| 67 | - `Stack` and `Fragment` should stay lightweight unless there is a strong reason otherwise. |
| 68 | |
| 69 | ## Markdown And Highlighting Notes |
| 70 | |
| 71 | - Markdown behavior should stay aligned with the core Reveal Markdown plugin unless the React API intentionally diverges. |
| 72 | - Markdown slide parsing and comment-based attribute helpers belong in `react/src/utils/markdown.ts`. |
| 73 | - Markdown code highlighting should recover on rerender and after Reveal becomes available, without requiring a full deck sync. |
| 74 | |
| 75 | ## When Changing Behavior |
| 76 | |
| 77 | - If sync, configure, markdown, or highlight behavior changes, update the relevant colocated tests in the same change. |
| 78 | - If the public React API or documented behavior changes, update `react/README.md`. |
| 79 | - Prefer focused regression tests over broad snapshots. |
| 80 | |
| 81 | ## Validation |
| 82 | |
| 83 | Run these after React wrapper changes: |
| 84 | |
| 85 | - `npm test --prefix react` |
| 86 | - `npm run build --prefix react` |
| 87 |