@lernapps/app-templates 0.0.0-stage → 0.1.0

package/interactive/docs/arc42/05-interactive-building-blocks.arc42.md

@@ -0,0 +1,518 @@
+# Building Blocks
+
+The interactive archetype's extension of the generic architecture (`docs/arc42/` at the root of
+`lernapps/app-templates`): an app whose doing is the content, with a static start page, one app page on which the
+shell runs the app's deterministic core and shows its state with the app's Vue components, and hash routes for modes
+and levels. The runtime `runtime/interactive/` ships the build step, the pages, the shell and the end-to-end tests; the
+creator writes the description, the core, the UI, the data, the messages and the playthroughs, and `src/main.ts`, which
+calls `startInteractive`. It reuses the explainer's component rules; the tutor handoff, task numbers, exercise contract
+and the examples check are not built for it (its playthroughs take the examples' role). Only the start page reads
+without JavaScript. An interactive app adds its own blocks below `bb-interactive-core`, `bb-interactive-ui` and
+`bb-interactive-data`: an app gets this architecture as a copy, and writes its own part between the markers
+`<!-- app: begin … -->` and `<!-- app: end … -->` in it (here inside the sections of the core, the UI and the data and
+at the end of each chapter), which the tooling keeps when it replaces the rest. The creator's assistant follows the
+skill `lernapps-interactive` (`if-skills`).
+
+## Level 1 (interactive app)
+
+```arc42
+:::diagram
+id: building-blocks-interactive-level-1
+view: building-block
+notation: mermaid
+:::
+```
+
+```mermaid
+flowchart TB
+    subgraph bb-runtime["Shared runtime"]
+        bb-component-rules["Component rules"]
+    end
+    bb-tooling["Tooling helpers"]
+    bb-archetype-runtime["Interactive runtime"]
+    bb-interactive-description["Description"]
+    bb-interactive-core["Core"]
+    bb-interactive-ui["UI"]
+    bb-interactive-data["Data"]
+    bb-interactive-messages["Messages"]
+    bb-interactive-playthroughs["Playthroughs"]
+    bb-archetype-runtime -->|"if-shared-runtime"| bb-runtime
+    bb-archetype-runtime -->|"if-component-rules"| bb-component-rules
+    bb-archetype-runtime -->|"if-preset"| bb-tooling
+    bb-interactive-core -->|"if-interactive-data"| bb-interactive-data
+    bb-interactive-ui -->|"if-messages"| bb-interactive-messages
+    bb-interactive-ui -->|"if-a11y"| bb-tooling
+    bb-interactive-ui -->|"if-translator"| bb-tooling
+```
+
+## Level 2: the interactive runtime
+
+```arc42
+:::diagram
+id: building-blocks-interactive-runtime
+view: building-block
+notation: mermaid
+:::
+```
+
+```mermaid
+flowchart TB
+    subgraph bb-archetype-runtime["Interactive runtime"]
+        bb-build["Build step"]
+        bb-validation["Description validation"]
+        bb-render["Page rendering"]
+        bb-shell["Shell"]
+        bb-e2e["End-to-end tests"]
+        bb-runtime-texts["Runtime texts"]
+    end
+    bb-interactive-description["Description"]
+    bb-interactive-core["Core"]
+    bb-interactive-ui["UI"]
+    bb-interactive-playthroughs["Playthroughs"]
+    bb-tooling["Tooling helpers"]
+    bb-build -->|"if-archetype-content"| bb-interactive-description
+    bb-build -->|"if-playthrough-format"| bb-interactive-playthroughs
+    bb-build -->|"if-core-contract"| bb-interactive-core
+    bb-validation -->|"if-archetype-content"| bb-interactive-description
+    bb-validation -->|"if-playthrough-format"| bb-interactive-playthroughs
+    bb-validation -->|"if-runtime-texts"| bb-runtime-texts
+    bb-render -->|"if-archetype-content"| bb-interactive-description
+    bb-render -->|"if-runtime-texts"| bb-runtime-texts
+    bb-shell -->|"if-core-contract"| bb-interactive-core
+    bb-shell -->|"if-root-component"| bb-interactive-ui
+    bb-e2e -->|"if-archetype-content"| bb-interactive-description
+    bb-e2e -->|"if-playthrough-format"| bb-interactive-playthroughs
+    bb-e2e -->|"if-state-property"| bb-shell
+    bb-e2e -->|"if-test-clock"| bb-shell
+    bb-e2e -->|"if-runtime-texts"| bb-runtime-texts
+    bb-e2e -->|"if-a11y"| bb-tooling
+```
+
+## Interactive runtime
+
+Built. The runtime of every interactive app, which the app does not change: it builds the pages, runs the build
+checks, starts the app's core and UI in the browser and brings the end-to-end tests.
+
+```arc42
+:::building-block
+id: bb-archetype-runtime
+title: Interactive runtime
+path: runtime/interactive
+technology: TypeScript, Vite plugin, Vue
+requires: if-shared-runtime, if-preset, if-component-rules
+implements: concept-archetype-extension
+:::
+```
+
+### Build step
+
+Built. The plugin `interactive()` reads `src/app.yaml` and the playthroughs, runs the component rules on the UI, loads
+the core in a Vite server of its own and checks its exports and that every route starts, plays every playthrough
+against the core twice, each step's inputs through `step` and then its ticks through `tick(state, 20)`, and fails when
+the two plays differ or a state differs from the expected one, and only then writes the start page, the app page and
+the 404 page. No time passes but the ticks a step names. An app's code has no size limit (`dec-no-size-limit`).
+
+```arc42
+:::building-block
+id: bb-build
+title: Build step
+parent: bb-archetype-runtime
+path: runtime/interactive/plugin.ts
+technology: Vite plugin
+requires: if-archetype-content, if-playthrough-format, if-core-contract, if-component-rules
+implements: concept-playthroughs, concept-determinism
+:::
+```
+
+#### Build plugin interface
+
+The app's vite.config.ts adds `interactive()` to the tooling preset; that is the only way the app enters the build.
+
+```arc42
+:::interface
+id: if-build-plugin
+title: interactive() Vite plugin
+provider: bb-build
+protocol: TypeScript import, @lernapps/app-templates/interactive/plugin
+path: runtime/interactive/plugin.ts
+:::
+```
+
+### Description validation
+
+Built. Validates `src/app.yaml` and every playthrough against their JSON schemas, then German first, complete
+languages, unique ids, at least one playthrough, each step expecting something, and known routes; one line per
+problem with file and line.
+
+```arc42
+:::building-block
+id: bb-validation
+title: Description validation
+parent: bb-archetype-runtime
+path: runtime/interactive/load.ts
+technology: Ajv, JSON Schema, YAML
+requires: if-archetype-content, if-playthrough-format, if-runtime-texts
+:::
+```
+
+### Page rendering
+
+Built. Renders, in each language, the start page (what the app does, the link into the app, the routes, how to play,
+competencies, background sections, a `<noscript>` note and no script) and the app page (title, `<noscript>` note with
+a link back, the routes as anchor links, and the element the shell mounts into, carrying the route ids).
+
+```arc42
+:::building-block
+id: bb-render
+title: Page rendering
+parent: bb-archetype-runtime
+path: runtime/interactive/render.ts
+technology: TypeScript, HTML
+requires: if-archetype-content, if-runtime-texts
+implements: concept-readable-without-js, concept-hash-routes, concept-accessibility
+:::
+```
+
+#### Pages interface
+
+Learners, teachers and parents read the start page at `lernapps.net/<repo>/` and play at
+`app/?seed=<n>#<route>`; the catalog entry's topics link to the routes.
+
+```arc42
+:::interface
+id: if-pages
+title: Start page and app page app/?seed=<n>#<route>
+provider: bb-render
+protocol: HTML pages over HTTPS (query and hash)
+path: runtime/interactive/render.ts
+:::
+```
+
+### Shell
+
+Built. `startInteractive(core, root)` mounts the root component on the app page and holds the core's state; it takes
+the seed from `?seed=<n>` (else a random one) and the route from the hash (else the first route), starts the core
+again on a new route, calls `tick(state, 20)` every 20 ms when the core has `tick`, and routes typed inputs to `step`
+(`dec-typed-input`): every key typed on the page as a key input, except on links, buttons and form fields or with
+Ctrl, Alt or Meta, and every input the root component emits as `input` (an action, or a key it stands for). When the
+end-to-end tests' clock is on the page (`if-test-clock`), it starts no interval and steps the ticks the tests ask for.
+
+The app page has a heading line: the h1, the app's title, and a slot beside it, hidden and empty. An app that wants a
+small control there (help, sound off) passes a component as `startInteractive(core, App, { title })`; the shell
+mounts it into the slot with the props `state` and `lang` and the same `input` event as the root component, and shows
+the slot. The header of both pages holds the language switch and nothing else, and an app with one language has none:
+the title is the h1, and the way back to the catalog is the platform's. The frame of the header, the page and the
+footer is as wide as the custom property `--page-max-width` (default `44rem`), which an app sets in its own
+`:root` rule.
+
+```arc42
+:::building-block
+id: bb-shell
+title: Shell
+parent: bb-archetype-runtime
+path: runtime/interactive/interactive.ts
+technology: TypeScript, Vue, DOM events
+requires: if-core-contract, if-root-component
+implements: concept-core-and-shell, concept-hash-routes, concept-determinism
+:::
+```
+
+#### Start interface
+
+The app's `src/main.ts` imports the runtime's style, the core and the root component and calls `startInteractive`.
+
+```arc42
+:::interface
+id: if-start
+title: startInteractive(core, root, options?)
+provider: bb-shell
+protocol: TypeScript import, @lernapps/app-templates/interactive
+path: runtime/interactive/interactive.ts
+:::
+```
+
+#### Test clock
+
+Before the client module runs, the end-to-end tests put an object on the page as the global `lernappsClock`; the
+shell then starts no interval and gives that object `tick(count)`, which calls the shell's own tick `count` times. No
+time passes in the browser but the ticks a playthrough step names, as in the build. Only the tests set it.
+
+```arc42
+:::interface
+id: if-test-clock
+title: lernappsClock, the end-to-end tests' clock
+provider: bb-shell
+protocol: global object with tick(count)
+path: runtime/interactive/contract.ts
+:::
+```
+
+#### State property
+
+The shell mirrors the state on the app's element as `lernappsState`, which the end-to-end tests read.
+
+```arc42
+:::ignore H020 the state property, the test clock and the core contract are all defined in contract.ts, the runtime's one contract module
+:::
+:::interface
+id: if-state-property
+title: lernappsState on the app element
+provider: bb-shell
+protocol: DOM property
+path: runtime/interactive/contract.ts
+:::
+```
+
+### End-to-end tests
+
+Built. `interactiveTests()` checks the start page and the app page without JavaScript in every language and plays
+every playthrough's steps in the browser on the test clock (`if-test-clock`): a key input pressed on the keyboard, an
+action emitted as `input` by the root component, as the component itself does, then the step's ticks; after each step
+it compares the state and the polite announcement, at desktop width and 360 px.
+
+```arc42
+:::building-block
+id: bb-e2e
+title: End-to-end tests
+parent: bb-archetype-runtime
+path: runtime/interactive/e2e.ts
+technology: Playwright
+requires: if-archetype-content, if-playthrough-format, if-state-property, if-test-clock, if-runtime-texts, if-a11y
+implements: concept-playthroughs
+:::
+```
+
+#### Tests interface
+
+The app's `e2e/interactive.e2e.ts` only calls `interactiveTests()`.
+
+```arc42
+:::interface
+id: if-e2e-tests
+title: interactiveTests()
+provider: bb-e2e
+protocol: TypeScript import, @lernapps/app-templates/interactive/e2e
+path: runtime/interactive/e2e.ts
+:::
+```
+
+### Runtime texts
+
+Built. The runtime's own learner texts in German and English; an app may declare only these languages.
+
+```arc42
+:::building-block
+id: bb-runtime-texts
+title: Runtime texts
+parent: bb-archetype-runtime
+path: runtime/interactive/messages.ts
+technology: JSON per language
+implements: concept-languages
+:::
+```
+
+#### Runtime texts interface
+
+The pages, the validation and the tests take the runtime's texts by key and language.
+
+```arc42
+:::interface
+id: if-runtime-texts
+title: Runtime texts by language
+provider: bb-runtime-texts
+protocol: TypeScript import, JSON
+path: runtime/interactive/messages
+:::
+```
+
+## Description
+
+Built in the template: `src/app.yaml` says what the start page shows, the languages and the routes.
+
+```arc42
+:::building-block
+id: bb-interactive-description
+title: Description
+technology: YAML
+path: interactive/src/app.yaml
+:::
+```
+
+### App description interface
+
+The interactive archetype's content: the build, the validation, the pages and the tests read the app's description
+only through this schema.
+
+```arc42
+:::interface
+id: if-archetype-content
+title: app.yaml (interactive.v1 schema)
+provider: bb-interactive-description
+protocol: YAML, JSON Schema
+path: runtime/interactive/interactive.v1.schema.json
+:::
+```
+
+## Core
+
+Built in the template. The app's logic, pure TypeScript without DOM, deterministic by its seed, its state plain JSON,
+so that it can be played and tested in Node and in the browser alike; it reads the app's data.
+
+```arc42
+:::building-block
+id: bb-interactive-core
+title: Core
+technology: TypeScript
+requires: if-interactive-data
+implements: concept-core-and-shell, concept-determinism
+path: interactive/src/core
+:::
+```
+
+### Core contract
+
+The core exports `start(seed, route)`, `step(state, input)` and, when the app moves on its own, `tick(state, dt)`.
+The input is typed and extensible (`dec-typed-input`): `{ kind: "key", key }` with the key as `KeyboardEvent.key`, or
+`{ kind: "action", name, value? }` for what the learner does with the pointer or by touch; a core handles the kinds it
+knows and returns the state unchanged for any other, so new kinds can come.
+
+```arc42
+:::ignore H020 the core contract, the state property and the test clock are all defined in contract.ts, the runtime's one contract module
+:::
+:::interface
+id: if-core-contract
+title: Core contract start, step, tick
+provider: bb-interactive-core
+protocol: TypeScript module exports
+path: runtime/interactive/contract.ts
+:::
+```
+
+<!-- app: begin core -->
+<!-- app: end core -->
+
+## UI
+
+Built in the template. Vue components that show the state and translate the device's input (keys, pointer, touch, …)
+into inputs; free in how they render (DOM, SVG, canvas). They may remember something through the small storage; the
+template does not.
+
+```arc42
+:::building-block
+id: bb-interactive-ui
+title: UI
+technology: Vue single-file components
+requires: if-a11y, if-translator, if-messages
+implements: concept-component-rules, concept-accessibility
+path: interactive/src/ui
+:::
+```
+
+### Root component
+
+The root component takes the props `state` and `lang` and emits `input` with an input (an action, or a key).
+
+```arc42
+:::ignore H014 the contract has no file of its own: its props are set in runtime/interactive/interactive.ts (if-start's file), the component is the app's
+:::
+:::interface
+id: if-root-component
+title: Root component (state, lang, input)
+provider: bb-interactive-ui
+protocol: Vue props and events
+:::
+```
+
+<!-- app: begin ui -->
+<!-- app: end ui -->
+
+## Data
+
+Built in the template. The app's content as data in its own format (lessons, texts with their faulty versions).
+
+```arc42
+:::building-block
+id: bb-interactive-data
+title: Data
+technology: JSON
+path: interactive/src/data
+:::
+```
+
+### App data
+
+The core imports the data files as JSON modules, so they are bundled and checked with the core.
+
+```arc42
+:::interface
+id: if-interactive-data
+title: Data files (JSON imports)
+provider: bb-interactive-data
+protocol: JSON module import
+path: interactive/src/data
+:::
+```
+
+<!-- app: begin data -->
+<!-- app: end data -->
+
+## Messages
+
+Built in the template. The app's learner texts by language, read through the translator.
+
+```arc42
+:::building-block
+id: bb-interactive-messages
+title: Messages
+technology: JSON
+implements: concept-languages
+path: interactive/src/messages
+:::
+```
+
+### Message files
+
+The UI imports one message file per language and hands it to the translator.
+
+```arc42
+:::interface
+id: if-messages
+title: Message files by language
+provider: bb-interactive-messages
+protocol: JSON module import
+path: interactive/src/messages
+:::
+```
+
+## Playthroughs
+
+Built in the template. Playthroughs as data: a seed, a route and steps of inputs (`keys` as the short form of key
+inputs, or `inputs`) and ticks that pass after them, with the state or announcement expected after each step. The
+template's playthrough lets a letter go late and starts a round with the action `again`.
+
+```arc42
+:::building-block
+id: bb-interactive-playthroughs
+title: Playthroughs
+technology: YAML
+implements: concept-playthroughs
+path: interactive/src/playthroughs
+:::
+```
+
+### Playthrough format
+
+The build and the end-to-end tests read playthroughs in this format.
+
+```arc42
+:::interface
+id: if-playthrough-format
+title: Playthrough (playthrough.v1 schema)
+provider: bb-interactive-playthroughs
+protocol: YAML, JSON Schema
+path: runtime/interactive/playthrough.v1.schema.json
+:::
+```
+
+<!-- app: begin -->
+<!-- app: end -->

package/interactive/docs/arc42/06-interactive-runtime-view.arc42.md

@@ -0,0 +1,58 @@
+# Runtime View
+
+The interactive archetype's own scenarios, besides the generic ones.
+
+## Playing on the app page
+
+The learner opens `app/`, possibly with `?seed=<n>` and `#<route>`. `src/main.ts` calls `startInteractive`, which
+takes the seed from the address (else a random one) and the route from the hash (else the first route), starts the
+core and mounts the root component with the state and the page's language. Components translate any device input
+(pointer, touch, …) into typed inputs for `step` (`dec-typed-input`): the shell gives every key typed on the page to
+`step` as a key input, except keys on links, buttons and form fields or with Ctrl, Alt or Meta, and steps every input
+the root component emits as `input`; a key that changes the state loses its default. When the core
+has `tick`, the shell calls it every 20 ms. A new route in the hash starts the core again with the same seed and marks
+the current route link. The components only show the state, take their texts through the translator and announce
+changes through the live region.
+
+```arc42
+:::runtime-scenario
+id: scenario-play
+title: Playing on the app page (input, ticks, route change)
+trigger: The learner opens the app page, gives an input, or follows a route link
+involves: bb-render, bb-shell, bb-interactive-core, bb-interactive-data, bb-interactive-ui, bb-interactive-messages, bb-tooling
+:::
+```
+
+## Building with the playthroughs
+
+The `interactive()` plugin validates `src/app.yaml` and the playthroughs, runs the component rules on the UI, loads
+the core in a Vite server of its own, checks its exports and that every route starts, and plays every playthrough
+twice, each step's inputs and then its ticks, comparing the two plays and the expected states, before it writes the start page and the app
+page with the runtime's texts.
+
+```arc42
+:::runtime-scenario
+id: scenario-interactive-build
+title: Building with the playthroughs
+trigger: The creator, a git hook or CI runs the build
+involves: bb-build, bb-validation, bb-component-rules, bb-interactive-description, bb-interactive-core, bb-interactive-playthroughs, bb-render, bb-runtime-texts
+:::
+```
+
+## Browser playthroughs
+
+`interactiveTests()` checks the start page and the app page without JavaScript in every language, then opens each
+playthrough at `app/?seed=<seed>#<route>` on the test clock, gives its inputs (keys pressed on the keyboard, actions
+emitted by the root component) and its ticks, and compares, after each step, the state read from `lernappsState` and the announcement of the polite live region.
+
+```arc42
+:::runtime-scenario
+id: scenario-browser-playthroughs
+title: Browser playthroughs in the end-to-end tests
+trigger: The pre-push hook or CI runs lernapps check --pre-push
+involves: bb-e2e, bb-interactive-description, bb-interactive-playthroughs, bb-shell, bb-interactive-core, bb-interactive-ui, bb-runtime-texts, bb-tooling
+:::
+```
+
+<!-- app: begin -->
+<!-- app: end -->

package/interactive/docs/arc42/07-interactive-deployment-view.arc42.md

@@ -0,0 +1,35 @@
+# Deployment View
+
+Where the interactive archetype's blocks run, below the generic nodes.
+
+## Interactive build
+
+The build step with its checks and the end-to-end tests run in CI and, through the same hooks, on the creator's
+machine; the app's description, code, data and playthroughs are built and played there.
+
+```arc42
+:::deployment-node
+id: dn-interactive-build
+title: Interactive build
+type: container
+parent: dn-ci-runner
+hosts: bb-interactive-description, bb-interactive-core, bb-interactive-ui, bb-interactive-data, bb-interactive-messages, bb-interactive-playthroughs
+:::
+```
+
+## Interactive app page
+
+The shell, the core and the UI run in the learner's browser on the app page.
+
+```arc42
+:::deployment-node
+id: dn-interactive-app-page
+title: Interactive app page
+type: container
+parent: dn-learner-browser
+hosts: bb-shell, bb-interactive-core, bb-interactive-ui, bb-interactive-data, bb-interactive-messages
+:::
+```
+
+<!-- app: begin -->
+<!-- app: end -->

package/interactive/docs/arc42/08-interactive-concepts.arc42.md

@@ -0,0 +1,52 @@
+# Cross-cutting Concepts
+
+The interactive archetype's concepts, besides the generic ones.
+
+## Core and shell
+
+The core is the app's logic in pure TypeScript without DOM, its state plain JSON, exported as `start(seed, route)`,
+`step(state, input)` and optionally `tick(state, dt)`. The input is typed and extensible: a key, a pointer or touch
+action, and other kinds later; the components translate any device input into such inputs (`dec-typed-input`). The
+shell keeps the state, feeds it inputs and ticks and hands it to the components, which only show it, so the same core
+runs in Node at build and in the browser.
+
+```arc42
+:::concept
+id: concept-core-and-shell
+title: Core and shell
+category: structure
+:::
+```
+
+## Playthroughs
+
+A playthrough is data: a seed, a route and steps of inputs, each with the state (a part of it) or the announcement
+expected after them. The build plays it against the core, the end-to-end tests give the same inputs in the browser,
+so behaviour is specified once and checked in both places. A step can let n ticks pass after its inputs; in the build
+and in the browser no other time passes, so a real-time core is checked deterministically. The core's property tests
+over fixed seeds are not built yet.
+
+```arc42
+:::concept
+id: concept-playthroughs
+title: Playthroughs as data
+category: testing
+:::
+```
+
+## Hash routes
+
+Modes and levels are routes declared in `src/app.yaml`, reached as `app/#<id>` from anchor links on the start page and
+the app page. The shell starts the core with the route of the address (else the first) and again on every new route,
+so an entry's topics can point to a route and `entry-links-resolve` can check it.
+
+```arc42
+:::concept
+id: concept-hash-routes
+title: Hash routes
+category: navigation
+:::
+```
+
+<!-- app: begin -->
+<!-- app: end -->