Enhance H5P build page with user prompts for feedback and improved navigation; update styles for better layout and readability

Author: alekswebnet

docs/h5p-build-page.md

@@ -4,6 +4,8 @@
 
 The source is not uploaded: the package is built in the browser. A link can carry the source in its fragment, which no server sees: `/h5p/build/#source=<base64url>`, the bytes being the source's JSON as UTF-8, or that JSON compressed with raw deflate (Node's `zlib.deflateRawSync`, Python's `zlib.compressobj(wbits=-15)`) to keep the link short. A linked source is built at once, unless it names files of its own, which only the person can choose. A page opened by such a link keeps the fragment in step with the source as the person changes it, so the address can be copied to send the changed source on ([below](#the-source-editor)). A source that names a picture by web address gets it only where that host allows CORS.
 
+For a person with no source yet, the page gives a prompt to copy into a chat. It carries the address of [the skill page](h5p-skill.md) whole, which a chat's fetch tool needs, and `site.js` gives it a Copy button as it does a code block. Under the steps, and there before anything is built, the page says where a package plays with no H5P site, in a paragraph with two links: [h5p-offline-player](https://github.com/missing-elements/h5p-offline-player), the player it plays in here, is set up on a site of one's own (its setup guide), or is an app that plays with no network. Under that is where to say how it went, in two ways, since a teacher may have no GitHub account. The first is an email, which asks for none, to the address h5p-offline-player's code of conduct and security policy give. The second is a new discussion in h5p-offline-player, where the author is made, which is public. `buildFeedback` in [src/_data/site.js](../src/_data/site.js) writes both addresses, each with the same title and two questions to start from.
+
 | File | What it holds |
 | --- | --- |
 | [src/h5p/build/index.njk](../src/h5p/build/index.njk) | The page's markup, in the site's layout, and its Content-Security-Policy: GitHub Pages cannot send a Content-Security-Policy header for a site, so a `<meta>` tag is the only policy it gets |

e2e/build.spec.ts

@@ -118,6 +118,44 @@ test('a pasted source builds, plays and downloads', async ({ page, baseURL }) =>
   expect(problems, problems.join('\n')).toEqual([])
 })
 
+test('before anything is built the page gives a prompt to try, and says where a package plays and where to say how it went', async ({ page, context, baseURL }) => {
+  const { problems, elsewhere } = watch(page, baseURL)
+  await context.grantPermissions(['clipboard-read', 'clipboard-write'])
+  await page.goto('/h5p/build/')
+  // The prompt carries the skill's page at its whole address, which a chat's fetch tool needs, and its button copies it.
+  const prompt = page.locator('pre.prompt')
+  await expect(prompt).toHaveText('Read https://missing-elements.github.io/h5p/skill/ and follow it to make an H5P quiz with five questions about the rivers of Europe.')
+  await page.locator('.docs-header').getByRole('button', { name: 'Copy' }).click()
+  expect(await page.evaluate(() => navigator.clipboard.readText())).toBe(await prompt.textContent())
+
+  // With no H5P site: the player this page plays it in, in two links in a paragraph, to how to set it
+  // up on a site of one's own and to its app, offline.
+  const plays = page.getByRole('region', { name: 'Play it without an H5P site' })
+  await expect(plays.locator('p a')).toHaveCount(2)
+  await expect(plays.getByRole('link', { name: 'on a site of your own' })).toHaveAttribute('href', 'https://github.com/missing-elements/h5p-offline-player/blob/main/docs/setup.md')
+  await expect(plays.getByRole('link', { name: 'offline, in its app' })).toHaveAttribute('href', 'https://h5p-offline-player.vercel.app/app/')
+
+  // Feedback asks for no account: an email, with a subject and two questions to start from.
+  const feedback = page.getByRole('region', { name: 'How did it go?' })
+  const email = feedback.getByRole('link', { name: 'Email feedback' })
+  await expect(email).toBeVisible()
+  const letter = new URL((await email.getAttribute('href'))!)
+  expect(letter.protocol).toBe('mailto:')
+  expect(letter.pathname).toMatch(/^[^@\s]+@[^@\s]+$/)
+  expect(letter.searchParams.get('subject')).toBe('Feedback on the H5P build page')
+  expect(letter.searchParams.get('body')).toBe('What I made (the content type, and the chat that wrote the source):\r\n\r\n\r\nWhat went well, or wrong:\r\n\r\n')
+  // And for someone with a GitHub account, a new discussion where the author is made, which starts the same.
+  const discussion = new URL((await feedback.getByRole('link', { name: 'Discuss on GitHub' }).getAttribute('href'))!)
+  expect(discussion.origin + discussion.pathname).toBe('https://github.com/missing-elements/h5p-offline-player/discussions/new')
+  expect(discussion.searchParams.get('category')).toBe('general')
+  expect(discussion.searchParams.get('title')).toBe('Feedback on the H5P build page')
+  expect(discussion.searchParams.get('body')).toBe(letter.searchParams.get('body')!.replaceAll('\r\n', '\n'))
+
+  // They are links: the page still fetches nothing from another site.
+  expect(elsewhere, 'nothing was fetched from another site').toEqual([])
+  expect(problems, problems.join('\n')).toEqual([])
+})
+
 test('a source with problems gets them all listed, ready for the chat', async ({ page, context, request, baseURL }) => {
   const { problems } = watch(page, baseURL)
   await context.grantPermissions(['clipboard-read', 'clipboard-write'])

e2e/home.spec.ts

@@ -2,11 +2,9 @@ import { expect, test } from '@playwright/test'
 
 /*
  * The org home, /: a card for each element, one for each tool, the build page, and a footer of
- * links; and the build page links the skill's page at the whole address a person gives the chat.
+ * links; and the build page links the skill's page, which has no card of its own.
  */
 
-const SKILL = 'https://missing-elements.github.io/h5p/skill/'
-
 test('the home page links to the build page, and the build page to the skill’s page, and both answer', async ({ page, request }) => {
   await page.goto('/')
   await expect(page.getByRole('region', { name: 'Web components' }).getByRole('link', { name: 'pdfjs-viewer', exact: true })).toHaveAttribute('href', '/pdfjs-viewer/')
@@ -15,6 +13,6 @@ test('the home page links to the build page, and the build page to the skill’s
   expect((await request.get('/h5p/build/')).ok()).toBe(true)
 
   await page.goto('/h5p/build/')
-  await expect(page.getByRole('link', { name: SKILL, exact: true })).toHaveAttribute('href', SKILL)
+  await expect(page.getByRole('link', { name: "the h5p-author skill's page" })).toHaveAttribute('href', '/h5p/skill/')
   expect((await request.get('/h5p/skill/')).ok()).toBe(true)
 })

src/_data/site.js

@@ -1,3 +1,22 @@
+// The address the project answers at: the one h5p-offline-player's code of conduct and security
+// policy give, and the organization's on GitHub.
+const contact = "alekswebnet@gmail.com";
+
+// Where to say how the H5P build page and the h5p-author skill went, in two ways that start from
+// the same title and two questions. An email asks for no account, and a teacher may have none on
+// GitHub. A new discussion in h5p-offline-player, where the author is made, is public, for someone
+// who has one. A mail body's lines end in CRLF (RFC 6068).
+const feedbackTitle = "Feedback on the H5P build page";
+const feedbackBody = "What I made (the content type, and the chat that wrote the source):\n\n\nWhat went well, or wrong:\n\n";
+const buildFeedback = {
+  email:
+    `mailto:${contact}?subject=${encodeURIComponent(feedbackTitle)}` +
+    `&body=${encodeURIComponent(feedbackBody.replaceAll("\n", "\r\n"))}`,
+  github:
+    "https://github.com/missing-elements/h5p-offline-player/discussions/new?category=general" +
+    `&title=${encodeURIComponent(feedbackTitle)}&body=${encodeURIComponent(feedbackBody)}`,
+};
+
 export default {
   name: "Missing Elements",
   url: "https://missing-elements.github.io",
@@ -29,4 +48,5 @@ export default {
       repo: "https://github.com/missing-elements/missing-elements.github.io/blob/main/docs/h5p-build-page.md",
     },
   ],
+  buildFeedback,
 };

src/assets/site.css

@@ -547,24 +547,21 @@ tbody th a:hover code { text-decoration: underline; }
 .home section + section { margin-top: 3rem; }
 .home section > h2 { margin: 0 0 0.75rem; padding: 0; border: 0; font-size: 1.5rem; }
 .home section > p { max-width: var(--measure); margin: 0 0 1.25rem; color: var(--muted); }
-/* The cards two to a row where two fit, each as tall as its row, with its links at its foot. Every
-   section has the same two columns, so a section of one card keeps it the width of the others. */
-.home section { container-type: inline-size; }
-.elements {
+/* Cards: on the home page, the elements and the tools. Two to a row where two fit and never more,
+   so one alone keeps the width of the others. Each is as tall as its row, with its links at its
+   foot. */
+.cards {
   display: grid;
-  grid-template-columns: minmax(0, 1fr);
+  grid-template-columns: repeat(auto-fill, minmax(min(100%, max(18rem, calc((100% - 1rem) / 2))), 1fr));
   gap: 1rem;
   margin: 0;
   padding: 0;
   list-style: none;
 }
-@container (width > 36rem) {
-  .elements { grid-template-columns: repeat(2, minmax(0, 1fr)); }
-}
-.elements li { display: flex; flex-direction: column; margin: 0; padding: 1rem 1.25rem; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); }
-.elements h3 { margin: 0 0 0.25rem; font-size: 1.125rem; }
-.elements p { margin: 0 0 0.5rem; color: var(--muted); }
-.elements .links { display: flex; gap: 1rem; margin-top: auto; font-size: 0.875rem; }
+.cards > li { display: flex; flex-direction: column; margin: 0; padding: 1rem 1.25rem; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); }
+.cards :is(h3, h4) { margin: 0 0 0.25rem; font-size: 1.125rem; }
+.cards p { margin: 0 0 0.5rem; color: var(--muted); }
+.cards .links { display: flex; gap: 1rem; margin-top: auto; font-size: 0.875rem; }
 /* The home page's footer: where else the elements are, in columns of links. */
 .site-footer { margin-top: 4rem; padding-top: 1.5rem; border-top: 1px solid var(--border); font-size: 0.875rem; }
 .footer-links { display: flex; flex-wrap: wrap; gap: 1.5rem 4rem; }
@@ -583,6 +580,11 @@ tbody th a:hover code { text-decoration: underline; }
 /* Prose keeps a line a reader can follow; the source, the lists and what plays take the whole width. */
 :is(.build, .skill) p:not(.status) { max-width: var(--measure); }
 
+/* A prompt to copy for a chat, in a code block's frame for its Copy button: prose, so it wraps and
+   is no wider than the prose around it. */
+.docs-header :is(.code, pre) { max-width: var(--measure); }
+pre.prompt { white-space: pre-wrap; overflow-wrap: anywhere; }
+
 /* H5P build page, /h5p/build/ */
 .build {
   --ok: var(--live);
@@ -653,7 +655,7 @@ tbody th a:hover code { text-decoration: underline; }
   border: 0;
   font-size: 1.25rem;
 }
-.build h3 { margin: 1.5rem 0 0.5rem; font-size: 1rem; }
+.build .step h3 { margin: 1.5rem 0 0.5rem; font-size: 1rem; }
 .step-marker {
   position: absolute;
   top: 0;
@@ -796,6 +798,28 @@ tbody th a:hover code { text-decoration: underline; }
 .player-box { margin: 1rem 0; border: 1px solid var(--border); border-radius: var(--radius); overflow: hidden; background: #ffffff; }
 .player-box h5p-player { display: block; }
 
+/* Under the steps: where else what was built plays, its title the size of a step's, and a card of
+   its own for saying how it went, with its two buttons at its end, which share a row where it is
+   wide enough and take one each where it is not. */
+.plays h2 { font-size: 1.25rem; }
+.feedback {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem 1.5rem;
+  margin-top: 1rem;
+  padding: 1rem 1.25rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--surface);
+}
+.feedback > :first-child { flex: 1 1 28rem; }
+.feedback h2 { margin: 0 0 0.25rem; padding: 0; border: 0; font-size: 1.125rem; }
+.feedback p { margin: 0; color: var(--muted); }
+.feedback-actions { display: flex; flex-wrap: wrap; gap: 0.5rem; }
+.feedback-actions .button { flex: 1 1 auto; justify-content: center; }
+
 @media (max-width: 480px) {
   .step { --marker: 1.75rem; --indent: calc(var(--marker) + 0.75rem); }
   .step-marker { font-size: 0.8125rem; }

src/h5p/build/index.njk

@@ -27,11 +27,14 @@ csp: "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' da
       site takes. Nothing is uploaded: the package is built in your browser, from the libraries this
       site serves.
     </p>
-    {#- The skill's page at its whole address, which a person gives the chat as it is. -#}
+    {#- A prompt to copy, which site.js gives a Copy button as it does a code block. It carries the
+        skill's page at its whole address, which a chat's fetch tool needs. -#}
     <p>
-      No source yet? Give the chat <a href="{{ site.url }}/h5p/skill/">{{ site.url }}/h5p/skill/</a>
-      and ask it for an activity: the h5p-author skill there tells it how to write one.
+      <strong>No source yet?</strong> Paste this into an AI chat, with a subject of your own. It
+      sends the chat to <a href="/h5p/skill/">the h5p-author skill's page</a>, which tells it how
+      to write an activity.
     </p>
+    <pre class="language-text prompt" data-label="Prompt">Read {{ site.url }}/h5p/skill/ and follow it to make an H5P quiz with five questions about the rivers of Europe.</pre>
   </header>
 
   {#- The steps are drawn as a timeline by site.css: a marker for each, on a rail that runs on to
@@ -104,6 +107,35 @@ csp: "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' da
     </p>
   </section>
 
+  {#- Under the steps, and there before anything is built: where else a package plays, with no H5P
+      site, which is h5p-offline-player, the player this page plays it in; and where to say how
+      the build went. -#}
+  <section class="plays" aria-labelledby="plays-heading">
+    <h2 id="plays-heading">Play it without an H5P site</h2>
+    <p>
+      Any H5P site takes the file you download. With none, use h5p-offline-player, the player this
+      page plays it in:
+      <a href="https://github.com/missing-elements/h5p-offline-player/blob/main/docs/setup.md">on a site of your own</a>,
+      or <a href="https://h5p-offline-player.vercel.app/app/">offline, in its app</a>.
+    </p>
+  </section>
+
+  {#- Two ways, the email first: it asks for no account, and a teacher may have none on GitHub. -#}
+  <section class="feedback" aria-labelledby="feedback-heading">
+    <div>
+      <h2 id="feedback-heading">How did it go?</h2>
+      <p>
+        Say what you made, and what went well or wrong with the chat's source or this page. Write
+        to the author or, with a GitHub
+        account, start a public discussion where the h5p-author skill is made.
+      </p>
+    </div>
+    <div class="feedback-actions">
+      <a class="button button-primary button-large" href="{{ site.buildFeedback.email }}">Email feedback</a>
+      <a class="button button-large" href="{{ site.buildFeedback.github }}">Discuss on GitHub</a>
+    </div>
+  </section>
+
   <footer class="docs-footer">
     <p>
       Built with <a href="https://github.com/missing-elements/h5p-offline-player">h5p-offline-player</a>

src/index.njk

@@ -10,7 +10,7 @@ description: Standalone, self-hostable web components for viewing documents and
 
   <section aria-labelledby="elements-heading">
     <h2 id="elements-heading">Web components</h2>
-    <ul class="elements" role="list">
+    <ul class="cards" role="list">
       {%- for element in site.elements %}
       <li>
         <h3><a href="{{ element.docs }}">{{ element.name }}</a></h3>
@@ -27,7 +27,7 @@ description: Standalone, self-hostable web components for viewing documents and
   <section aria-labelledby="tools-heading">
     <h2 id="tools-heading">Tools</h2>
     <p>Apps built on the elements, which run in your browser.</p>
-    <ul class="elements" role="list">
+    <ul class="cards" role="list">
       {%- for tool in site.tools %}
       <li>
         <h3><a href="{{ tool.page }}">{{ tool.name }}</a></h3>