Update "Example program" page to use "pick"

- Add code to check for `"pick"` contexts
- Highlight multiple source ranges with different color

Author: gnidan

packages/web/spec/program/example.mdx

@@ -28,6 +28,7 @@ code {
 
   let localValue = storedValue + 1;
   storedValue = localValue;
+  return;
 }
 `}]}
   instructions={[
@@ -285,8 +286,10 @@ code {
         mnemonic: "JUMPDEST"
       },
       context: ({ findSourceRange }) => ({
-        code: findSourceRange("return;"),
-        remark: "skip to here if not enough paid"
+        pick: [
+          { code: findSourceRange("return;") },
+          { code: findSourceRange("return;", { after: "return;" }) },
+        ]
       })
     }
   ]}

packages/web/src/theme/ProgramExample/Details.tsx

@@ -0,0 +1,67 @@
+import Admonition from "@theme/Admonition";
+import Link from "@docusaurus/Link";
+import { Program } from "@ethdebug/format";
+import { useProgramExampleContext } from "./ProgramExampleContext";
+import { HighlightedInstruction } from "./HighlightedInstruction";
+import { Variables } from "./Variables";
+
+// imported for style legend
+import "./SourceContents.css";
+
+export interface Props {
+}
+
+export function Details(props: Props): JSX.Element {
+  const { highlightedInstruction, highlightMode } = useProgramExampleContext();
+
+  if (highlightMode === "simple" || !highlightedInstruction) {
+    return <>
+      <h3>Details</h3>
+      <BasicAdmonition />
+    </>;
+  }
+
+
+  return <>
+    <h3>Details</h3>
+    <InstructionAdmonition instruction={highlightedInstruction} />
+    <details>
+      <summary>See full <strong>ethdebug/format/program/instruction</strong> object</summary>
+      <HighlightedInstruction />
+    </details>
+  </>;
+}
+
+interface InstructionAdmonitionProps {
+  instruction: Program.Instruction;
+}
+function InstructionAdmonition({
+  instruction
+}: InstructionAdmonitionProps): JSX.Element {
+  return <Admonition type="info">
+    <p>
+      The selected instruction provides the following <Link to="/spec/program/context">
+        <strong>ethdebug/format</strong> Program contexts
+      </Link>:
+    </p>
+    <ul>
+      <li>
+        <strong>Code context</strong> is highlighted <span className="highlighted-code">in this
+        style</span> above.
+      </li>
+      <li>
+        <strong>Variables context</strong> is indicated by variable declarations
+        highlighted <span className="highlighted-variable-declaration">in this
+        style</span> above.
+      </li>
+    </ul>
+  </Admonition>;
+}
+
+function BasicAdmonition(props: {}): JSX.Element {
+  return <Admonition type="tip">
+    Select an instruction offset to see associated <strong>
+      ethdebug/format
+    </strong> debugging information.
+  </Admonition>;
+}

packages/web/src/theme/ProgramExample/SourceContents.css

@@ -4,6 +4,11 @@
   background-color: var(--ifm-color-primary-lightest);
 }
 
+.highlighted-ambiguous-code {
+  font-weight: bold;
+  background-color: var(--ifm-color-warning-lightest);
+}
+
 .highlighted-variable-declaration {
   text-decoration: underline;
   text-decoration-style: wavy;

packages/web/src/theme/ProgramExample/SourceContents.tsx

@@ -31,7 +31,9 @@ export function SourceContents(
 
   const simpleDecorations = Program.Context.isCode(context)
     ? decorateCodeContext(context, source)
-    : [];
+    : Program.Context.isPick(context)
+      ? decoratePickContext(context, source)
+      : [];
 
   const detailedDecorations = [
     ...simpleDecorations,
@@ -56,7 +58,8 @@ export function SourceContents(
 
 function decorateCodeContext(
   { code }: Program.Context.Code,
-  source: Materials.Source
+  source: Materials.Source,
+  className: string = "highlighted-code"
 ): Shiki.DecorationItem[] {
   const { offset, length } = normalizeRange(code.range, source);
 
@@ -65,12 +68,28 @@ function decorateCodeContext(
       start: offset,
       end: offset + length,
       properties: {
-        class: "highlighted-code"
+        class: className
       }
     }
   ];
 }
 
+function decoratePickContext(
+  { pick }: Program.Context.Pick,
+  source: Materials.Source
+): Shiki.DecorationItem[] {
+  // HACK this only supports picking from a choice of several different code
+  // contexts
+  if (!pick.every(Program.Context.isCode)) {
+    return [];
+  }
+
+  return pick.flatMap(
+    (choice) => decorateCodeContext(choice, source, "highlighted-ambiguous-code")
+  );
+}
+
+
 function decorateVariablesContext(
   { variables }: Program.Context.Variables,
   source: Materials.Source

packages/web/src/theme/ProgramExample/Viewer.tsx

@@ -1,60 +1,16 @@
 import Admonition from "@theme/Admonition";
 import Link from "@docusaurus/Link";
-import { useProgramExampleContext } from "./ProgramExampleContext";
 import { SourceContents } from "./SourceContents";
 import { Opcodes } from "./Opcodes";
-import { HighlightedInstruction } from "./HighlightedInstruction";
+import { Details } from "./Details";
 import { Variables } from "./Variables";
 
 import "./Viewer.css";
-import "./SourceContents.css";
 
 export interface Props {
 }
 
 export function Viewer(props: Props): JSX.Element {
-  const { highlightedInstruction, highlightMode } = useProgramExampleContext();
-
-  const basicAdmonition = <Admonition type="tip">
-    Select an instruction offset to see associated <strong>
-      ethdebug/format
-    </strong> debugging information.
-  </Admonition>;
-
-  const detailedAdmonition = <Admonition type="info">
-    <p>
-      The selected instruction provides the following <Link to="/spec/program/context">
-        <strong>ethdebug/format</strong> Program contexts
-      </Link>:
-    </p>
-    <ul>
-      <li>
-        <strong>Code context</strong> is highlighted <span className="highlighted-code">in this
-        style</span> above.
-      </li>
-      <li>
-        <strong>Variables context</strong> is indicated by variable declarations
-        highlighted <span className="highlighted-variable-declaration">in this
-        style</span> above.
-      </li>
-    </ul>
-  </Admonition>;
-
-  const details = highlightedInstruction && highlightMode === "detailed"
-    ? <>
-        <h3>Details</h3>
-        {detailedAdmonition}
-        <details>
-          <summary>See full <strong>ethdebug/format/program/instruction</strong> object</summary>
-          <HighlightedInstruction />
-        </details>
-      </>
-    : <>
-        <h3>Details</h3>
-        {basicAdmonition}
-      </>;
-
-
   return <>
     <h2>Interactive example</h2>
     <div className="viewer-row">
@@ -67,6 +23,6 @@ export function Viewer(props: Props): JSX.Element {
         <Opcodes />
       </div>
     </div>
-    {details}
+    <Details />
   </>;
 }