Skip to content

Add the HTML and CSS preview block - #243

Merged
AQIB-NAWAB merged 1 commit into
mainfrom
feat/html-preview-block
Nov 18, 2026
Merged

AQIB-NAWAB merged 1 commit into
mainfrom
feat/html-preview-block

Conversation

@AQIB-NAWAB

Copy link
Copy Markdown
Collaborator

What this adds

A lesson can write a fenced preview block, and the reader draws it as a small browser window with real HTML and CSS. The code can sit beside it (mode: split, with a Hide code button) or be hidden (mode: preview). Optional sliders and dropdowns fill {{name}} placeholders in the code, so a learner changes one value and sees the code and the result change together.

```preview
title: Padding and margin
mode: split
slider: pad | Padding | 0 | 60 | 2 | 20 | px
---html
<p class="card">Hello</p>
---css
.card { padding: {{pad}}; }
```

It is built for the CSS Fundamentals and HTML Foundations courses (53 examples between them, already merged in devweekends/Edorax-core as plain fences) and works for any course. Full syntax: docs/html-preview-block.md.

How it is built

  • server/src/shared/html-preview/spec.ts (shared): parses the fence, checks it, fills placeholders, builds the frame document.
  • server/src/shared/mdx/remark-html-preview.ts (shared): turns the fence into an HtmlPreview element. It is added to readerRemarkPlugins, so web and desktop get it. An invalid fence throws, so it fails when the course is validated.
  • packages/learning-ui/.../content-blocks/html-preview.tsx: the block, registered in sharedLessonBlocks and the MDX allowlist. server/scripts/validate-course-source.ts runs the plugin too.
  • Generated copies refreshed with pnpm sync-shared.

Safety

The example is read-only author content, never learner input. The frame uses sandbox="" (no scripts, forms, popups or same-origin access), a content policy of default-src 'none' (no network, only inline styles and data: images), and links are switched off. The source is also refused if it has script tags, on...= attributes, iframe, link, meta, base, @import, javascript: addresses or web addresses in src, href or url(). The check runs when the course is parsed and again when the block is drawn; a refused example shows a plain message instead of a frame.

Tests

  • Server: new tests/unit/shared/mdx/html-preview.test.ts (parsing, controls, forbidden content, templates, frame document, remark plugin, registration). All 356 shared unit tests pass; pnpm sync-shared:check and the server type check are clean.
  • Frontend: new tests/unit/mdx/html-preview.test.ts (sandbox attribute, policy, controls, preview-only mode, refusal) and the existing allowlist-in-step test pass.
  • One existing file, tests/unit/shared/mdx/remark-learning-log.test.ts, fails to start in a fresh checkout because the generated Prisma client file is missing. It is not touched by this change.
  • Checked by eye: all 49 CSS and 27 HTML lessons opened in Chrome through the instructor preview with all 53 examples drawn and no block errors, in a local build.

Not done

  • Not tested: the desktop app, phone layout, keyboard and screen reader use.
  • The reader still shows the course project goal above each lesson; that is a separate change.

A lesson can write a fenced `preview` block and the reader draws it as a
small browser window, with the code beside it (split) or hidden (preview).
Optional sliders and dropdowns fill {{name}} placeholders in the HTML and
CSS, so a learner can change one value and see the result and the code
change together.

The example is drawn in an iframe with sandbox="" and a default-src
'none' content policy, with links switched off. The source is refused when
it contains script tags, event attributes, embedded content, link, meta,
base, @import, javascript: addresses or web addresses. An invalid fence
fails when the course is validated.

Adds the spec and remark plugin (shared), the HtmlPreview block (web and
desktop through the shared lesson blocks), the allowlist entry, the course
source validator hook, unit tests, and a short doc.
@AQIB-NAWAB
AQIB-NAWAB merged commit e3894bd into main Nov 18, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant