@abreen/tada 1.14.2 → 1.15.0

package/README.md

@@ -27,7 +27,7 @@ A static site generator. The successor to Presto.
   * Renders step-by-step source highlighting, output, and memory diagrams
 - Slides mode: separate content by `---` and present sections as full-screen slides
 - PDF files are copied into `dist/`
-  - Text of each PDF page is extracted using `mutool` (if present) and indexed
+  * Text of each PDF page is extracted using `mutool` (if present) and indexed
 - External link handling (special visual treatment for external links)
 - Internal link validation at build time (broken links fail the build)
 - Internal links automatically prefixed with base path, if specified
@@ -37,7 +37,8 @@ A static site generator. The successor to Presto.
   * `<<< details ... <<<` renders a collapsible box
   * `::: section ... :::` renders a special section with a fancy background
   * `!!! note ... !!!` and `!!! warning ... !!!` render alert boxes
-  * `??? question ... ???` renders a Q & A section; answers hidden until click
+  * `??? question ... ???` renders a Q&A section; answer is hidden until click
+    - To display clickable multiple choice options, use a [task list][task-list]
   * `+++ ... +++ ... +++` renders a two-column layout
   * Special heading subtitles with `## Heading # A subtitle here`
   * `{{{ _partial.md }}}` syntax for including partials
@@ -387,3 +388,4 @@ which results in:
 [jep467]: https://openjdk.org/jeps/467
 [katex]: https://katex.org/
 [homebrew]: https://brew.sh/
+[task-list]: https://github.github.com/gfm/#task-list-items-extension-

package/build/utils/markdown.ts

@@ -24,6 +24,7 @@ import type { RenderDependencyCollector, SiteVariables } from '../types';
 const DETAILS_PATTERN = /^details\s+(.*)$/;
 const ALERT_PATTERN = /^(note|warning)(?:\s+"(.+)"|\s+(.+))?$/;
 const QUESTION_PATTERN = /^question\s+(.+)$/;
+const MULTIPLE_CHOICE_MARKER_LENGTH = 4;
 
 interface CreateMarkdownOptions {
   filePath?: string;
@@ -36,6 +37,16 @@ interface CreateMarkdownOptions {
   dependencyCollector?: RenderDependencyCollector;
 }
 
+interface MultipleChoiceOption {
+  correct: boolean;
+  inline: Token;
+}
+
+interface MultipleChoiceMeta {
+  question: string;
+  options: MultipleChoiceOption[];
+}
+
 function capitalize(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
@@ -123,6 +134,132 @@ export function createMarkdown(
     return token;
   }
 
+  function cloneToken(token: Token): Token {
+    const cloned = new Token(token.type, token.tag, token.nesting);
+    cloned.attrs = token.attrs?.map(([name, value]) => [name, value]) ?? null;
+    cloned.block = token.block;
+    cloned.children = token.children?.map(cloneToken) ?? null;
+    cloned.content = token.content;
+    cloned.hidden = token.hidden;
+    cloned.info = token.info;
+    cloned.level = token.level;
+    cloned.map = token.map ? [token.map[0], token.map[1]] : null;
+    cloned.markup = token.markup;
+    cloned.meta = token.meta;
+    return cloned;
+  }
+
+  function parseMultipleChoiceOption(
+    inline: Token,
+  ): MultipleChoiceOption | null {
+    const firstChild = inline.children?.[0];
+    if (firstChild?.type !== 'text') {
+      return null;
+    }
+
+    let correct: boolean;
+    if (firstChild.content.startsWith('[ ] ')) {
+      correct = false;
+    } else if (
+      firstChild.content.startsWith('[x] ') ||
+      firstChild.content.startsWith('[X] ')
+    ) {
+      correct = true;
+    } else {
+      return null;
+    }
+
+    const optionInline = cloneToken(inline);
+    optionInline.content = inline.content.slice(MULTIPLE_CHOICE_MARKER_LENGTH);
+    if (optionInline.children?.[0]?.type === 'text') {
+      optionInline.children[0].content = optionInline.children[0].content.slice(
+        MULTIPLE_CHOICE_MARKER_LENGTH,
+      );
+    }
+    if (slides) {
+      sanitizeTokenForSlides(optionInline);
+    }
+
+    return { correct, inline: optionInline };
+  }
+
+  function findQuestionCloseIndex(tokens: Token[], openIndex: number): number {
+    const level = tokens[openIndex].level;
+    for (let i = openIndex + 1; i < tokens.length; i++) {
+      const token = tokens[i];
+      if (token.type === 'container_question_close' && token.level === level) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  function multipleChoiceError(message: string): Error {
+    return new Error(
+      (filePath ? `${filePath}: ` : '') + `multiple choice question ${message}`,
+    );
+  }
+
+  function parseMultipleChoiceQuestion(
+    tokens: Token[],
+    openIndex: number,
+    closeIndex: number,
+  ): MultipleChoiceMeta | null {
+    const questionMatch = tokens[openIndex].info.trim().match(QUESTION_PATTERN);
+    if (!questionMatch) {
+      return null;
+    }
+
+    const bodyStart = openIndex + 1;
+    const bodyEnd = closeIndex - 1;
+    if (
+      bodyStart > bodyEnd ||
+      tokens[bodyStart].type !== 'bullet_list_open' ||
+      tokens[bodyEnd].type !== 'bullet_list_close'
+    ) {
+      return null;
+    }
+
+    const options: MultipleChoiceOption[] = [];
+    for (let i = bodyStart + 1; i < bodyEnd; ) {
+      const listItemOpen = tokens[i];
+      const paragraphOpen = tokens[i + 1];
+      const inline = tokens[i + 2];
+      const paragraphClose = tokens[i + 3];
+      const listItemClose = tokens[i + 4];
+      if (
+        listItemOpen?.type !== 'list_item_open' ||
+        paragraphOpen?.type !== 'paragraph_open' ||
+        inline?.type !== 'inline' ||
+        paragraphClose?.type !== 'paragraph_close' ||
+        listItemClose?.type !== 'list_item_close'
+      ) {
+        return null;
+      }
+
+      const option = parseMultipleChoiceOption(inline);
+      if (!option) {
+        return null;
+      }
+
+      options.push(option);
+      i += 5;
+    }
+
+    if (options.length === 0) {
+      return null;
+    }
+
+    const correctCount = options.filter(option => option.correct).length;
+    if (correctCount !== 1) {
+      throw multipleChoiceError(
+        `must include exactly one correct option marked with [x], but found ${correctCount}`,
+      );
+    }
+
+    return { question: questionMatch[1], options };
+  }
+
   function isInlineOnlyTokenStream(tokens: Token[]): boolean {
     return (
       tokens.length === 1 &&
@@ -434,6 +571,89 @@ export function createMarkdown(
     },
   });
 
+  markdown.core.ruler.before(
+    'slides_transform',
+    'multiple_choice_questions',
+    state => {
+      const transformedTokens: Token[] = [];
+      for (let i = 0; i < state.tokens.length; i++) {
+        const token = state.tokens[i];
+        if (token.type !== 'container_question_open') {
+          transformedTokens.push(token);
+          continue;
+        }
+
+        const closeIndex = findQuestionCloseIndex(state.tokens, i);
+        if (closeIndex === -1) {
+          transformedTokens.push(token);
+          continue;
+        }
+
+        const multipleChoice = parseMultipleChoiceQuestion(
+          state.tokens,
+          i,
+          closeIndex,
+        );
+        if (!multipleChoice) {
+          transformedTokens.push(...state.tokens.slice(i, closeIndex + 1));
+          i = closeIndex;
+          continue;
+        }
+
+        const multipleChoiceToken = new Token(
+          'question_multiple_choice',
+          '',
+          0,
+        );
+        multipleChoiceToken.block = true;
+        multipleChoiceToken.level = token.level;
+        multipleChoiceToken.map = token.map;
+        multipleChoiceToken.meta = multipleChoice;
+        transformedTokens.push(multipleChoiceToken);
+        i = closeIndex;
+      }
+
+      state.tokens = transformedTokens;
+    },
+  );
+
+  markdown.renderer.rules.question_multiple_choice = (
+    tokens,
+    idx,
+    renderOptions,
+    env,
+  ) => {
+    const meta = tokens[idx].meta as MultipleChoiceMeta;
+    const question = markdown.renderInline(meta.question);
+    const optionsHtml = meta.options
+      .map(option => {
+        const correctAttribute = option.correct ? ' data-correct=""' : '';
+        const optionHtml = markdown.renderer.render(
+          [option.inline],
+          renderOptions,
+          env,
+        );
+        return (
+          '<div class="question-multiple-choice-option"' +
+          correctAttribute +
+          '>' +
+          optionHtml +
+          '</div>'
+        );
+      })
+      .join('');
+
+    return (
+      '<div class="question question-multiple-choice">' +
+      '<p class="question-q"><span class="question-label">Q.</span><span>' +
+      question +
+      '</span></p>' +
+      '<div class="question-multiple-choice-options">' +
+      optionsHtml +
+      '</div></div>\n'
+    );
+  };
+
   /*
    * Customize markdown-it-footnote renderer.
    *

package/init/content/markdown.md

@@ -293,6 +293,16 @@ solved directly without any further recursive calls. For recursive methods that
 process strings, the base case is the empty string.
 ???
 
+If the body is a [task list][task-list] with exactly one `[x]` option, it
+becomes a multiple choice question with clickable options:
+
+??? question Which is correct for obtaining the number of characters in a `String`?
+- [ ] `word.size()`
+- [x] `word.length()`
+- [ ] `word.count()`
+- [ ] `word.length`
+???
+
 
 ### Generic section
 
@@ -438,3 +448,4 @@ Here's a time range:
 [flavored]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
 [presto]: https://github.com/abreen/presto
 [shiki]: https://shiki.style/
+[task-list]: https://github.github.com/gfm/#task-list-items-extension-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abreen/tada",
-  "version": "1.14.2",
+  "version": "1.15.0",
   "type": "module",
   "description": "A static site generator",
   "license": "MIT",

package/src/_base.scss

@@ -60,6 +60,19 @@ html {
   background: var(--bg-color);
 }
 
+.visually-hidden {
+  position: absolute !important;
+  width: 1px !important;
+  height: 1px !important;
+  padding: 0 !important;
+  margin: -1px !important;
+  overflow: hidden !important;
+  white-space: nowrap !important;
+  border: 0 !important;
+  clip: rect(0, 0, 0, 0) !important;
+  clip-path: inset(50%) !important;
+}
+
 a {
   color: var(--link-color);
   text-decoration-line: none;

package/src/question/index.ts

@@ -1,4 +1,64 @@
 export default (window: Window) => {
+  const appendResultText = (option: HTMLElement, text: string) => {
+    const result = window.document.createElement('span');
+    result.className = 'visually-hidden question-multiple-choice-result';
+    result.textContent = text;
+    option.append(result);
+  };
+
+  const multipleChoiceBlocks = window.document.querySelectorAll<HTMLElement>(
+    '.question-multiple-choice',
+  );
+  multipleChoiceBlocks.forEach(block => {
+    const options = Array.from(
+      block.querySelectorAll<HTMLElement>('.question-multiple-choice-option'),
+    );
+    options.forEach(option => {
+      option.setAttribute('role', 'button');
+      option.setAttribute('tabindex', '0');
+    });
+
+    const reveal = (selected: HTMLElement) => {
+      block.setAttribute('data-revealed', '');
+      selected.setAttribute('data-selected', '');
+      options.forEach(option => {
+        option.removeAttribute('role');
+        option.removeAttribute('tabindex');
+        if (option.hasAttribute('data-correct')) {
+          appendResultText(
+            option,
+            option === selected ? 'Selected answer, correct' : 'Correct answer',
+          );
+        } else if (option === selected) {
+          appendResultText(option, 'Selected answer, incorrect');
+        }
+      });
+    };
+
+    options.forEach(option => {
+      option.addEventListener('click', (e: MouseEvent) => {
+        if (block.hasAttribute('data-revealed')) {
+          return;
+        }
+
+        e.preventDefault();
+        e.stopPropagation();
+        reveal(option);
+      });
+      option.addEventListener('keydown', (e: KeyboardEvent) => {
+        if (block.hasAttribute('data-revealed')) {
+          return;
+        }
+
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          e.stopPropagation();
+          reveal(option);
+        }
+      });
+    });
+  });
+
   const bodies =
     window.document.querySelectorAll<HTMLElement>('.question-a-body');
   bodies.forEach(el => {

package/src/question/style.scss

@@ -1,6 +1,8 @@
 @use '../mixins' as *;
 
 .question {
+  --question-label-width: 1.2em;
+
   margin-bottom: 2rem;
 }
 
@@ -17,7 +19,7 @@
 
 .question-label,
 .question-a-label {
-  flex-shrink: 0;
+  flex: 0 0 var(--question-label-width);
   margin: 0;
   font-weight: 700;
   color: var(--theme-color-text);
@@ -32,17 +34,20 @@
 
 .question-a-body {
   flex: 1;
+}
+
+.js .question-a-body {
   cursor: pointer;
 
   @include user-select(none);
 }
 
-.question-a-body:focus-visible {
+.js .question-a-body:focus-visible {
   outline: 2px solid var(--theme-color);
   outline-offset: -2px;
 }
 
-.question-a-body[data-revealed] {
+.js .question-a-body[data-revealed] {
   &:focus,
   &:focus-visible {
     outline: none;
@@ -68,7 +73,7 @@
   }
 }
 
-.question-a-body:not([data-revealed]) > * {
+.js .question-a-body:not([data-revealed]) > * {
   color: transparent;
   pointer-events: none;
   background-color: var(--bg2-color);
@@ -76,14 +81,14 @@
   box-shadow: none;
 }
 
-.question-a-body:not([data-revealed]) > * * {
+.js .question-a-body:not([data-revealed]) > * * {
   color: transparent;
   background-color: var(--bg2-color);
   border-color: transparent;
   box-shadow: none;
 }
 
-.question-a-body::after {
+.js .question-a-body::after {
   display: block;
   font-size: var(--font-size-small);
   font-style: italic;
@@ -97,22 +102,112 @@
   }
 }
 
-.question-a-body[data-revealed]::after {
+.js .question-a-body[data-revealed]::after {
   opacity: 0;
 }
 
 @media (hover: none) {
-  .question-a-body::after {
+  .js .question-a-body::after {
     content: 'Tap to reveal';
   }
 }
 
-.question-a-body[data-revealed] {
+.js .question-a-body[data-revealed] {
   cursor: unset;
 
   @include user-select(text);
 }
 
+.question-multiple-choice {
+  --question-correct-color: hsl(142deg 58% 36%);
+  --question-correct-icon: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><circle cx='12' cy='12' r='10' fill='none' stroke='black' stroke-width='1.5'/><path d='M7 12.5 10.5 16 17 8.5' fill='none' stroke='black' stroke-width='1.75' stroke-linecap='round' stroke-linejoin='round'/></svg>");
+  --question-incorrect-color: hsl(0deg 72% 48%);
+  --question-incorrect-icon: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M7 7 17 17 M17 7 7 17' fill='none' stroke='black' stroke-width='1.75' stroke-linecap='round'/></svg>");
+  --question-result-icon-size: 1.35em;
+}
+
+@media (prefers-color-scheme: dark) {
+  .question-multiple-choice {
+    --question-correct-color: hsl(142deg 58% 52%);
+    --question-incorrect-color: hsl(0deg 82% 62%);
+  }
+}
+
+.question-multiple-choice-options {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75em;
+  margin-left: calc(var(--question-label-width) + 0.5em);
+}
+
+.question-multiple-choice-option {
+  position: relative;
+  padding: 0.5em calc(var(--question-result-icon-size) + 1em) 0.5em 0.5em;
+  cursor: pointer;
+  border: 0.125em solid var(--bg2-color);
+  border-radius: var(--border-radius);
+
+  @include user-select(none);
+
+  @media (prefers-reduced-motion: no-preference) {
+    transition:
+      border-color 0.25s,
+      box-shadow 0.25s;
+  }
+}
+
+.question-multiple-choice-option::after {
+  position: absolute;
+  top: 50%;
+  right: 0.5em;
+  display: none;
+  width: var(--question-result-icon-size);
+  height: var(--question-result-icon-size);
+  pointer-events: none;
+  content: '';
+  transform: translateY(-50%);
+}
+
+.question-multiple-choice-option:focus-visible {
+  outline: 2px solid var(--theme-color);
+  outline-offset: 2px;
+}
+
+.question-multiple-choice[data-revealed] {
+  .question-multiple-choice-option {
+    cursor: unset;
+
+    @include user-select(text);
+
+    &:focus,
+    &:focus-visible {
+      outline: none;
+    }
+  }
+
+  .question-multiple-choice-option[data-correct] {
+    border-color: var(--question-correct-color);
+
+    &::after {
+      display: block;
+      color: var(--question-correct-color);
+
+      @include contained-mask(var(--question-correct-icon));
+    }
+  }
+
+  .question-multiple-choice-option[data-selected]:not([data-correct]) {
+    border-color: var(--question-incorrect-color);
+
+    &::after {
+      display: block;
+      color: var(--question-incorrect-color);
+
+      @include contained-mask(var(--question-incorrect-icon));
+    }
+  }
+}
+
 @media print {
   .question-a-body {
     cursor: default;
@@ -134,4 +229,21 @@
       display: none;
     }
   }
+
+  .question-multiple-choice-option {
+    cursor: default;
+
+    @include user-select(text);
+  }
+
+  .question-multiple-choice-option[data-correct] {
+    border-color: var(--question-correct-color);
+
+    &::after {
+      display: block;
+      color: var(--question-correct-color);
+
+      @include contained-mask(var(--question-correct-icon));
+    }
+  }
 }

package/templates/_top.html

@@ -33,6 +33,7 @@
     <meta property="og:author" content="<%= page.author.name %>" />
     <% } %>
     <title><%= page.title %><%= site.titlePostfix %></title>
+    <script>document.documentElement.classList.add('js')</script>
     <% if (!isWatchMode) { %>
     <script type="speculationrules">
     {
@@ -47,10 +48,9 @@
     <% } %>
   <script>document.head.appendChild(document.createElement('style')).textContent='.time-zone-label[hidden],select.time-zone[hidden]{display:revert}'</script>
   <noscript><style>
-    .question-a-body:not([data-revealed]) > * { color: unset; background-color: unset; }
-    .question-a-body:not([data-revealed]) > * * { color: unset; background-color: unset; }
-    .question-a-body::after { display: none; }
-    .question-a-body { cursor: unset; }
+    .question-multiple-choice-option { cursor: unset; }
+    .question-multiple-choice-option[data-correct] { border-color: hsl(142deg 58% 36%); }
+    .question-multiple-choice-option[data-correct]::after { display: block; background-color: hsl(142deg 58% 36%); -webkit-mask-image: var(--question-correct-icon); mask-image: var(--question-correct-icon); -webkit-mask-repeat: no-repeat; mask-repeat: no-repeat; -webkit-mask-position: center center; mask-position: center center; -webkit-mask-size: contain; mask-size: contain; }
   </style></noscript>
   </head>