From 5e410c090440052303ffe0524746c6e11345c89b Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <michael@orlitzky.com>
Date: Fri, 3 Nov 2023 12:11:25 -0400
Subject: [PATCH] index.html.in: big Javascript and comment cleanup

---
 index.html.in | 272 ++++++++++++++++++++++++++------------------------
 1 file changed, 144 insertions(+), 128 deletions(-)

diff --git a/index.html.in b/index.html.in
index 34fec42..e14b87d 100644
--- a/index.html.in
+++ b/index.html.in
@@ -102,7 +102,7 @@
       }
 
 
-      /* Tram */
+      /* Train */
       @keyframes trainroll {
         from { transform: translateX(0%);   }
         to   { transform: translateX(100%); }
@@ -415,10 +415,10 @@
 
     <script>
 
-      /***********************************************/
-      /* First, center the ticket within the browser */
-      /***********************************************/
-
+      /**
+       * Center the ticket within the browser by translating the SVG
+       * until the ticket and the viewport centerlines coincide.
+       */
       function center_ticket() {
         /* We're relying on the SVG being the full height of the
          * viewport already, and on the aspect ratio being
@@ -441,9 +441,10 @@
       }
 
 
-      /******************************/
-      /* Set the service identifier */
-      /******************************/
+      /**
+       * Set the service identifier from the querystring if it's there.
+       * Otherwise, leave it at the default of "F".
+       */
       function set_service_id() {
         const sid = document.getElementById("serviceid");
 
@@ -452,13 +453,13 @@
         if (params.get("serviceid")) {
           sid.textContent = params.get("serviceid");
         }
-
-        /* Otherwise, leave it at "F" */
       }
 
-      /************************/
-      /* Set the service name */
-      /************************/
+
+      /**
+       * Set the service name from the querystring if it's there.
+       * Otherwise, leave it at the default of "BaltimoreLink".
+       */
       function set_service_name() {
         const sid = document.getElementById("servicename");
 
@@ -467,43 +468,37 @@
         if (params.get("servicename")) {
           sid.textContent = params.get("servicename");
         }
-
-        /* Otherwise, leave it at "BaltimoreLink" */
       }
 
 
-      /************************/
-      /* Set the service zone */
-      /************************/
-      function set_service_zone(event, zone) {
-        /* We can take the zone as a parameter too; this allows us to
-         * use this function for the (computed) MARC Train zone and
-         * not just the querystring Commuter Bus zone. The extra
-         * "event" parameter is there for the event listener, which
-         * would otherwise stuff an onload event into the zone
-         * parameter. "Thankfully" javascript lets us call a
-         * two-argument function with one argument and thereby abuse
-         * the event handler for this. */
+      /**
+       * Set the zone from the given "zone" parameter and then unhide it.
+       */
+      function set_zone(zone) {
         const z = document.getElementById("zone");
-        const params = new URLSearchParams(document.location.search);
-
-        if (zone) {
-          z.textContent = zone;
-          z.style.display = "block"; /* It's hidden by default */
-        }
-        else if (params.get("zone")) {
-          /* Get the "zone" from the querystring if it's there */
-          z.textContent = params.get("zone");
-          z.style.display = "block"; /* It's hidden by default */
-        }
-
-        /* Otherwise, leave it blank (and hidden) */
-      }
-
-      /***********************************************************/
-      /* Resize the  ticket background based on the service name */
-      /***********************************************************/
 
+        z.textContent = zone;
+        z.style.display = "block"; /* hidden by default */
+      }
+
+
+      /**
+       * Resize the  ticket background based on the service name.
+       * The BaltimoreLink, Commuter Bus, and MARC Train tickets
+       * are all different heights and are arranged vertically a
+       * bit different.
+       *
+       * Rather than design three completelty separate tickets and
+       * then have to keep track of which one we're using, I have
+       * instead decided to use one ticket and to reposition it
+       * on-the-fly based on the service name. This is necessarily
+       * a bit ugly because it involves a lot of magic numbers that
+       * can only be explained if you open up inkscape with a CharmPass
+       * screenshot to see where things belong and how to get them there.
+       *
+       * The SVG was designed with BaltimoreLink in mind, so this
+       * is a no-op if the service is BaltimoreLink.
+       */
       function resize_ticket() {
         /* Get the "servicename" from the querystring if it's there */
         const params = new URLSearchParams(document.location.search);
@@ -535,15 +530,13 @@
           t.setAttribute("transform", "translate(0 -67.17)");
           sn.setAttribute("transform", "translate(0 131.0)");
         }
-
-        /* Otherwise, leave it alone. The SVG was designed with the
-         * BaltimoreLink ticket in mind */
       }
 
-      /****************************************/
-      /* Set and reposition the security code */
-      /****************************************/
 
+      /**
+       * Set the security code from the querystring if it was given;
+       * otherwise generate a random code.
+       */
       function set_code() {
         const ct = document.getElementById("codetext");
 
@@ -569,6 +562,16 @@
       }
 
 
+      /**
+       * Center the security code within its container.
+       *
+       * Some codes like "II" and "WW" can take up wildly different
+       * amounts of horizonetal space, but they should always be
+       * centered inside their little red box. This turns out to be
+       * harder than it sounds because we can only find the width of
+       * the code in browser coordinates, whereas its "x" coordinate
+       * is in SVG coordinates. Anyway, we do it.
+       */
       function center_code() {
         /* Center the security code inside its red box */
         const ct = document.getElementById("codetext");
@@ -587,17 +590,16 @@
 
         /* We've measured everything so far in "client rect"
          * coordinates, because that's the only available measurement
-         * we have for the width of the <text> element after futzing
-         * with its contents. But when we reposition that <text>
-         * element, it will be by adjusting its "x" attribute, and
-         * that attribute uses a different coordinate system than the
-         * client rect does. Specifically, "x" refers to an offset
-         * within the SVG's coordinate system, and the client rect
-         * coordinates are pixels on-screen. To convert between the
+         * we have for the width of the <text> element. But when we
+         * reposition that <text> element, it will be by adjusting its
+         * "x" attribute, and that attribute uses a different coordinate
+         * system than the client rect does. Specifically, "x" refers to
+         * an offset within the SVG's coordinate system, and the client
+         * rect coordinates are pixels on-screen. To convert between the
          * two, we can take the "width" attribute of the background
          * element and compare it to the width of the background
          * element's client rect. Since the size of the background is
-         * fixed, this should give us a multiplier that turns client recr
+         * fixed, this should give us a multiplier that turns client rect
          * distances (what we have) into SVG distances (what we want) */
         const client_to_svg = parseFloat(bg.getAttribute("width"))/r1.width;
 
@@ -609,22 +611,22 @@
         ct.setAttribute("x", parseFloat(ct.getAttribute("x")) + svg_hdelta);
       }
 
-      /*****************************************/
-      /* Next, set up the ticket date and time */
-      /*****************************************/
-
+      /**
+       * Set the ticket's expiration date and time.
+       *
+       * BaltimoreLink and MARC Train tickets expire after 90 minutes;
+       * while Commuter Bus tickets expire after 10 minutes.
+       */
       function set_ticket_expiry() {
         /* There are two parameters, time and date, that we store in one
-         * underlying "date" variable. Default both to an hour and a
-         * half from now. This is what the CharmPass app does for
-         * one-way tickets. */
+         * underlying "date" variable. */
         const date = new Date();
 
-        /* BaltimoreLink and MARC Train are valid for an hour and a half */
+        /* BaltimoreLink and MARC Train */
         let minutes = 90;
         const params = new URLSearchParams(document.location.search);
         if (params.get("servicename") == "Commuter Bus") {
-          /* But commuter bus tickets are only valid for ten minutes */
+          /* Commuter bus tickets are only valid for ten minutes */
           minutes = 10;
         }
 
@@ -647,56 +649,56 @@
       }
 
 
-      /*********************************************************/
-      /* Finally, the onclick handler for the night/day switch */
-      /*********************************************************/
+      /**
+       * Swap the day/night sky colors.
+       *
+       * We use CSS classes to keep track of the current state because
+       * it's a tiny bit cleaner than a global variable, but for some
+       * reason we can't use those same classes to actually change the
+       * color. (The classes, change, but the color doesn't.) Rather
+       * than waste time trying to explain this, we just set the "fill"
+       * attribute ourselves whenever we swap classes.
+       */
+      function swap_day_night() {
+        const sky = document.getElementById("sky");
 
-      /* We always start in "day" mode */
-      is_day = true;
-
-      function set_day() {
-        sky.style.fill = "#efb02f";
-      }
-
-      function set_night() {
-        sky.style.fill = "#143b66";
-      }
-
-      function swap_colors() {
-        if (is_day) {
-          set_night();
-          is_day = false;
+        if (sky.getAttribute("class") == "night") {
+          sky.setAttribute("fill", "#efb02f");
+          sky.setAttribute("class", "day");
         }
         else {
-          set_day();
-          is_day = true;
+          /* Put this case second so that the first time the
+           * screen is tapped (when there are no classes on
+           * the sky element) the color still changes. */
+          sky.setAttribute("fill", "#143b66");
+          sky.setAttribute("class", "night");
         }
       }
 
 
-      /*******************************************************/
-      /* Compute the MARC "zone" from its origin/destination */
-      /*******************************************************/
-
-      /* Sorted on the first component, then the second */
-      const zone_map = {
-        BAL_BWE: 2,
-        BAL_BWI: 1,
-        BAL_SEB: 3,
-        BAL_WAS: 4,
-        BAL_WBL: 1,
-        BCA_CPK_: 3,
-        BCA_WAS_: 4,
-        BWI_BWE: 1,
-        BWI_WAS: 3,
-        BWI_WBL: 1
-      };
-
-      /* Compute the zone (string) for the given origin/destination pair.
+      /**
+       * Compute the zone (string) for the given origin/destination pair.
+       *
        * If we don't know it or if you chose in invalid pair (destination
        * not on the same line as your origin?) then the empty string is
-       * returned. */
+       * returned.
+       */
       function compute_marc_zone(src, dest) {
+
+        /* Sorted on the first component, then the second */
+        const zone_map = {
+          BAL_BWE: 2,
+          BAL_BWI: 1,
+          BAL_SEB: 3,
+          BAL_WAS: 4,
+          BAL_WBL: 1,
+          BCA_CPK_: 3,
+          BCA_WAS_: 4,
+          BWI_BWE: 1,
+          BWI_WAS: 3,
+          BWI_WBL: 1
+        };
+
         /* Forward direction key for zone_map */
         const fwd = src + "_" +  dest;
 
@@ -731,22 +733,37 @@
         }
       }
 
-      function set_marc_zone() {
+
+      /**
+       * Compute and set the zone.
+       *
+       * We can be given a zone in two ways. First, on Commuter Bus
+       * tickets, it is given explicitly via the querystring. But
+       * It can also be specified implicitly via the origin and
+       * destination on a MARC Train ticket. Here we try both and
+       * then call set_zone() with the result if something worked.
+       */
+      function compute_and_set_zone() {
         const params = new URLSearchParams(document.location.search);
-        if (params.get("origin") && params.get("destination")) {
-          const src = params.get("origin");
-          const dest = params.get("destination");
-          const zone = compute_marc_zone(src, dest);
+        const src = params.get("origin");
+        const dest = params.get("destination");
 
-          set_service_zone(null, zone);
+        if (src && dest) {
+          /* MARC Train */
+          const zone = compute_marc_zone(src, dest);
+          set_zone(zone);
+        }
+        else if (params.get("zone")) {
+          /* Commuter Bus */
+          set_zone(params.get("zone"));
         }
       }
 
 
-      /*****************************************************/
-      /* Set the origin and destination for the MARC Train */
-      /*****************************************************/
-
+      /**
+       * Set the origin and destination for the MARC Train if they
+       * were provided, and unhide them if so.
+       */
       function set_marc_origin_destination() {
         const params = new URLSearchParams(document.location.search);
         if (!params.get("origin") || !params.get("destination")) {
@@ -765,13 +782,14 @@
         origin.textContent = params.get("origin");
         destination.textContent = params.get("destination");
 
-        origindest.style.display = "block"; /* It's hidden by default */
+        origindest.style.display = "block"; /* hidden by default */
       }
 
-      /******************************************/
-      /* Display the ticket (and hide the menu) */
-      /******************************************/
 
+      /**
+       * Hide the menu and display the ticket. This is what happens
+       * when you submit the form.
+       */
       function go() {
         /* To create our "window" onto the scene, we're going to slide the
          * SVG off the left-hand side of the screen, and we don't want
@@ -786,6 +804,7 @@
         menu.style.display = "none";
       }
 
+
       /*****************************************************/
       /* Add event handlers for all of the functions above */
       /*****************************************************/
@@ -807,9 +826,6 @@
         /* Set the service name when the page has loaded */
         window.addEventListener("load", set_service_name);
 
-        /* Set the service zone when the page has loaded */
-        window.addEventListener("load", set_service_zone);
-
         /* Resize the ticket background if necessary */
         window.addEventListener("load", resize_ticket);
 
@@ -826,11 +842,11 @@
         /* Set the MARC Train origin and destination, if applicable */
         window.addEventListener("load", set_marc_origin_destination);
 
-        /* Set the MARC Train zone, if applicable */
-        window.addEventListener("load", set_marc_zone);
+        /* Compute and set the zone, if applicable */
+        window.addEventListener("load", compute_and_set_zone);
 
         /* Swap colors when the screen is tapped */
-        document.body.addEventListener("click", swap_colors);
+        document.body.addEventListener("click", swap_day_night);
       }
 
     </script>
-- 
2.44.2