From c729b51da60c04c034cd2fa33ab307fe2bae2e1c Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Tue, 7 Jan 2025 22:54:30 -0500
Subject: [PATCH 01/21] buttonize this link

---
 src/routes/dashboard/points-motions/+page.svelte | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/src/routes/dashboard/points-motions/+page.svelte b/src/routes/dashboard/points-motions/+page.svelte
index 0a55752..62169b0 100644
--- a/src/routes/dashboard/points-motions/+page.svelte
+++ b/src/routes/dashboard/points-motions/+page.svelte
@@ -1,4 +1,5 @@
 <script lang="ts">
+  import { goto } from "$app/navigation";
   import { base } from "$app/paths";
   import DelLabel from "$lib/components/del-label/DelLabel.svelte";
   import IconLabel from "$lib/components/IconLabel.svelte";
@@ -175,17 +176,14 @@
                   >
                     <Icon icon="mdi:cancel" width="24" height="24" class="text-error-500" />
                   </button>
-                  <a
+                  <button
                     class="btn btn-sm btn-icon w-8"
-                    onclick={() => acceptMotion(motion)}
-                    href="{base}/dashboard/current-motion"
-                    role="button"
+                    onclick={() => { acceptMotion(motion); goto(`${base}/dashboard/current-motion`); }}
                     data-label="Accept {delName}'s Motion"
                     title="Accept {delName}'s Motion"
-                    tabindex={0}
                   >
                     <Icon icon="mdi:check" width="24" height="24" class="text-success-700" />
-                  </a>
+                  </button>
                   <button
                     class="btn btn-sm btn-icon w-8"
                     onclick={() => editMotion(i, motion)}

From a7da0297f4b9904baf7c2f26ba9a824a0bc1dffc Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Wed, 8 Jan 2025 14:17:15 -0500
Subject: [PATCH 02/21] move clamp to utils

---
 src/lib/components/Timer.svelte |  8 +-------
 src/lib/util/index.ts           | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/src/lib/components/Timer.svelte b/src/lib/components/Timer.svelte
index dc3ca88..74f5f7b 100644
--- a/src/lib/components/Timer.svelte
+++ b/src/lib/components/Timer.svelte
@@ -125,13 +125,6 @@
         }
     }
 
-    function clamp(value: number, min: number, max: number) {
-        if (Number.isNaN(value)) return max;
-        if (value < min) return min;
-        if (value > max) return max;
-        return value;
-    }
-
     function keydown(e: KeyboardEvent) {
         if (disableKeyHandlers) return;
         if (e.target !== document.body) return;
@@ -165,6 +158,7 @@
 
 <script module lang="ts">
     import type { ClockMessage } from "$lib/types";
+    import { clamp } from "$lib/util";
     import ClockSourceWorker from "$lib/util/clock?worker";
 
     // This is a synchronized timer for all Timer components.
diff --git a/src/lib/util/index.ts b/src/lib/util/index.ts
index 6310b23..73eba1a 100644
--- a/src/lib/util/index.ts
+++ b/src/lib/util/index.ts
@@ -94,3 +94,20 @@ export function lazyslide(node: HTMLElement, { delay = 0, duration = 400, easing
         }
     } satisfies TransitionConfig;
 }
+
+/**
+ * Clamps a value between a minimum and maximum. 
+ * If the value is less than the minimum, this returns the minimum,
+ * and if it is greater than the maximum, this erturns the maximum.
+ * 
+ * @param value the value
+ * @param min the minimum
+ * @param max the maximum
+ * @returns the clamped value
+ */
+export function clamp(value: number, min: number, max: number) {
+    if (Number.isNaN(value)) return max;
+    if (value < min) return min;
+    if (value > max) return max;
+    return value;
+}
\ No newline at end of file

From 912730c45f01ab83406f3d5bb72d7a614bbf5610 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Wed, 8 Jan 2025 15:45:32 -0500
Subject: [PATCH 03/21] add Timer.svelte doc

---
 src/lib/components/Timer.svelte | 137 +++++++++++++++++++++++---------
 1 file changed, 100 insertions(+), 37 deletions(-)

diff --git a/src/lib/components/Timer.svelte b/src/lib/components/Timer.svelte
index 74f5f7b..5430987 100644
--- a/src/lib/components/Timer.svelte
+++ b/src/lib/components/Timer.svelte
@@ -1,53 +1,107 @@
-<!-- A small timer component.
-    This component is a linear progress bar that runs for a preset number of seconds.
-    This contains the binds bind:start, bind:pause, bind:reset to start/pause/reset the timer,
-    and the duration prop to control how many seconds the timer should run for.
+<!-- 
+    @component A small timer component.
+    This component consists of a linear progress bar and text displaying the timer's elapsed duration.
+    
+    To programatically control the timer, bind to the `running` prop of this component. 
+    Setting it to `false` pauses the timer, and setting it to `true` starts the timer.
+    The timer will automatically pause (setting `running` to false) when the full duration elapses.
 -->
 <script lang="ts">
     import { parseTime, stringifyTime } from "$lib/util/time";
     import { ProgressBar } from "@skeletonlabs/skeleton";
-    import { onDestroy, onMount } from "svelte";
+    import { onDestroy, onMount, untrack } from "svelte";
     
     interface Props {
+        /**
+         * How long the total duration of this timer should run for (in seconds).
+         * 
+         * If this timer is `editable`, then this is a **bindable** prop, 
+         * in which case the duration is updated when the timer is edited.
+         */
         duration: number;
+
+        /**
+         * The name of the timer. This should have some unique name per page.
+         * It does not have to be descriptive; it could literally just be `1`.
+         */
         name: string;
-        height?: string;
+
+        /**
+         * Whether or not this timer is running.
+         * 
+         * This is a **bindable** prop. It will update to reflect the timer's
+         * running state. This can be set to start or pause the timer.
+         * 
+         * To reset the timer, use the `reset` function of the component.
+         */
         running?: boolean;
+
+        // Visual properties:
+        /**
+         * Any height classes that should be added to the progress bar.
+         */
+        height?: string;
+
+        /**
+         * If enabled, this removes the duration text. 
+         * By default, this is false.
+         */
         hideText?: boolean;
-        disableKeyHandlers?: boolean;
+
+        // Other properties:
+        /**
+         * If enabled, the total duration part of the text can be modified to change the duration.
+         * By default, this is false.
+         */
         editable?: boolean;
-        onPause?: ((elapsed: number) => void) | undefined;
+
+        /**
+         * If enabled, keyboard shortcuts to manage the timer are disabled. 
+         * By default, this is false.
+         */
+        disableKeyHandlers?: boolean;
+
+        /**
+         * This property can be bound to add an event handler for every time the timer is paused.
+         * 
+         * The listener can accept a number representing the number of milliseconds since the last
+         * pause.
+         */
+        onPause?: (elapsed: number) => void;
     }
 
     let {
         duration = $bindable(),
         name,
-        height = "h-10",
         running = $bindable(false),
+        height = "h-10",
         hideText = false,
-        disableKeyHandlers = false,
         editable = false,
-        onPause = undefined
+        disableKeyHandlers = false,
+        onPause = undefined,
     }: Props = $props();
 
     
     const COLOR_THRESHOLDS = [
-        ["bg-emerald-500", 1],
-        ["bg-yellow-500",  0.5],
-        ["bg-red-500",     0.2]
+        // color = the color class to apply
+        // threshold = the maximum value needed for this color apply
+        //     e.g., if (threshold_0 < progress <= threshold_1), we use color_1
+        { color: "bg-emerald-500", threshold: 1   },
+        { color: "bg-yellow-500",  threshold: 0.5 },
+        { color: "bg-red-500",     threshold: 0.2 },
     ] as const;
 
     let DURATION_MS = $derived(duration * 1000);
     // reset timer on duration update:
     $effect(() => {
         duration;
-        reset();
+        untrack(reset);
     });
 
     // Progress & display values
     let msRemaining = $state(duration * 1000);
     let progress = $derived(clamp(msRemaining / DURATION_MS, 0, 1))
-    let color = $derived((COLOR_THRESHOLDS.findLast(([_, n]) => progress <= n) ?? COLOR_THRESHOLDS[0])[0]);
+    let color = $derived((COLOR_THRESHOLDS.findLast(t => progress <= t.threshold) ?? COLOR_THRESHOLDS[0]).color);
     let barProps = $derived({
         value: 100 * progress,
         height,
@@ -61,6 +115,8 @@
     let lastStart: number | undefined = undefined;
     let lastEnd: number = 0;
     let msRemainingAtStart: number;
+
+    // Timer event loop
     onMount(() => {
         initClockSource().addEventListener("message", loop);
     });
@@ -69,20 +125,6 @@
         updateRunningEffects(running);
         clockSource?.removeEventListener("message", loop);
     });
-
-    // Trigger state update on running change:
-    $effect(() => {
-        updateRunningEffects(running);
-    });
-
-    // Readonly query variables:
-    export function secsRemaining(): number {
-        return msRemaining / 1000;
-    }
-    export function canReset(): boolean {
-        return secsRemaining() != duration;
-    }
-    
     function loop({ data }: MessageEvent<ClockMessage>) {
         if (data.kind === "startTick") {
             if (!running) return;
@@ -98,10 +140,31 @@
             data satisfies never;
         }
     }
+
+    // Trigger state update on running change:
+    $effect(() => updateRunningEffects(running));
+
+    // Exported methods:
+    /**
+     * Whether the timer can be reset at the moment.
+     * It can be reset only when the duration is not at maximum.
+     * @returns whether the timer can be reset
+     */
+    export function canReset(): boolean {
+        return msRemaining != DURATION_MS;
+    }
+    /**
+     * Resets the timer. 
+     * This practically does nothing if `canReset()` is false.
+     */
     export function reset() {
         running = false;
         msRemaining = DURATION_MS;
     }
+
+    /**
+     * Elapsed time since last pause.
+     */
     function getElapsedTime() {
         if (typeof lastStart === "undefined") return 0;
         if (Number.isNaN(lastStart)) return 0;
@@ -111,20 +174,20 @@
         return lastEnd - lastStart;
     }
     
-    // You have to check for a state change here, idk why
-    let _running = running;
     function updateRunningEffects(running: boolean) {
-        if (_running != running) {
-            _running = running;
+        // Make sure that running does not depend on msRemaining 
+        // (since that updates while running)
+        untrack(() => {
             if (running) {
                 lastStart = undefined;
                 msRemainingAtStart = msRemaining;
             } else {
                 onPause?.(getElapsedTime());
             }
-        }
+        })
     }
 
+    // Keyboard events
     function keydown(e: KeyboardEvent) {
         if (disableKeyHandlers) return;
         if (e.target !== document.body) return;
@@ -178,7 +241,7 @@
         id={barProps.labelledby}
     >
         {#if editable && !running}
-            {stringifyTime(secsRemaining())}/<span
+            {stringifyTime(msRemaining / 1000)}/<span
                 class="border-b-4 border-transparent hover:border-surface-500 focus:border-surface-500 transition rounded"
                 contenteditable
                 onfocusout={setDuration}
@@ -189,7 +252,7 @@
                 {stringifyTime(duration)}
             </span>
         {:else}
-            {stringifyTime(secsRemaining())}/{stringifyTime(duration)}
+            {stringifyTime(msRemaining / 1000)}/{stringifyTime(duration)}
         {/if}
     </h2>
     <ProgressBar {...barProps} />

From 080d3ecacdd79db7aa92295d8a07e7562eb612ae Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Wed, 8 Jan 2025 23:30:25 -0500
Subject: [PATCH 04/21] encapsulate caucus-type pages' timer into a
 `TimerPanel` component

---
 src/lib/components/Timer.svelte               |  12 +-
 src/lib/components/motions/ModCaucus.svelte   | 121 ----------
 src/lib/components/motions/RoundRobin.svelte  | 109 ---------
 src/lib/components/motions/TimerPanel.svelte  | 224 ++++++++++++++++++
 .../components/motions/page/ModCaucus.svelte  |  65 +++++
 .../components/motions/{ => page}/README.md   |   0
 .../components/motions/page/RoundRobin.svelte |  62 +++++
 .../motions/{ => page}/UnmodCaucus.svelte     |   0
 .../dashboard/current-motion/+page.svelte     |   6 +-
 .../dashboard/speaker-list/+page.svelte       |  72 +-----
 10 files changed, 372 insertions(+), 299 deletions(-)
 delete mode 100644 src/lib/components/motions/ModCaucus.svelte
 delete mode 100644 src/lib/components/motions/RoundRobin.svelte
 create mode 100644 src/lib/components/motions/TimerPanel.svelte
 create mode 100644 src/lib/components/motions/page/ModCaucus.svelte
 rename src/lib/components/motions/{ => page}/README.md (100%)
 create mode 100644 src/lib/components/motions/page/RoundRobin.svelte
 rename src/lib/components/motions/{ => page}/UnmodCaucus.svelte (100%)

diff --git a/src/lib/components/Timer.svelte b/src/lib/components/Timer.svelte
index 5430987..78095ab 100644
--- a/src/lib/components/Timer.svelte
+++ b/src/lib/components/Timer.svelte
@@ -1,10 +1,10 @@
 <!-- 
-    @component A small timer component.
-    This component consists of a linear progress bar and text displaying the timer's elapsed duration.
-    
-    To programatically control the timer, bind to the `running` prop of this component. 
-    Setting it to `false` pauses the timer, and setting it to `true` starts the timer.
-    The timer will automatically pause (setting `running` to false) when the full duration elapses.
+  @component A small timer component.
+  This component consists of a linear progress bar and text displaying the timer's elapsed duration.
+  
+  To programatically control the timer, bind to the `running` prop of this component. 
+  Setting it to `false` pauses the timer, and setting it to `true` starts the timer.
+  The timer will automatically pause (setting `running` to false) when the full duration elapses.
 -->
 <script lang="ts">
     import { parseTime, stringifyTime } from "$lib/util/time";
diff --git a/src/lib/components/motions/ModCaucus.svelte b/src/lib/components/motions/ModCaucus.svelte
deleted file mode 100644
index 3f7ed38..0000000
--- a/src/lib/components/motions/ModCaucus.svelte
+++ /dev/null
@@ -1,121 +0,0 @@
-<script lang="ts">
-    import DelLabel from "$lib/components/del-label/DelLabel.svelte";
-    import SpeakerList from "$lib/components/SpeakerList.svelte";
-    import Timer from "$lib/components/Timer.svelte";
-    import { getSessionContext } from "$lib/context/index.svelte";
-    import { db } from "$lib/db/index.svelte";
-    import { findDelegate } from "$lib/db/delegates";
-    import { presentDelegateSchema } from "$lib/motions/form_validation";
-    import type { Motion, Speaker } from "$lib/types";
-    import { lazyslide } from "$lib/util";
-    import Icon from "@iconify/svelte";
-    import { untrack } from "svelte";
-
-    interface Props {
-        motion: Motion & { kind: "mod" };
-        order: Speaker[];
-    }
-    let { motion, order = $bindable() }: Props = $props();
-
-    const sessionData = getSessionContext();
-    const { delegates } = sessionData;
-    $effect(() => {
-        sessionData.barTopic = `Topic: ${motion.topic}`;
-    });
-
-    // Timer
-    let running: boolean = $state(false);
-    let delTimer: Timer | undefined = $state();
-    let totalTimer: Timer | undefined = $state();
-    
-    // Speakers List
-    let speakersList: SpeakerList | undefined = $state();
-    let selectedSpeaker = $derived(speakersList?.selectedSpeaker());
-    $effect(() => {
-        if (running) untrack(() => {
-            speakersList?.start();
-        })
-    });
-
-    // Button triggers
-    function reset() {
-        delTimer?.reset();
-    }
-    function resetAll() {
-        delTimer?.reset();
-        totalTimer?.reset();
-    }
-    function next() {
-        speakersList?.next();
-    }
-</script>
-
-<div class="flex flex-col lg:flex-row h-full gap-8 items-stretch">
-    <!--
-        Under mobile, the timer encompasses the whole page 
-        and the speakers list can be accessed by scrolling down.
-
-        Under desktop, both are on the same screen,
-        with the left side being the timer and the right side being the speakers list.
-    -->
-    <!-- Left/Top -->
-    <div class="flex flex-col flex-grow flex-shrink-0 basis-full lg:basis-auto">
-        <div class="flex justify-center h-6 lg:hidden">
-            <!-- Placeholder which matches size of chevron-down -->
-        </div>
-        <div class="flex flex-col justify-center flex-grow">
-            {#key selectedSpeaker?.key}
-                <div class="pb-5" transition:lazyslide>
-                    {#if typeof selectedSpeaker !== "undefined"}
-                        <DelLabel attrs={findDelegate($delegates, selectedSpeaker.key)} />
-                    {/if}
-                </div>
-            {/key}
-            <div class="flex flex-col gap-5">
-                <Timer 
-                    name="delegate"
-                    duration={motion.speakingTime}
-                    bind:this={delTimer}
-                    bind:running
-                    disableKeyHandlers={typeof selectedSpeaker === "undefined"}
-                    onPause={(t) => db.updateDelegate(selectedSpeaker?.key, d => { d.stats.durationSpoken += t; })}
-                />
-                <Timer
-                    name="total"
-                    duration={motion.totalTime}
-                    bind:this={totalTimer}
-                    bind:running
-                    disableKeyHandlers
-                />
-                <div class="flex flex-row gap-3 justify-center">
-                    {#if !running}
-                        <button class="btn variant-filled-primary" disabled={typeof selectedSpeaker === "undefined"} onclick={() => running = true}>Start</button>
-                    {:else}
-                        <button class="btn variant-filled-primary" onclick={() => running = false}>Pause</button>
-                    {/if}
-                    <button class="btn variant-filled-primary" disabled={speakersList?.isAllDone() ?? true} onclick={next}>Next</button>
-                    <button class="btn variant-filled-primary" disabled={!delTimer?.canReset()} onclick={reset}>Reset</button>
-                    <button class="btn variant-filled-primary" disabled={!totalTimer?.canReset()} onclick={resetAll}>Reset all</button>
-                </div>
-            </div>
-        </div>
-        <!-- Mobile chevron -->
-        <div class="flex justify-center lg:hidden">
-            <Icon icon="mdi:chevron-down" width="24" height="24" />
-        </div>
-    </div>
-    <!-- Right/Bottom -->
-    <div class="flex flex-col gap-4 h-full lg:overflow-hidden xl:min-w-[25rem] lg:max-w-[33%]">
-        <!-- List -->
-        <SpeakerList
-            bind:order
-            delegates={$delegates}
-            bind:this={speakersList}
-            useDefaultControls={{
-                validator: presentDelegateSchema
-            }}
-            onBeforeSpeakerUpdate={reset}
-            onMarkComplete={(key, isRepeat) => { if (!isRepeat) db.updateDelegate(key, d => { d.stats.timesSpoken++; }) }}
-        />
-    </div>
-</div>
\ No newline at end of file
diff --git a/src/lib/components/motions/RoundRobin.svelte b/src/lib/components/motions/RoundRobin.svelte
deleted file mode 100644
index f8d4269..0000000
--- a/src/lib/components/motions/RoundRobin.svelte
+++ /dev/null
@@ -1,109 +0,0 @@
-<script lang="ts">
-    import DelLabel from "$lib/components/del-label/DelLabel.svelte";
-    import SpeakerList, { createSpeaker } from "$lib/components/SpeakerList.svelte";
-    import Timer from "$lib/components/Timer.svelte";
-    import { getSessionContext } from "$lib/context/index.svelte";
-    import { db } from "$lib/db/index.svelte";
-    import { findDelegate } from "$lib/db/delegates";
-    import type { Motion, Speaker } from "$lib/types";
-    import { lazyslide } from "$lib/util";
-    import Icon from "@iconify/svelte";
-    import { untrack } from "svelte";
-
-    interface Props {
-        motion: Motion & { kind: "rr" };
-        order: Speaker[]
-    }
-    let { motion, order = $bindable() }: Props = $props();
-
-    const sessionData = getSessionContext();
-    const { delegates } = sessionData;
-    $effect(() => {
-        sessionData.barTopic = `Topic: ${motion.topic}`;
-    });
-
-    // Timer
-    let running: boolean = $state(false);
-    let timer: Timer | undefined = $state();
-    
-    // Speakers List
-    let speakersList: SpeakerList | undefined = $state();
-    $effect(() => {
-        if (untrack(() => order.length == 0)) {
-            order = $delegates.filter(d => d.isPresent()).map(d => createSpeaker(d.id));
-        }
-    });
-    let selectedSpeaker = $derived(speakersList?.selectedSpeaker());
-    $effect(() => {
-        if (running) untrack(() => {
-            speakersList?.start();
-        })
-    });
-    
-    function reset() {
-        timer?.reset();
-    }
-    // Button triggers
-    function next() {
-        speakersList?.next();
-    }
-</script>
-
-<div class="flex flex-col lg:flex-row h-full gap-8 items-stretch">
-    <!--
-        Under mobile, the timer encompasses the whole page 
-        and the speakers list can be accessed by scrolling down.
-
-        Under desktop, both are on the same screen,
-        with the left side being the timer and the right side being the speakers list.
-    -->
-    <!-- Left/Top -->
-    <div class="flex flex-col flex-grow flex-shrink-0 basis-full lg:basis-auto">
-        <div class="flex justify-center h-6 lg:hidden">
-            <!-- Placeholder which matches size of chevron-down -->
-        </div>
-        <div class="flex flex-col justify-center flex-grow">
-            {#key selectedSpeaker?.key}
-                <div class="pb-5" transition:lazyslide>
-                    {#if typeof selectedSpeaker !== "undefined"}
-                        <DelLabel attrs={findDelegate($delegates, selectedSpeaker.key)} />
-                    {/if}
-                </div>
-            {/key}
-            <div class="flex flex-col gap-5">
-                <Timer 
-                    name="total"
-                    duration={motion.speakingTime} 
-                    bind:this={timer}
-                    bind:running 
-                    disableKeyHandlers={typeof selectedSpeaker === "undefined"}
-                    onPause={(t) => db.updateDelegate(selectedSpeaker?.key, d => { d.stats.durationSpoken += t; })}
-                />
-                <div class="flex flex-row gap-3 justify-center">
-                    {#if !running}
-                        <button class="btn variant-filled-primary" disabled={typeof selectedSpeaker === "undefined"} onclick={() => running = true}>Start</button>
-                    {:else}
-                        <button class="btn variant-filled-primary" onclick={() => running = false}>Pause</button>
-                    {/if}
-                    <button class="btn variant-filled-primary" disabled={speakersList?.isAllDone() ?? true} onclick={next}>Next</button>
-                    <button class="btn variant-filled-primary" disabled={!timer?.canReset()} onclick={reset}>Reset</button>
-                </div>
-            </div>
-        </div>
-        <!-- Mobile chevron -->
-        <div class="flex justify-center lg:hidden">
-            <Icon icon="mdi:chevron-down" width="24" height="24" />
-        </div>
-    </div>
-    <!-- Right/Bottom -->
-    <div class="flex flex-col gap-4 h-full lg:overflow-hidden xl:min-w-[25rem] lg:max-w-[33%]">
-        <!-- List -->
-        <SpeakerList
-            bind:order
-            delegates={$delegates}
-            bind:this={speakersList}
-            onBeforeSpeakerUpdate={reset}
-            onMarkComplete={(key, isRepeat) => { if (!isRepeat) db.updateDelegate(key, d => { d.stats.timesSpoken++; }) }}
-        />
-    </div>
-</div>
\ No newline at end of file
diff --git a/src/lib/components/motions/TimerPanel.svelte b/src/lib/components/motions/TimerPanel.svelte
new file mode 100644
index 0000000..46827bf
--- /dev/null
+++ b/src/lib/components/motions/TimerPanel.svelte
@@ -0,0 +1,224 @@
+<!-- 
+  @component A component that wraps the entire panel where the timer 
+  presides in the moderated caucus/round robin/speaker list/related pages.
+
+  This panel consists of the following:
+  - the delegate label (with flag + name)
+  - 1 (or more) timers
+  - a button bar for managing the timers
+
+  This panel also automatically performs necessary logic between the timer
+  and the speaker list and database stats.
+-->
+<script lang="ts">
+    import SpeakerList from "$lib/components/SpeakerList.svelte";
+    import DelLabel from "$lib/components/del-label/DelLabel.svelte";
+    import { findDelegate, type Delegate } from "$lib/db/delegates";
+    import { db } from "$lib/db/index.svelte";
+    import { lazyslide } from "$lib/util";
+    import Icon from "@iconify/svelte";
+    import Timer from "../Timer.svelte";
+    import { untrack, type Snippet } from "svelte";
+
+    interface Props {
+        /**
+         * The delegate array.
+         */
+        delegates: Delegate[]
+
+        /**
+         * The speakers list component (to implement logic for).
+         */
+        speakersList: SpeakerList | undefined,
+
+        /**
+         * The running property for all timers.
+         * This is a **bindable** prop.
+         */
+        running?: boolean,
+
+        /**
+         * The duration (in seconds) for the timers.
+         * This prop also determines how many timers exist in this timer panel:
+         * - If `duration` is a number, this creates 1 timer with the given value as the duration
+         * - If `duration` is an array, then each element represents a timer with the element as the duration
+         * 
+         * If this timer panel is `editable`, then this is a **bindable** prop, 
+         * in which case the duration is updated when the respective timer is edited.
+         */
+        duration: number | number[],
+
+        /**
+         * Same as Timer's `editable` prop: If enabled, the maximum duration for all timers is editable.
+         */
+        editable?: boolean,
+
+        /**
+         * An optionally definable snippet. 
+         * If defined, this replaces the default "Reset" button (which resets all timers)
+         * with HTML content of your choice.
+         */
+        resetButtons?: Snippet<[typeof reset, typeof canReset]>
+    }
+    let {
+        delegates,
+        speakersList,
+        running = $bindable(false),
+        duration = $bindable(),
+        editable = false,
+        resetButtons = undefined
+    }: Props = $props();
+
+    // Creates a `timers` state with the specific number of timers.
+    // This section is a bit jank because it has to handle the two formats for `duration`.
+    const numTimers = () => duration instanceof Array ? duration.length : 1;
+    let timers = $state<(Timer | undefined)[]>(Array.from({ length: numTimers() }));
+    $effect(() => {
+        let nTimers = numTimers();
+        if (nTimers != timers.length) {
+            timers = Array.from({ length: nTimers });
+        }
+    });
+
+    // Getter/setter for duration, because there are two different formats for it.
+    function getDuration(i: number) {
+        return typeof duration === "number" ? duration : duration[i];
+    }
+    function setDuration(i: number, d: number) {
+        if (typeof duration === "number") {
+            duration = d;
+        } else {
+            duration[i] = d;
+        } 
+    }
+    
+    /**
+     * Currently selected speaker from speaker's list.
+     */
+    let selectedSpeaker = $derived(speakersList?.selectedSpeaker());
+    /**
+     * Whether timer can be started.
+     * A timer can be started if there is a speaker the timer is bound to.
+     */
+    let timerNotStartable = $derived(typeof selectedSpeaker === "undefined");
+
+    // If we switch to running, mark the current speaker as complete.
+    $effect(() => {
+        if (running) untrack(() => {
+            speakersList?.start();
+        })
+    });
+
+    /**
+     * Returns whether any of the timers can be reset.
+     * @param indices the indices to check resettable status for
+     *    (0 being the top/left-most and incrementing down/right).
+     * 
+     * **If no indices are provided, this instead resets all timers.**
+     */
+    export function canReset(...indices: number[]) {
+        if (indices.length === 0) {
+            return timers.some(t => t?.canReset());
+        } else {
+            return indices.some(i => timers[i]?.canReset());
+        }
+    }
+
+    /**
+     * Resets a given set of timers.
+     * @param indices the indices of the timers to reset
+     *    (0 being the top/left-most and incrementing down/right).
+     * 
+     * **If no indices are provided, this instead resets all timers.**
+     */
+    export function reset(...indices: number[]) {
+        if (indices.length === 0) {
+            timers.forEach(t => t?.reset());
+        } else {
+            indices.forEach(i => timers[i]?.reset());
+        }
+    }
+    function next() {
+        speakersList?.next();
+    }
+</script>
+<script module>
+    export { resetButton };
+</script>
+
+<div class="flex justify-center h-6 lg:hidden">
+    <!-- Placeholder which matches size of chevron-down -->
+</div>
+<div class="flex flex-col justify-center flex-grow">
+    {#key selectedSpeaker?.key}
+        <div class="pb-5" transition:lazyslide>
+            {#if typeof selectedSpeaker !== "undefined"}
+                <DelLabel attrs={findDelegate(delegates, selectedSpeaker.key)} />
+            {/if}
+        </div>
+    {/key}
+    <div class="flex flex-col gap-5">
+        {#each timers as _, i}
+            <!-- 
+                This const is needed because the event handlers should 
+                ONLY apply to 1 of the timers to avoid duplication.
+
+                We bind it to the last.
+            -->
+            {@const last = i == timers.length - 1}
+            <Timer
+                name="timer-{i}"
+                bind:duration={() => getDuration(i), d => setDuration(i, d)}
+                bind:running
+                bind:this={timers[i]}
+                disableKeyHandlers={!last || timerNotStartable}
+                onPause={
+                    last ? t => db.updateDelegate(selectedSpeaker?.key, d => { d.stats.durationSpoken += t; })
+                         : undefined
+                }
+                {editable}
+            />
+        {/each}
+        <!-- Button bar -->
+        <div class="flex flex-row gap-3 justify-center">
+            <!-- Start/Pause -->
+            <button 
+                class="btn variant-filled-primary"
+                disabled={!running && timerNotStartable}
+                onclick={() => running = !running}
+            >
+                {running ? 'Pause' : 'Start'}
+            </button>
+            <!-- Next -->
+            <button class="btn variant-filled-primary" disabled={speakersList?.isAllDone() ?? true} onclick={next}>Next</button>
+            <!-- Reset (or the custom defined buttons) -->
+            {@render (resetButtons ?? resetButton)(reset, canReset)}
+        </div>
+    </div>
+</div>
+<!-- Mobile chevron -->
+<div class="flex justify-center lg:hidden">
+    <Icon icon="mdi:chevron-down" width="24" height="24" />
+</div>
+
+<!-- 
+  A basic reset button.
+  @param reset The timer panel's reset callback (provided by the `resetButtons` snippet)
+  @param canReset The timer panel's canReset callback (provided by the `resetButtons` snippet)
+  @param label The text to write on this button
+  @param indices Which indices to reset (or nothing, if we wish to apply to all timers)
+-->
+{#snippet resetButton(
+    reset: (...indices: number[]) => void,
+    canReset: (...indices: number[]) => boolean,
+    label: string = "Reset",
+    indices?: number[]
+)}
+    <button
+        class="btn variant-filled-primary"
+        disabled={!canReset(...(indices ?? []))}
+        onclick={() => reset(...(indices ?? []))}
+    >
+        {label}
+    </button>
+{/snippet}
\ No newline at end of file
diff --git a/src/lib/components/motions/page/ModCaucus.svelte b/src/lib/components/motions/page/ModCaucus.svelte
new file mode 100644
index 0000000..afdd17f
--- /dev/null
+++ b/src/lib/components/motions/page/ModCaucus.svelte
@@ -0,0 +1,65 @@
+<script lang="ts">
+    import SpeakerList from "$lib/components/SpeakerList.svelte";
+    import TimerPanel, { resetButton } from "$lib/components/motions/TimerPanel.svelte";
+    import { getSessionContext } from "$lib/context/index.svelte";
+    import { db } from "$lib/db/index.svelte";
+    import { presentDelegateSchema } from "$lib/motions/form_validation";
+    import type { Motion, Speaker } from "$lib/types";
+
+    interface Props {
+        motion: Motion & { kind: "mod" };
+        order: Speaker[];
+    }
+    let { motion, order = $bindable() }: Props = $props();
+
+    const sessionData = getSessionContext();
+    const { delegates } = sessionData;
+    $effect(() => {
+        sessionData.barTopic = `Topic: ${motion.topic}`;
+    });
+
+    let timerPanel = $state<TimerPanel>();
+    let speakersList = $state<SpeakerList>();
+
+    function resetOne() {
+        timerPanel?.reset(0);
+    }
+</script>
+
+<div class="flex flex-col lg:flex-row h-full gap-8 items-stretch">
+    <!--
+        Under mobile, the timer encompasses the whole page 
+        and the speakers list can be accessed by scrolling down.
+
+        Under desktop, both are on the same screen,
+        with the left side being the timer and the right side being the speakers list.
+    -->
+    <!-- Left/Top -->
+    <div class="flex flex-col flex-grow flex-shrink-0 basis-full lg:basis-auto">
+        <TimerPanel
+            delegates={$delegates}
+            {speakersList}
+            duration={[motion.speakingTime, motion.totalTime]}
+            bind:this={timerPanel}
+        >
+        {#snippet resetButtons(reset, canReset)}
+            {@render resetButton(reset, canReset, "Reset", [0])}
+            {@render resetButton(reset, canReset, "Reset All")}
+        {/snippet}
+        </TimerPanel>
+    </div>
+    <!-- Right/Bottom -->
+    <div class="flex flex-col gap-4 h-full lg:overflow-hidden xl:min-w-[25rem] lg:max-w-[33%]">
+        <!-- List -->
+        <SpeakerList
+            bind:order
+            delegates={$delegates}
+            bind:this={speakersList}
+            useDefaultControls={{
+                validator: presentDelegateSchema
+            }}
+            onBeforeSpeakerUpdate={resetOne}
+            onMarkComplete={(key, isRepeat) => { if (!isRepeat) db.updateDelegate(key, d => { d.stats.timesSpoken++; }) }}
+        />
+    </div>
+</div>
\ No newline at end of file
diff --git a/src/lib/components/motions/README.md b/src/lib/components/motions/page/README.md
similarity index 100%
rename from src/lib/components/motions/README.md
rename to src/lib/components/motions/page/README.md
diff --git a/src/lib/components/motions/page/RoundRobin.svelte b/src/lib/components/motions/page/RoundRobin.svelte
new file mode 100644
index 0000000..2818ab1
--- /dev/null
+++ b/src/lib/components/motions/page/RoundRobin.svelte
@@ -0,0 +1,62 @@
+<script lang="ts">
+    import SpeakerList, { createSpeaker } from "$lib/components/SpeakerList.svelte";
+    import TimerPanel from "$lib/components/motions/TimerPanel.svelte";
+    import { getSessionContext } from "$lib/context/index.svelte";
+    import { db } from "$lib/db/index.svelte";
+    import type { Motion, Speaker } from "$lib/types";
+    import { untrack } from "svelte";
+
+    interface Props {
+        motion: Motion & { kind: "rr" };
+        order: Speaker[]
+    }
+    let { motion, order = $bindable() }: Props = $props();
+
+    const sessionData = getSessionContext();
+    const { delegates } = sessionData;
+    $effect(() => {
+        sessionData.barTopic = `Topic: ${motion.topic}`;
+    });
+    $effect(() => {
+        if (untrack(() => order.length == 0)) {
+            order = $delegates.filter(d => d.isPresent()).map(d => createSpeaker(d.id));
+        }
+    });
+
+    let timerPanel = $state<TimerPanel>();
+    let speakersList = $state<SpeakerList>();
+    
+    function reset() {
+        timerPanel?.reset();
+    }
+</script>
+
+<div class="flex flex-col lg:flex-row h-full gap-8 items-stretch">
+    <!--
+        Under mobile, the timer encompasses the whole page 
+        and the speakers list can be accessed by scrolling down.
+
+        Under desktop, both are on the same screen,
+        with the left side being the timer and the right side being the speakers list.
+    -->
+    <!-- Left/Top -->
+    <div class="flex flex-col flex-grow flex-shrink-0 basis-full lg:basis-auto">
+        <TimerPanel
+            delegates={$delegates}
+            {speakersList}
+            duration={motion.speakingTime}
+            bind:this={timerPanel}
+        />
+    </div>
+    <!-- Right/Bottom -->
+    <div class="flex flex-col gap-4 h-full lg:overflow-hidden xl:min-w-[25rem] lg:max-w-[33%]">
+        <!-- List -->
+        <SpeakerList
+            bind:order
+            delegates={$delegates}
+            bind:this={speakersList}
+            onBeforeSpeakerUpdate={reset}
+            onMarkComplete={(key, isRepeat) => { if (!isRepeat) db.updateDelegate(key, d => { d.stats.timesSpoken++; }) }}
+        />
+    </div>
+</div>
\ No newline at end of file
diff --git a/src/lib/components/motions/UnmodCaucus.svelte b/src/lib/components/motions/page/UnmodCaucus.svelte
similarity index 100%
rename from src/lib/components/motions/UnmodCaucus.svelte
rename to src/lib/components/motions/page/UnmodCaucus.svelte
diff --git a/src/routes/dashboard/current-motion/+page.svelte b/src/routes/dashboard/current-motion/+page.svelte
index f494de7..d95af01 100644
--- a/src/routes/dashboard/current-motion/+page.svelte
+++ b/src/routes/dashboard/current-motion/+page.svelte
@@ -1,8 +1,8 @@
 <script lang="ts">
     import { base } from "$app/paths";
-    import ModCaucus from "$lib/components/motions/ModCaucus.svelte";
-    import RoundRobin from "$lib/components/motions/RoundRobin.svelte";
-    import UnmodCaucus from "$lib/components/motions/UnmodCaucus.svelte";
+    import ModCaucus from "$lib/components/motions/page/ModCaucus.svelte";
+    import RoundRobin from "$lib/components/motions/page/RoundRobin.svelte";
+    import UnmodCaucus from "$lib/components/motions/page/UnmodCaucus.svelte";
     import { getSessionContext } from "$lib/context/index.svelte";
 
     const { selectedMotion, selectedMotionState } = getSessionContext();
diff --git a/src/routes/dashboard/speaker-list/+page.svelte b/src/routes/dashboard/speaker-list/+page.svelte
index 5960e21..00425f7 100644
--- a/src/routes/dashboard/speaker-list/+page.svelte
+++ b/src/routes/dashboard/speaker-list/+page.svelte
@@ -1,39 +1,20 @@
 <script lang="ts">
-    import DelLabel from "$lib/components/del-label/DelLabel.svelte";
     import SpeakerList from "$lib/components/SpeakerList.svelte";
-    import Timer from "$lib/components/Timer.svelte";
+    import TimerPanel from "$lib/components/motions/TimerPanel.svelte";
     import { getSessionContext } from "$lib/context/index.svelte";
     import { db } from "$lib/db/index.svelte";
-    import { findDelegate } from "$lib/db/delegates";
     import { presentDelegateSchema } from "$lib/motions/form_validation";
-    import { lazyslide } from "$lib/util";
     import { parseTime } from "$lib/util/time";
-    import Icon from "@iconify/svelte";
-    import { untrack } from "svelte";
 
     const { speakersList: order, delegates } = getSessionContext();
 
-    // Timer
-    let running: boolean = $state(false);
     let duration: number = $state(60);
-    let timer: Timer | undefined = $state();
-    
-    // Speakers List
-    let speakersList: SpeakerList | undefined = $state();
+    let timerPanel = $state<TimerPanel>();
+    let speakersList = $state<SpeakerList>();
     let durInput: string = $state("");
-    let selectedSpeaker = $derived(speakersList?.selectedSpeaker());
 
-    $effect(() => {
-        if (running) untrack(() => {
-            speakersList?.start();
-        })
-    });
     function reset() {
-        timer?.reset();
-    }
-    // Button triggers
-    function next() {
-        speakersList?.next();
+        timerPanel?.reset();
     }
     function setDuration(e: SubmitEvent) {
         e.preventDefault();
@@ -57,49 +38,20 @@
     -->
     <!-- Left/Top -->
     <div class="flex flex-col flex-grow flex-shrink-0 basis-full lg:basis-auto">
-        <div class="flex justify-center h-6 lg:hidden">
-            <!-- Placeholder which matches size of chevron-down -->
-        </div>
-        <div class="flex flex-col justify-center flex-grow">
-            {#key selectedSpeaker?.key}
-                <div class="pb-5" transition:lazyslide>
-                    {#if typeof selectedSpeaker !== "undefined"}
-                        <DelLabel attrs={findDelegate($delegates, selectedSpeaker.key)} />
-                    {/if}
-                </div>
-            {/key}
-            <div class="flex flex-col gap-5">
-                <Timer
-                    name="total"
-                    bind:duration
-                    bind:running
-                    bind:this={timer}
-                    disableKeyHandlers={typeof selectedSpeaker === "undefined"}
-                    onPause={(t) => db.updateDelegate(selectedSpeaker?.key, d => { d.stats.durationSpoken += t; })}
-                    editable
-                />
-                <div class="flex flex-row gap-3 justify-center">
-                    {#if !running}
-                        <button class="btn variant-filled-primary" disabled={typeof selectedSpeaker === "undefined"} onclick={() => running = true}>Start</button>
-                    {:else}
-                        <button class="btn variant-filled-primary" onclick={() => running = false}>Pause</button>
-                    {/if}
-                    <button class="btn variant-filled-primary" disabled={speakersList?.isAllDone() ?? true} onclick={next}>Next</button>
-                    <button class="btn variant-filled-primary" disabled={!timer?.canReset()} onclick={reset}>Reset</button>
-                </div>
-            </div>
-        </div>
-        <!-- Mobile chevron -->
-        <div class="flex justify-center lg:hidden">
-            <Icon icon="mdi:chevron-down" width="24" height="24" />
-        </div>
+        <TimerPanel
+            delegates={$delegates}
+            {speakersList}
+            bind:duration
+            bind:this={timerPanel}
+            editable
+        />
     </div>
     <!-- Right/Bottom -->
     <div class="flex flex-col gap-4 h-full lg:overflow-hidden xl:min-w-[25rem] lg:max-w-[33%]">
         <!-- List -->
         <SpeakerList
-            bind:order={$order}
             delegates={$delegates}
+            bind:order={$order}
             bind:this={speakersList}
             useDefaultControls={{
                 validator: presentDelegateSchema

From 010d77ab5b6775218a3919b35b88caa8db754a09 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Wed, 8 Jan 2025 23:43:48 -0500
Subject: [PATCH 05/21] Improve`IconLabel`'s doc

---
 src/lib/components/IconLabel.svelte | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/lib/components/IconLabel.svelte b/src/lib/components/IconLabel.svelte
index bab0bfa..faef141 100644
--- a/src/lib/components/IconLabel.svelte
+++ b/src/lib/components/IconLabel.svelte
@@ -1,17 +1,32 @@
 <!--
-    @component
-    
-    A piece of text that can be replaced with an icon on smaller screens.
+    @component A piece of text that can be replaced with an icon on smaller screens.
 -->
 
 <script lang="ts">
     import Icon from "@iconify/svelte";
 
     interface Props {
+        /**
+         * The icon to use.
+         */
         icon: string,
+        /**
+         * The label if the screen is wide enough.
+         */
         label: string,
+        /**
+         * The screen width needed for the text to take effect.
+         * This is any of Tailwind's default media sizes (e.g., 'sm', 'md', 'lg', etc.)
+         */
         size?: string,
+
+        /**
+         * The width of the icon (default 24).
+         */
         iconWidth?: number,
+        /**
+         * The height of the icon (default 24).
+         */
         iconHeight?: number
     }
 

From 90b5dab6b04f6081b052398b5a85aab9b6210661 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Thu, 9 Jan 2025 15:47:55 -0500
Subject: [PATCH 06/21] App Bar components

---
 src/lib/components/app-bar/BarHeader.svelte | 13 ++++++--
 src/lib/components/app-bar/BarStats.svelte  | 33 +++++++++++++++++----
 2 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/src/lib/components/app-bar/BarHeader.svelte b/src/lib/components/app-bar/BarHeader.svelte
index 2ebc9df..8dce17f 100644
--- a/src/lib/components/app-bar/BarHeader.svelte
+++ b/src/lib/components/app-bar/BarHeader.svelte
@@ -1,8 +1,15 @@
+<!--
+  @component The title text in the header.
+-->
 <script lang="ts">
     interface Props {
+        /** Title text */
         title: string,
+        /** Size of text (using Tailwind media sizes) */
         size?: "sm" | "md" | "lg",
+        /** Additional properties to apply to the title */
         styles?: string,
+        /** Whether the title is editable (by default, this is true) */
         editable?: boolean
     }
 
@@ -15,10 +22,10 @@
             heading.textContent = title = heading.textContent?.trim() || title;
         }
     }
-    function keyDown(k: KeyboardEvent) {
+    function keyDown(e: KeyboardEvent) {
         // If Enter is pressed, unfocus the title
-        if (k.code === "Enter") {
-            k.preventDefault();
+        if (e.code === "Enter") {
+            e.preventDefault();
             heading?.blur();
         }
     }
diff --git a/src/lib/components/app-bar/BarStats.svelte b/src/lib/components/app-bar/BarStats.svelte
index 522092f..983bfff 100644
--- a/src/lib/components/app-bar/BarStats.svelte
+++ b/src/lib/components/app-bar/BarStats.svelte
@@ -1,9 +1,24 @@
+<!-- 
+  @component Bar stats, consisting of 3 bubbles and the 3 attendance numbers.
+-->
+
 <script lang="ts">
     import { ConicGradient, type ConicStop } from '@skeletonlabs/skeleton';
 
     interface Props {
+        /**
+         * Total attendance.
+         */
         total: number;
+        /**
+         * An override for the majority value
+         * (if the default calculation is not sufficient).
+         */
         majOverride?: number | undefined;
+        /**
+         * An override for the supermajority value
+         * (if the default calculation is not sufficient).
+         */
         supermajOverride?: number | undefined;
     }
     let {
@@ -12,12 +27,11 @@
         supermajOverride = undefined
     }: Props = $props();
 
-    // given n,
-    // maj is smallest integer > n/2
-    // supermaj is smallest integer > 2n/3
-    // TODO: make this cleaner
-    let maj = $derived(majOverride ?? total >= 1 ? Math.ceil(total / 2 + 0.01) : 0);
-    let supermaj = $derived(supermajOverride ?? total >= 1 ? Math.ceil(total * 2 / 3 + 0.01) : 0);
+    // Given the total attendance (n),
+    // the majority is the smallest integer > n/2
+    // the supermajority is the smallest integer > 2/3 n
+    let maj: number = $derived(majOverride ?? smallestIntegerGt(total / 2));
+    let supermaj: number = $derived(supermajOverride ?? smallestIntegerGt(total * 2 / 3));
 
     const majConic: ConicStop[] = [
         { color: 'rgb(var(--color-primary-800))', start: 0, end: 50 },
@@ -30,6 +44,13 @@
     const totalConic: ConicStop[] = [
         { color: 'rgb(var(--color-tertiary-500))', start: 0, end: 100 },
     ];
+    /**
+     * Smallest integer greater than `n`, capped to at least 0.
+     * @param n total
+     */
+    function smallestIntegerGt(n: number) {
+        return Math.max(0, Math.ceil(n + 0.01));
+    }
 </script>
 
 <div class="flex flex-row gap-3 justify-center">

From 9705a805998f2d4aa3dd96a5444f0f5b2211885d Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Thu, 9 Jan 2025 23:20:27 -0500
Subject: [PATCH 07/21] LabeledSlideToggle, MetaTags, Navigation,
 SettingsNavigation

---
 src/lib/components/IconLabel.svelte           |  2 +-
 src/lib/components/LabeledSlideToggle.svelte  |  2 --
 src/lib/components/MetaTags.svelte            |  6 ++++
 src/lib/components/nav/Navigation.svelte      | 12 +++++++
 .../components/nav/SettingsNavigation.svelte  | 32 +++++++++++++++----
 src/routes/dashboard/+layout.svelte           |  2 +-
 6 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/src/lib/components/IconLabel.svelte b/src/lib/components/IconLabel.svelte
index faef141..c5ce8fb 100644
--- a/src/lib/components/IconLabel.svelte
+++ b/src/lib/components/IconLabel.svelte
@@ -1,5 +1,5 @@
 <!--
-    @component A piece of text that can be replaced with an icon on smaller screens.
+    @component A text label that is replaced with an icon on smaller screens.
 -->
 
 <script lang="ts">
diff --git a/src/lib/components/LabeledSlideToggle.svelte b/src/lib/components/LabeledSlideToggle.svelte
index 7b640d6..72624b4 100644
--- a/src/lib/components/LabeledSlideToggle.svelte
+++ b/src/lib/components/LabeledSlideToggle.svelte
@@ -1,4 +1,3 @@
-<!-- @migration-task Error while migrating Svelte code: $$props is used together with named props in a way that cannot be automatically migrated. -->
 <script lang="ts">
     import { SlideToggle } from "@skeletonlabs/skeleton";
     import { type Snippet } from "svelte";
@@ -21,7 +20,6 @@
     }: Props = $props();
 </script>
 
-<!-- svelte-ignore a11y_label_has_associated_control : SlideToggle is a control -->
 <label class={labelClass}>
     {@render children()}
     <SlideToggle 
diff --git a/src/lib/components/MetaTags.svelte b/src/lib/components/MetaTags.svelte
index 90dd6f2..b826e64 100644
--- a/src/lib/components/MetaTags.svelte
+++ b/src/lib/components/MetaTags.svelte
@@ -1,3 +1,9 @@
+<!-- 
+  @component Component that adds special SEO tags to the webpage.
+
+  This can be located anywhere in the `+page.svelte`,
+  but it preferably should be on the top level.
+-->
 <script lang="ts">
     import { page } from "$app/state";
 
diff --git a/src/lib/components/nav/Navigation.svelte b/src/lib/components/nav/Navigation.svelte
index 166614d..136c0f9 100644
--- a/src/lib/components/nav/Navigation.svelte
+++ b/src/lib/components/nav/Navigation.svelte
@@ -1,9 +1,21 @@
+<!--
+  @component The navigation drawer, accessible on the left-hand side of the UI.
+
+  This drawer allows users to visit different pages on the site.
+-->
 <script lang="ts">
     import { base } from "$app/paths";
     import { page } from "$app/state";
 
     interface Props {
+        /**
+         * Record of accessible links and their display name.
+         */
         links: Record<string, { label: string }>;
+        /**
+         * A method callback that "closes" the drawer that 
+         * this navigation resides under.
+         */
         close: () => void;
     }
     let { links, close }: Props = $props();
diff --git a/src/lib/components/nav/SettingsNavigation.svelte b/src/lib/components/nav/SettingsNavigation.svelte
index 215ccad..ab2d939 100644
--- a/src/lib/components/nav/SettingsNavigation.svelte
+++ b/src/lib/components/nav/SettingsNavigation.svelte
@@ -1,3 +1,8 @@
+<!-- 
+  @component The settings and admin navigation drawer, accessible on the right-hand side of the UI.
+
+  This drawer allows users to visit different **admin** pages and configure various settings on the site.
+ -->
 <script lang="ts">
     import { goto } from "$app/navigation";
     import { base } from "$app/paths";
@@ -8,6 +13,10 @@
     import { LightSwitch } from "@skeletonlabs/skeleton";
 
     interface Props {
+        /**
+         * A method callback that "closes" the drawer that 
+         * this navigation resides under.
+         */
         close: () => void;
     }
     let { close }: Props = $props();
@@ -16,7 +25,11 @@
     const selectedSession = queryStore(() => db.getSessionValue("sessionKey"));
     const sessionData = getSessionContext();
     
-    async function clearSession() {
+    /**
+     * This implements the functionality of the "Add Session" button.
+     * Saves the current session and creates a new session.
+     */
+    async function createNewSession() {
         await db.saveSessionData();
         await resetSessionContext(sessionData);
         goto(`${base}/dashboard/roll-call`);
@@ -29,6 +42,7 @@
 </div>
 <hr />
 
+<!-- External link to admin pages -->
 <nav class="list-nav p-2">
     <ul>
         <a onclick={close} href="{base}/admin/settings" tabindex="0">
@@ -42,6 +56,7 @@
 
 <hr />
 
+<!-- Theming -->
 <div class="p-4 flex flex-col gap-3">
     <div class="flex gap-3 items-center">
         <h3 class="h3">Theme</h3>
@@ -54,20 +69,24 @@
 
 <hr />
 
+<!-- Session management -->
+
+<!-- A session row, which currently just consists of the "switch to this session" button -->
 {#snippet sessionRow(key?: number)}
     {@const selected = $selectedSession === key}
+    {@const displayKey = +(key ?? $prevSessions.length) + 1}
     <button
         class="btn {selected ? "variant-filled-primary" : "variant-soft-surface"}"
         onclick={() => { if (typeof key === "number" && !selected) db.loadSessionData(key); }}
+        aria-label="Select{selected ? "ed" : ""} Session {displayKey}"
+        aria-pressed={selected}
     >
-        Session {+(key ?? $prevSessions.length) + 1}
+        Session {displayKey}
     </button>
-    <div>
-        <!-- Buttons -->
-    </div>
 {/snippet}
 <div class="p-4 flex flex-col gap-3">
     <div class="grid grid-cols-1 gap-1">
+        <!-- All sessions -->
         {#each $prevSessions as sessionKey}
             {@render sessionRow(+sessionKey)}
         {/each}
@@ -75,9 +94,10 @@
             {@render sessionRow(undefined)}
         {/if}
     </div>
+    <!-- Add session button -->
     <button 
         class="btn variant-ghost-surface" 
-        onclick={clearSession}
+        onclick={createNewSession}
     >
         <Icon icon="mdi:plus" width="24" height="24" />
         Add Session
diff --git a/src/routes/dashboard/+layout.svelte b/src/routes/dashboard/+layout.svelte
index 37a1e49..af070a0 100644
--- a/src/routes/dashboard/+layout.svelte
+++ b/src/routes/dashboard/+layout.svelte
@@ -56,7 +56,7 @@
 <Drawer>
     {#if $drawerStore.id === "navigation"}
         <Navigation close={drawerStore.close} {links} />
-        {:else if $drawerStore.id === "settings"}
+    {:else if $drawerStore.id === "settings"}
         <SettingsNavigation close={drawerStore.close} />
     {/if}
 </Drawer>

From d53e3df80c5c8b2e770b69c4d4a405df40612493 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Fri, 10 Jan 2025 00:17:23 -0500
Subject: [PATCH 08/21] popup refactor (delete DelPopup.svelte, create
 popup.ts), doc DelAutocomplete

---
 src/lib/components/DelAutocomplete.svelte     | 75 +++++++++++++++
 src/lib/components/MotionForm.svelte          | 27 ++++--
 src/lib/components/SpeakerList.svelte         | 20 ++--
 .../del-input/DelAutocomplete.svelte          | 33 -------
 src/lib/components/del-input/DelPopup.svelte  | 53 -----------
 src/lib/components/del-input/README.md        | 53 -----------
 src/lib/util/popup.ts                         | 58 +++++++++++
 src/routes/admin/stats/+page.svelte           | 21 ++--
 src/routes/dashboard/utilities/+page.svelte   | 95 +++++++++----------
 9 files changed, 214 insertions(+), 221 deletions(-)
 create mode 100644 src/lib/components/DelAutocomplete.svelte
 delete mode 100644 src/lib/components/del-input/DelAutocomplete.svelte
 delete mode 100644 src/lib/components/del-input/DelPopup.svelte
 delete mode 100644 src/lib/components/del-input/README.md
 create mode 100644 src/lib/util/popup.ts

diff --git a/src/lib/components/DelAutocomplete.svelte b/src/lib/components/DelAutocomplete.svelte
new file mode 100644
index 0000000..8c5b445
--- /dev/null
+++ b/src/lib/components/DelAutocomplete.svelte
@@ -0,0 +1,75 @@
+<!-- 
+  @component A wrapper around Skeleton's `<Autocomplete>` component 
+  that makes it easier to manage Delegate autocomplete.
+
+  To create a Delegate autocomplete item, bound the `use:popup={autocompletePopup(POPUP_TARGET)}` 
+  (from `popup.ts`) on the corresponding `input`.
+
+  Then, create a popup with a `<DelAutocomplete>` component in it:
+  ```svelte
+    <div class="{POPUP_CARD_CLASSES}" data-popup={POPUP_TARGET}>
+        <DelAutocomplete
+            bind:input
+            {delegates}
+            on:selection={e => "actions to perform when item has been selected in autocomplete"}
+        />
+    </div>
+  ```
+-->
+
+<script lang="ts">
+    import type { Delegate } from "$lib/db/delegates";
+    import { Autocomplete, type AutocompleteOption } from "@skeletonlabs/skeleton";
+
+    interface Props {
+        /**
+         * Bindable property representing the input text which the autocomplete tries to complete.
+         */
+        input: string | undefined;
+        /**
+         * List of delegates. The autocomplete will automatically filter out non-present delegates.
+         */
+        delegates: Delegate[];
+        /**
+         * Tailwind class representing the maximum height of the autocomplete box.
+         */
+        maxHeight?: string;
+    }
+
+    let {
+        input = $bindable(),
+        delegates,
+        maxHeight = "max-h-96"
+    }: Props = $props();
+
+    let options = $derived(
+        delegates
+            .filter(d => d.isPresent())
+            .map(d => ({
+                value: d.id,
+                label: d.name,
+                keywords: d.aliases.join(",")
+            }) satisfies AutocompleteOption<number>)
+    );
+</script>
+
+<script lang="ts" module>
+    /**
+     * Defaults for an `<input>` element which triggers a delegate autocomplete.
+     * @param noDelsPresent state indicating whether any delegates are present.
+     * @returns the placeholders
+     */
+    export function autocompletePlaceholders(noDelsPresent: boolean) {
+        return {
+            disabled: noDelsPresent,
+            placeholder: !noDelsPresent ? "Select a delegate..." : "No delegates present",
+        };
+    }
+</script>
+
+<Autocomplete
+    class="overflow-y-auto {maxHeight}"
+    bind:input
+    {options}
+    on:selection
+/>
\ No newline at end of file
diff --git a/src/lib/components/MotionForm.svelte b/src/lib/components/MotionForm.svelte
index 908d715..0ae070f 100644
--- a/src/lib/components/MotionForm.svelte
+++ b/src/lib/components/MotionForm.svelte
@@ -1,10 +1,11 @@
 <script lang="ts">
     import LabeledSlideToggle from "$lib/components/LabeledSlideToggle.svelte";
-    import DelPopup, { defaultPlaceholder, defaultPopupSettings } from "$lib/components/del-input/DelPopup.svelte";
+    import DelAutocomplete, { autocompletePlaceholders } from "$lib/components/DelAutocomplete.svelte";
     import { getSessionContext } from "$lib/context/index.svelte";
     import { createMotionSchema, inputifyMotion, MOTION_FIELDS, MOTION_LABELS } from "$lib/motions/definitions";
     import { formatValidationError } from "$lib/motions/form_validation";
     import type { MotionInput, MotionInputWithFields } from "$lib/motions/types";
+    import { autocompletePopup, POPUP_CARD_CLASSES } from "$lib/util/popup";
     import { addColons, parseTime } from "$lib/util/time";
     import type { Motion } from "$lib/types";
     
@@ -35,7 +36,8 @@
     let afterDel: HTMLElement | undefined = $state();
 
     let noDelegatesPresent = $derived($delegates.every(d => !d.isPresent()));
-
+    const POPUP_TARGET = "delegate-input-popup";
+    
     function submitMotion(e: SubmitEvent) {
         e.preventDefault();
 
@@ -131,8 +133,8 @@
             class:input-error={inputError?.path.includes("delegate")}
             bind:value={inputMotion.delegate}
             required
-            use:popup={{...defaultPopupSettings("delegateInputPopup"), event: "focus-click"}}
-            {...defaultPlaceholder(noDelegatesPresent)}
+            use:popup={autocompletePopup(POPUP_TARGET)}
+            {...autocompletePlaceholders(noDelegatesPresent)}
         >
     </label>
     <label class="label">
@@ -212,10 +214,15 @@
     {/if}
 
     <!-- Delegate autocomplete popup -->
-    <DelPopup
-        popupID="delegateInputPopup"
-        bind:input={inputMotion.delegate}
-        delegates={$delegates}
-        on:selection={e => {inputMotion.delegate = e.detail.label; resetInputErrors(); afterDel?.focus()}}
-    />
+    <div class="{POPUP_CARD_CLASSES}" data-popup={POPUP_TARGET}>
+        <DelAutocomplete
+            bind:input={inputMotion.delegate}
+            delegates={$delegates}
+            on:selection={e => {
+                inputMotion.delegate = e.detail.label;
+                resetInputErrors();
+                afterDel?.focus();
+            }}
+        />
+    </div>
 </form>
\ No newline at end of file
diff --git a/src/lib/components/SpeakerList.svelte b/src/lib/components/SpeakerList.svelte
index 130d34c..c70da49 100644
--- a/src/lib/components/SpeakerList.svelte
+++ b/src/lib/components/SpeakerList.svelte
@@ -1,6 +1,6 @@
 <script lang="ts">
     import DelLabel from "$lib/components/del-label/DelLabel.svelte";
-    import DelPopup, { defaultPlaceholder, defaultPopupSettings } from "$lib/components/del-input/DelPopup.svelte";
+    import DelAutocomplete, { autocompletePlaceholders } from "$lib/components/DelAutocomplete.svelte";
     import { type Delegate, findDelegate } from "$lib/db/delegates";
     import { formatValidationError } from "$lib/motions/form_validation";
     import type { DelegateID, Speaker, SpeakerEntryID } from "$lib/types";
@@ -13,6 +13,7 @@
     import { tick, untrack } from "svelte";
     import { flip } from "svelte/animate";
     import { dragHandle, dragHandleZone } from "svelte-dnd-action";
+    import { autocompletePopup, POPUP_CARD_CLASSES } from "$lib/util/popup";
 
     let dfltControlsInput: string = $state("");
     let dfltControlsError: string | undefined = $state(undefined);
@@ -286,8 +287,8 @@
                         class="input" 
                         class:input-error={error}
                         bind:value={dfltControlsInput}
-                        use:popup={{ ...defaultPopupSettings(popupID), placement: "left-end", event: "focus-click" }}
-                        {...defaultPlaceholder(noDelegatesPresent)}
+                        use:popup={{ ...autocompletePopup(popupID), placement: "left-end" }}
+                        {...autocompletePlaceholders(noDelegatesPresent)}
                     />
                     <div class="ml-2">
                         <button
@@ -327,12 +328,13 @@
 
             The solution used here is to not put another element over the popup :)
         -->
-        <DelPopup 
-            {popupID}
-            bind:input={dfltControlsInput}
-            {delegates}
-            on:selection={e => addSpeaker(e.detail.label, true)}
-        />
+        <div class="{POPUP_CARD_CLASSES}" data-popup={popupID}>
+            <DelAutocomplete
+                bind:input={dfltControlsInput}
+                {delegates}
+                on:selection={e => addSpeaker(e.detail.label, true)}
+            />
+        </div>
     {/if}
 </div>
 
diff --git a/src/lib/components/del-input/DelAutocomplete.svelte b/src/lib/components/del-input/DelAutocomplete.svelte
deleted file mode 100644
index fc43983..0000000
--- a/src/lib/components/del-input/DelAutocomplete.svelte
+++ /dev/null
@@ -1,33 +0,0 @@
-<script lang="ts">
-    import type { Delegate } from "$lib/db/delegates";
-    import { Autocomplete, type AutocompleteOption } from "@skeletonlabs/skeleton";
-
-    interface Props {
-        input: string | undefined;
-        delegates: Delegate[];
-        maxHeight?: string;
-    }
-
-    let {
-        input = $bindable(),
-        delegates,
-        maxHeight = "max-h-96"
-    }: Props = $props();
-
-    let options = $derived(
-        delegates
-            .filter(d => d.isPresent())
-            .map(d => ({
-                value: d.id,
-                label: d.name,
-                keywords: d.aliases.join(",")
-            }) satisfies AutocompleteOption<number>)
-    );
-</script>
-
-<Autocomplete
-    class="overflow-y-auto {maxHeight}"
-    bind:input
-    {options}
-    on:selection
-/>
\ No newline at end of file
diff --git a/src/lib/components/del-input/DelPopup.svelte b/src/lib/components/del-input/DelPopup.svelte
deleted file mode 100644
index c2f39a4..0000000
--- a/src/lib/components/del-input/DelPopup.svelte
+++ /dev/null
@@ -1,53 +0,0 @@
-<script lang="ts">
-    import DelAutocomplete from "$lib/components/del-input/DelAutocomplete.svelte";
-    import type { Delegate } from "$lib/db/delegates";
-    import { type PopupSettings } from "@skeletonlabs/skeleton";
-
-    interface Props {
-        popupID: string;
-        input: string | undefined;
-        delegates: Delegate[];
-        maxHeight?: string;
-    }
-    let {
-        popupID,
-        input = $bindable(),
-        delegates,
-        maxHeight = "max-h-96"
-    }: Props = $props();
-</script>
-
-<script lang="ts" module>
-    export function defaultPopupSettings(target: string): PopupSettings {
-        return {
-            event: 'focus-click',
-            target,
-            placement: 'bottom',
-            middleware: {
-                size: {
-                    apply({availableHeight, elements}: any) {
-                        Object.assign(elements.floating.style, {
-                            maxHeight: `${availableHeight}px`,
-                        });
-                    },
-                }
-            }
-        };
-    }
-
-    export function defaultPlaceholder(noDelegatesPresent: boolean) {
-        return {
-            disabled: noDelegatesPresent,
-            placeholder: !noDelegatesPresent ? "Select a delegate..." : "No delegates present",
-        };
-    }
-</script>
-
-<div class="card overflow-hidden p-2" data-popup={popupID} tabindex="-1">
-    <DelAutocomplete
-        bind:input
-        {delegates}
-        {maxHeight}
-        on:selection
-    />
-</div>
\ No newline at end of file
diff --git a/src/lib/components/del-input/README.md b/src/lib/components/del-input/README.md
deleted file mode 100644
index ea3e4e3..0000000
--- a/src/lib/components/del-input/README.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Delegate Input Components
-
-Components relating to text input for delegates. This folder consists of:
-
-- `DelAutocomplete`: A small component that displays the list of suggested delegate options.
-- `DelPopup`: A popup wrapper encapsulating a `DelAutocomplete` component
-
-These components allow a suggestion popup to display next to a delegate `<input>`, allowing directors to quickly fill in the name of delegates.
-
-## Usage
-
-To bind a `DelPopup` element to an `<input>` element, there are a few steps:
-
-1. Declare a `<DelPopup>` component near the bottom of the page (any element that follows `<DelPopup>` can cover the popup, so it has to be near the end. Increasing `z-index` does not fix this).
-2. Bind `delegates` props of `<DelPopup>` to a list of delegates. These can typically be bound to the `$delegates` store, which can be generated from the delegates database with `enabledDelegatesStore(.)`.
-3. Bind the `<DelPopup>` component's `input` prop to the same value as the `<input>` element's `value` prop
-4. Set `on:selection` to update the `input` variable in `<DelPopup>` to `e.detail.label`
-5. use the [Skeleton UI popup action](https://www.skeleton.dev/utilities/popups) on the `input` prop, matching the `target` setting to the `<DelPopup>` component's `popupID` prop.
-
-`DelPopup` also provides two utility functions that can be used to reduce the amount of settings that need to be configured:
-
-- `defaultPopupSettings(popupId: string)`: Creates a default popup configuration to be used for the `popup` action (see #3)
-- `defaultPlaceholder(noDelegatesPresent)`: Declares an object to automatically handle `disabled` and `placeholder` props.
-
-The bindings should look similar to this:
-
-```svelte
-<script lang="ts">
-    import DelPopup, { defaultPlaceholder, defaultPopupSettings } from "$lib/components/del-input/DelPopup.svelte";
-    
-    let inputValue: string;
-    let delegates = enabledDelegatesStore(db.delegates);
-    let noDelegatesPresent = $derived(delegates.every(d => !d.isPresent()));
-</script>
-
-<!-- ... -->
-
-<input 
-  class="input"
-  bind:value={inputValue}
-  use:popup={defaultPopupSettings("delegatePopup")}
-  {...defaultPlaceholder(noDelegatesPresent)}
->
-
-<!-- ... -->
- 
-<DelPopup
-  popupID="delegatePopup"
-  bind:input={inputValue}
-  delegates={$delegates}
-  on:selection={e => inputValue = e.detail.label}
-/>
-```
diff --git a/src/lib/util/popup.ts b/src/lib/util/popup.ts
new file mode 100644
index 0000000..712c225
--- /dev/null
+++ b/src/lib/util/popup.ts
@@ -0,0 +1,58 @@
+/**
+ * Utilities for creating and managing popups.
+ * 
+ * The basic setup is the following:
+ * - On the element you need to trigger the popup on, you attach the `use:popup={interactivePopup(POPUP_TARGET)}` action.
+ * - To create the popup, create a popup `<div>`, like so:
+ * ```html
+ * <div class="{POPUP_CARD_CLASSES}" data-popup={POPUP_TARGET}>
+ *     <!-- contents -->
+ * </div>
+ * ```
+ * 
+ * For additional details on autocomplete popups, see `DelAutocomplete.svelte`.
+ */
+
+import type { PopupSettings } from "@skeletonlabs/skeleton";
+
+/**
+ * Default Tailwind classes for popup cards.
+ */
+export const POPUP_CARD_CLASSES = "card overflow-hidden p-4";
+
+/**
+ * Defaults for a popup whose contents are meant to be interacted with
+ * and not dismissed when interacted with.
+ * 
+ * @param target popup ID
+ * @returns the settings
+ */
+export function interactivePopup(target: string): PopupSettings {
+    return {
+        event: 'focus-click',
+        target,
+        closeQuery: ''
+    }
+}
+
+/**
+ * Defaults for a popup which holds an autocomplete module.
+ * @param target popup ID
+ * @returns the settings
+ */
+export function autocompletePopup(target: string): PopupSettings {
+    return {
+        event: 'focus-click',
+        target,
+        placement: 'bottom',
+        middleware: {
+            size: {
+                apply({availableHeight, elements}: any) {
+                    Object.assign(elements.floating.style, {
+                        maxHeight: `${availableHeight}px`,
+                    });
+                },
+            }
+        }
+    };
+}
diff --git a/src/routes/admin/stats/+page.svelte b/src/routes/admin/stats/+page.svelte
index e75ead4..bbbebc0 100644
--- a/src/routes/admin/stats/+page.svelte
+++ b/src/routes/admin/stats/+page.svelte
@@ -6,6 +6,7 @@
     import { Delegate } from "$lib/db/delegates";
     import type { StatsData } from "$lib/types";
     import { compare, downloadFile } from "$lib/util";
+    import { interactivePopup, POPUP_CARD_CLASSES } from "$lib/util/popup";
     import { stringifyTime } from "$lib/util/time";
     
     import Icon from "@iconify/svelte";
@@ -94,11 +95,7 @@
     );
 
     // Configuration
-    const CONFIGURE_MODAL_SETTINGS: PopupSettings = {
-        event: "focus-click",
-        target: "stats-button",
-        closeQuery: ''
-    }
+    const POPUP_TARGET = "export-stats-popup";
     function exportStats() {
         let data = {
             committee: $barTitle,
@@ -129,7 +126,7 @@
             class="btn-icon variant-filled-warning"
             aria-label="Edit Stats"
             title="Edit Stats"
-            use:popup={CONFIGURE_MODAL_SETTINGS}
+            use:popup={interactivePopup(POPUP_TARGET)}
         >
             <Icon icon="mdi:database-export-outline" width="24" height="24" />
         </button>
@@ -202,12 +199,10 @@
       
 </div>
 
-<div data-popup="stats-button">
-    <div class="card p-4 bg-surface-300-600-token">
-        <div class="flex flex-col gap-2 overflow-hidden">
-            <h4 class="h4">Export Statistics</h4>
-            <button class="btn variant-filled-primary" onclick={exportAllStats}>Export All Sessions</button>
-            <button class="btn variant-filled-primary" onclick={exportStats}>Export Session {pageSettings.page + 1}</button>
-        </div>
+<div class="{POPUP_CARD_CLASSES}" data-popup={POPUP_TARGET}>
+    <div class="flex flex-col gap-2 overflow-hidden">
+        <h4 class="h4">Export Statistics</h4>
+        <button class="btn variant-filled-primary" onclick={exportAllStats}>Export All Sessions</button>
+        <button class="btn variant-filled-primary" onclick={exportStats}>Export Session {pageSettings.page + 1}</button>
     </div>
 </div>
\ No newline at end of file
diff --git a/src/routes/dashboard/utilities/+page.svelte b/src/routes/dashboard/utilities/+page.svelte
index de3b39f..fe603a9 100644
--- a/src/routes/dashboard/utilities/+page.svelte
+++ b/src/routes/dashboard/utilities/+page.svelte
@@ -1,10 +1,11 @@
 <script lang="ts">
-    import DelAutocomplete from "$lib/components/del-input/DelAutocomplete.svelte";
+    import DelAutocomplete from "$lib/components/DelAutocomplete.svelte";
     import DelLabel from "$lib/components/del-label/DelLabel.svelte";
     import LabeledSlideToggle from "$lib/components/LabeledSlideToggle.svelte";
     import Timer from "$lib/components/Timer.svelte";
     import { getSessionContext } from "$lib/context/index.svelte";
     import { lazyslide } from "$lib/util";
+    import { interactivePopup, POPUP_CARD_CLASSES } from "$lib/util/popup";
     import { parseTime } from "$lib/util/time";
 
     import Icon from "@iconify/svelte";
@@ -25,11 +26,7 @@
     let labelText: string = $state("");
 
     // Configuration
-    const CONFIGURE_MODAL_SETTINGS: PopupSettings = {
-        event: "focus-click",
-        target: "configure",
-        closeQuery: ''
-    }
+    const POPUP_TARGET = "configure-popup";
     function setDuration() {
         let secs = parseTime(durInput);
         if (typeof secs !== "undefined") {
@@ -46,7 +43,7 @@
 <div class="flex flex-col h-full items-stretch">
     <button
         class="btn-icon variant-filled-surface self-end"
-        use:popup={CONFIGURE_MODAL_SETTINGS}
+        use:popup={interactivePopup(POPUP_TARGET)}
         aria-label="Configure Utilities"
         title="Configure Utilities"
     >
@@ -84,51 +81,49 @@
     </div>
 </div>
 
-<div data-popup="configure">
-    <div class="card p-4">
-        <div class="flex flex-col gap-4 overflow-hidden">
-            <!-- Timer config -->
-             <LabeledSlideToggle name="enable-timer" bind:checked={timerEnabled}>
-                <span><strong>Timer</strong></span>
-             </LabeledSlideToggle>
-            {#if timerEnabled}
-                <div class="flex flex-row gap-5">
-                    <form class="contents" onsubmit={submitDuration}>
-                        <label class="flex flex-grow items-center justify-between gap-3">
-                            <span>Time</span>
-                            <input class="input" bind:value={durInput} oninput={setDuration} placeholder="mm:ss" />
-                        </label>
-                    </form>
-                </div>
-            {/if}
-            <hr />
-            <!-- Label config -->
-            <form class="contents">
-                <label class="flex flex-grow items-center justify-between gap-3">
-                    <span><strong>Label</strong></span>
-                    <select class="select" bind:value={labelType}>
-                        <option value="delegate" label="Delegate"></option>
-                        <option value="title" label="Title"></option>
-                        <option value="none" label="None"></option>
-                    </select>
-                </label>
-                {#if labelType !== "none"}
+<div class="{POPUP_CARD_CLASSES}" data-popup={POPUP_TARGET}>
+    <div class="flex flex-col gap-4 overflow-hidden">
+        <!-- Timer config -->
+            <LabeledSlideToggle name="enable-timer" bind:checked={timerEnabled}>
+            <span><strong>Timer</strong></span>
+            </LabeledSlideToggle>
+        {#if timerEnabled}
+            <div class="flex flex-row gap-5">
+                <form class="contents" onsubmit={submitDuration}>
                     <label class="flex flex-grow items-center justify-between gap-3">
-                        <span>Text</span>
-                        <input class="input" bind:value={labelText} />
+                        <span>Time</span>
+                        <input class="input" bind:value={durInput} oninput={setDuration} placeholder="mm:ss" />
                     </label>
-                    {#if labelType === "delegate"}
-                        <div class="card bg-surface-200-700-token">
-                            <DelAutocomplete
-                                bind:input={labelText}
-                                delegates={Object.values($delegates)}
-                                maxHeight="max-h-36"
-                                on:selection={e => labelText = e.detail.label}
-                            />
-                        </div>
-                    {/if}
+                </form>
+            </div>
+        {/if}
+        <hr />
+        <!-- Label config -->
+        <form class="contents">
+            <label class="flex flex-grow items-center justify-between gap-3">
+                <span><strong>Label</strong></span>
+                <select class="select" bind:value={labelType}>
+                    <option value="delegate" label="Delegate"></option>
+                    <option value="title" label="Title"></option>
+                    <option value="none" label="None"></option>
+                </select>
+            </label>
+            {#if labelType !== "none"}
+                <label class="flex flex-grow items-center justify-between gap-3">
+                    <span>Text</span>
+                    <input class="input" bind:value={labelText} />
+                </label>
+                {#if labelType === "delegate"}
+                    <div class="card bg-surface-200-700-token">
+                        <DelAutocomplete
+                            bind:input={labelText}
+                            delegates={Object.values($delegates)}
+                            maxHeight="max-h-36"
+                            on:selection={e => labelText = e.detail.label}
+                        />
+                    </div>
                 {/if}
-            </form>
-        </div>
+            {/if}
+        </form>
     </div>
 </div>
\ No newline at end of file

From baa2ac102d9d566ad3d6646915b04b245a3ea38e Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Tue, 14 Jan 2025 14:19:18 -0500
Subject: [PATCH 09/21] doc SpeakersList + slight refactor

---
 src/lib/components/SpeakerList.svelte         | 160 ++++++++++++------
 .../components/motions/page/ModCaucus.svelte  |   4 -
 .../components/motions/page/RoundRobin.svelte |   4 +-
 .../dashboard/speaker-list/+page.svelte       |   4 -
 4 files changed, 109 insertions(+), 63 deletions(-)

diff --git a/src/lib/components/SpeakerList.svelte b/src/lib/components/SpeakerList.svelte
index c70da49..75e5df9 100644
--- a/src/lib/components/SpeakerList.svelte
+++ b/src/lib/components/SpeakerList.svelte
@@ -1,23 +1,26 @@
+<!--
+  @component This component displays a list of speakers during a caucus,
+  as well as providing a default method ot adding new speakers.
+
+  This component handles the ability to select, delete, 
+  and rearrange speakers in the speakers' list.
+ -->
 <script lang="ts">
     import DelLabel from "$lib/components/del-label/DelLabel.svelte";
     import DelAutocomplete, { autocompletePlaceholders } from "$lib/components/DelAutocomplete.svelte";
     import { type Delegate, findDelegate } from "$lib/db/delegates";
-    import { formatValidationError } from "$lib/motions/form_validation";
+    import { formatValidationError, presentDelegateSchema } from "$lib/motions/form_validation";
     import type { DelegateID, Speaker, SpeakerEntryID } from "$lib/types";
     import { getDndItemId, isDndShadow, processDrag } from "$lib/util/dnd";
     import { triggerConfirmModal } from "$lib/util";
     
-    import { z } from "zod";
     import Icon from "@iconify/svelte";
     import { getModalStore, popup } from "@skeletonlabs/skeleton";
-    import { tick, untrack } from "svelte";
+    import { tick, untrack, type Snippet } from "svelte";
     import { flip } from "svelte/animate";
     import { dragHandle, dragHandleZone } from "svelte-dnd-action";
     import { autocompletePopup, POPUP_CARD_CLASSES } from "$lib/util/popup";
 
-    let dfltControlsInput: string = $state("");
-    let dfltControlsError: string | undefined = $state(undefined);
-
     const modalStore = getModalStore();
 
     interface Props {
@@ -30,25 +33,27 @@
          */
         delegates?: Delegate[];
         /**
-         * If defined, this creates control options to allow for adding
-         * and removing speakers from the speakers' list.
+         * The controls at the bottom of the speaker list
+         * which handle the addition of new speakers.
          * 
-         * This doesn't need to be defined if:
-         * 1. Adding delegates isn't required, or
-         * 2. A custom control is implemented instead
+         * If this prop is defined, this overrides the default add delegate controls
+         * provided by this component.
+         */
+        controls?: Snippet;
+        /**
+         * If this prop is defined, the function callback is activated right before a speaker changes.
+         */
+        onBeforeSpeakerUpdate?: ((oldSpeaker: Speaker | undefined, newSpeaker: Speaker | undefined) => unknown);
+        /**
+         * If this prop is defined, the function callback is activated when a speaker is marked as completed.
          */
-        useDefaultControls?: {
-            validator: z.ZodType<DelegateID, any, any> | ((dels: Delegate[]) => z.ZodType<DelegateID, any, any>),
-            popupID?: string
-        } | undefined;
-        onBeforeSpeakerUpdate?: ((oldSpeaker: Speaker | undefined, newSpeaker: Speaker | undefined) => unknown) | undefined;
-        onMarkComplete?: ((key: DelegateID, isRepeat: boolean) => unknown) | undefined;
+        onMarkComplete?: ((key: DelegateID, isRepeat: boolean) => unknown);
     }
 
     let {
         order = $bindable([]),
         delegates = [],
-        useDefaultControls = undefined,
+        controls = undefined,
         onBeforeSpeakerUpdate = undefined,
         onMarkComplete = undefined
     }: Props = $props();
@@ -57,7 +62,21 @@
     let dndItems = $state($state.snapshot(order));
     $effect(() => { dndItems = order; });
 
-    // Special IDs to track:
+    // Input properties (the current input, any errors with input, and the input validator)
+    // Input validator currently doesn't have support to be changed, but if needed,
+    // just add a new prop for it.
+    //
+    // The `addDelInput` and `addDelError` properties only apply if `controls` is not defined.
+    let addDelInput: string = $state("");
+    let addDelError: string = $state("");
+    let addDelValidator = $derived(presentDelegateSchema(delegates));
+
+    /**
+     * ID for target. (Cannot be changed, but if needed just add a prop for it.)
+     */
+    const POPUP_TARGET = "add-delegate-popup";
+
+    // The UUID of the currently selected speaker object:
     let selectedSpeakerId = $state<SpeakerEntryID>();
     // A mapping from IDs to Speakers:
     let orderMap = $derived(Object.fromEntries(
@@ -67,8 +86,13 @@
 
     // List item elements per order item
     let liElements = new Map<SpeakerEntryID, HTMLLIElement>();
+    function jumpToSpeaker(speakerId: string) {
+        liElements.get(speakerId)?.scrollIntoView({ block: "nearest" });
+    }
 
-    // Readonly values
+    /**
+     * Whether the speaker's list is complete (there are no other speakers left in the list).
+     */
     export function isAllDone() {
         return typeof selectedSpeakerId === "undefined" && order.every(({ completed }) => completed);
     }
@@ -87,11 +111,18 @@
         });
         
     }
-    //
+    /**
+     * Find the speaker object with this UUID.
+     * @param speakerId the ID (or undefined)
+     */
     function findSpeaker(speakerId: SpeakerEntryID | undefined): Speaker | undefined {
         if (typeof speakerId === "undefined") return;
         return orderMap[speakerId]?.speaker;
     }
+    /**
+     * Marks the speaker as completed (and activates any listeners bound to "onMarkComplete").
+     * @param speakerId the ID (or undefined)
+     */
     function markComplete(speakerId: SpeakerEntryID | undefined) {
         let speaker = findSpeaker(speakerId);
         if (typeof speaker !== "undefined") {
@@ -100,9 +131,16 @@
         }
         order = order;
     }
+
+    /**
+     * Starts the speaker's list.
+     */
     export function start() {
         markComplete(selectedSpeakerId);
     }
+    /**
+     * Moves to the next speaker in the speaker's list.
+     */
     export function next() {
         markComplete(selectedSpeakerId);
 
@@ -110,8 +148,13 @@
         setSelectedSpeaker(order.find(({ completed }) => !completed));
     }
 
+    /**
+     * Adds a speaker to the speaker's list.
+     * @param name The full name of the speaker (not a key; this is parsed by the default validator)
+     * @param clearControlInput Whether this function call should clear the input (by default false)
+     */
     export function addSpeaker(name: string, clearControlInput: boolean = false) {
-        const result = validator.safeParse(name);
+        const result = addDelValidator.safeParse(name);
         if (result.success) {
             const key = result.data;
             // Successful, so add speakers:
@@ -120,23 +163,31 @@
             order = order;
 
             // Jump to this speaker when DOM updates.
-            tick().then(() => {
-                gotoSpeaker(speaker.id);
-            });
+            tick().then(() => jumpToSpeaker(speaker.id));
 
-            if (typeof useDefaultControls !== "undefined") {
-                dfltControlsError = undefined;
+            // Only applies to default controls
+            if (typeof controls === "undefined") {
+                addDelError = "";
                 // Clear the control input if it exists and it was requested to be cleared.
-                if (clearControlInput) dfltControlsInput = "";
+                if (clearControlInput) addDelInput = "";
             }
         } else {
-            dfltControlsError = formatValidationError(result.error).message;
+            addDelError = formatValidationError(result.error).message;
         }
     }
+
+    // DEFAULT CONTROLS
+    /**
+     * Wrapper around `addSpeaker`.
+     */
     function submitSpeaker(e: SubmitEvent) {
         e.preventDefault();
-        addSpeaker(dfltControlsInput, true);
+        addSpeaker(addDelInput, true);
     }
+    /**
+     * Deletes the speaker at index i in the speaker's list.
+     * @param i The index.
+     */
     function deleteSpeaker(i: number) {
         let [removedSpeaker] = order.splice(i, 1);
         order = order;
@@ -145,6 +196,9 @@
             setSelectedSpeaker(undefined);
         }
     }
+    /**
+     * Remove all speakers from the speaker's list.
+     */
     function clearSpeakers() {
         triggerConfirmModal(
             modalStore, "Are you sure you want to clear the Speakers List?",
@@ -152,6 +206,15 @@
         );
     }
     /// Sets the selected speaker.
+
+    /**
+     * Sets the selected speaker and activates the "onBeforeSpeakerUpdate" listener.
+     * 
+     * In order to properly trigger `onBeforeSpeakerUpdate`, this method should be used,
+     * and not `selectedSpeakerId = newId`.
+     * 
+     * @param speaker the speaker object (or undefined to clear speaker)
+     */
     function setSelectedSpeaker(speaker: Speaker | undefined) {
         if (selectedSpeakerId !== speaker?.id) {
             // Call beforeSpeakerUpdate (and let it run to completion if is Promise) before setting speaker.
@@ -164,9 +227,6 @@
         }
     }
 
-    function gotoSpeaker(speakerId: string) {
-        liElements.get(speakerId)?.scrollIntoView({ block: "nearest" });
-    }
     // If order updates and selectedSpeaker isn't in there, then clear selectedSpeaker.
     // Scroll to speaker if it is out of view.
     $effect(() => {
@@ -174,7 +234,7 @@
             if (!(selectedSpeakerId in orderMap)) {
                 setSelectedSpeaker(undefined);
             } else {
-                gotoSpeaker(selectedSpeakerId);
+                jumpToSpeaker(selectedSpeakerId);
             }
         }
     })
@@ -183,16 +243,6 @@
         map.set(key, el);
         return { destroy() { map.delete(key); } }
     };
-    let noDelegatesPresent = $derived(delegates.every(d => !d.isPresent()));
-
-    // Properties which are only used with default controls:
-    let validator = $derived.by(() => {
-        if (typeof useDefaultControls?.validator === "function") {
-            return useDefaultControls.validator(delegates);
-        } else {
-            return useDefaultControls?.validator ?? z.never();
-        }
-    });
 </script>
 <script module lang="ts">
     /**
@@ -274,20 +324,22 @@
         {/each}
     </ol>
 
-    <!-- Default controls, consisting of a delegate input, an add button, and a clear button. -->
-    {#if typeof useDefaultControls !== "undefined"}
-        {@const popupID = useDefaultControls.popupID ?? "addDelegatePopup"}
-        {@const error = typeof dfltControlsError !== "undefined"}
+    {#if controls}
+        {@render controls()}
+    {:else}
+        <!-- Default controls, consisting of a delegate input, an add button, and a clear button. -->
+        {@const error = !!addDelError}
+        {@const noDelegatesPresent = delegates.every(d => !d.isPresent())}
 
         <div class="flex flex-col gap-1">
             <div class="flex flex-row gap-1">
                 <!-- Add delegate -->
-                <form class="contents" onsubmit={submitSpeaker} oninput={() => dfltControlsError = undefined}>
+                <form class="contents" onsubmit={submitSpeaker} oninput={() => addDelError = ""}>
                     <input 
                         class="input" 
                         class:input-error={error}
-                        bind:value={dfltControlsInput}
-                        use:popup={{ ...autocompletePopup(popupID), placement: "left-end" }}
+                        bind:value={addDelInput}
+                        use:popup={{ ...autocompletePopup(POPUP_TARGET), placement: "left-end" }}
                         {...autocompletePlaceholders(noDelegatesPresent)}
                     />
                     <div class="ml-2">
@@ -318,7 +370,7 @@
             </div>
             <!-- Error messages! -->
             <div class="text-error-500 text-center transition-[height] overflow-hidden {error ? 'h-6' : 'h-0'}">
-                {dfltControlsError ?? "\xA0"}
+                {addDelError || "\xA0"}
             </div>
         </div>
 
@@ -328,9 +380,9 @@
 
             The solution used here is to not put another element over the popup :)
         -->
-        <div class="{POPUP_CARD_CLASSES}" data-popup={popupID}>
+        <div class="{POPUP_CARD_CLASSES}" data-popup={POPUP_TARGET}>
             <DelAutocomplete
-                bind:input={dfltControlsInput}
+                bind:input={addDelInput}
                 {delegates}
                 on:selection={e => addSpeaker(e.detail.label, true)}
             />
diff --git a/src/lib/components/motions/page/ModCaucus.svelte b/src/lib/components/motions/page/ModCaucus.svelte
index afdd17f..560d946 100644
--- a/src/lib/components/motions/page/ModCaucus.svelte
+++ b/src/lib/components/motions/page/ModCaucus.svelte
@@ -3,7 +3,6 @@
     import TimerPanel, { resetButton } from "$lib/components/motions/TimerPanel.svelte";
     import { getSessionContext } from "$lib/context/index.svelte";
     import { db } from "$lib/db/index.svelte";
-    import { presentDelegateSchema } from "$lib/motions/form_validation";
     import type { Motion, Speaker } from "$lib/types";
 
     interface Props {
@@ -55,9 +54,6 @@
             bind:order
             delegates={$delegates}
             bind:this={speakersList}
-            useDefaultControls={{
-                validator: presentDelegateSchema
-            }}
             onBeforeSpeakerUpdate={resetOne}
             onMarkComplete={(key, isRepeat) => { if (!isRepeat) db.updateDelegate(key, d => { d.stats.timesSpoken++; }) }}
         />
diff --git a/src/lib/components/motions/page/RoundRobin.svelte b/src/lib/components/motions/page/RoundRobin.svelte
index 2818ab1..2ad81e1 100644
--- a/src/lib/components/motions/page/RoundRobin.svelte
+++ b/src/lib/components/motions/page/RoundRobin.svelte
@@ -57,6 +57,8 @@
             bind:this={speakersList}
             onBeforeSpeakerUpdate={reset}
             onMarkComplete={(key, isRepeat) => { if (!isRepeat) db.updateDelegate(key, d => { d.stats.timesSpoken++; }) }}
-        />
+        >
+            {#snippet controls()}{/snippet}
+        </SpeakerList>
     </div>
 </div>
\ No newline at end of file
diff --git a/src/routes/dashboard/speaker-list/+page.svelte b/src/routes/dashboard/speaker-list/+page.svelte
index 00425f7..782f44e 100644
--- a/src/routes/dashboard/speaker-list/+page.svelte
+++ b/src/routes/dashboard/speaker-list/+page.svelte
@@ -3,7 +3,6 @@
     import TimerPanel from "$lib/components/motions/TimerPanel.svelte";
     import { getSessionContext } from "$lib/context/index.svelte";
     import { db } from "$lib/db/index.svelte";
-    import { presentDelegateSchema } from "$lib/motions/form_validation";
     import { parseTime } from "$lib/util/time";
 
     const { speakersList: order, delegates } = getSessionContext();
@@ -53,9 +52,6 @@
             delegates={$delegates}
             bind:order={$order}
             bind:this={speakersList}
-            useDefaultControls={{
-                validator: presentDelegateSchema
-            }}
             onBeforeSpeakerUpdate={reset}
             onMarkComplete={(key, isRepeat) => { if (!isRepeat) db.updateDelegate(key, d => { d.stats.timesSpoken++; }) }}
         />

From 4356b2034e3ce493f29e434ffde4764a2fa97555 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Wed, 15 Jan 2025 23:19:58 -0500
Subject: [PATCH 10/21] DelFlag and DelLabel doc

---
 src/lib/components/del-label/DelFlag.svelte  | 45 +++++++++++++++-----
 src/lib/components/del-label/DelLabel.svelte | 27 +++++++++++-
 2 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/src/lib/components/del-label/DelFlag.svelte b/src/lib/components/del-label/DelFlag.svelte
index bd783c3..ccd435c 100644
--- a/src/lib/components/del-label/DelFlag.svelte
+++ b/src/lib/components/del-label/DelFlag.svelte
@@ -1,43 +1,68 @@
+<!-- 
+  @component A wrapper around flag images.
+
+  This handles accessibility and differences between inline/non-inline flags.
+  This is used with `DelLabel` to handle the display of delegates.
+-->
 <script lang="ts">
     import { getFlagUrl } from "$lib/flags/flagcdn";
     import Icon from "@iconify/svelte";
 
     interface Props {
+        /**
+         * Country's name. This is necessary for accessibilities purposes.
+         */
         label: string,
+        /**
+         * The link to the flag's URL. 
+         * 
+         * This is *preferably* an SVG, but can also be PNG.
+         * Currently, this should be a link to an image from `flagcdn.com`.
+         */
         url: string | undefined,
+        /**
+         * The height of the flag, which should be defined with Tailwind CSS classes.
+         */
         height?: string;
+        /**
+         * The fallback if the URL provided doesn't exist.
+         * - `un`: Fallback to the United Nations flag
+         * - `icon`: Fallback to a broken flag icon (this should only be used for inline, small flags)
+         * - `none`: Fallback to nothing. A blank space.
+         */
         fallback?: "un" | "icon" | "none";
+        /**
+         * Whether this flag is inline with the text or not.
+         * 
+         * If enabled and using a FlagCDN flag, this will overwrite the flag with a special inline version.
+         */
         inline?: boolean
     }
 
     let {
         label,
-        url,
+        url: flagURL,
         height = "",
         fallback = "none",
         inline = false
     }: Props = $props();
 
-    // Only set flag on client-side, to prevent hydration mismatch issues.
-    // https://svelte.dev/docs/svelte/v5-migration-guide#Other-breaking-changes-img-src-and-html-hydration-mismatches-are-not-repaired
-    let flag: URL | undefined = $derived(url ? new URL(url) : undefined);
-
     /**
      * Hack to implement fixed flags for FlagCDN flags.
      */
-    function _legacyFixedFlagSrc(url: URL) {
+    function _legacyFixedFlagSrc(url: string) {
         let match;
-        if (inline && (match = url.href.match(/^https:\/\/flagcdn.com\/(\w+).svg$/))) {
+        if (inline && (match = url.match(/^https:\/\/flagcdn.com\/(\w+).svg\/?$/))) {
             return `https://flagcdn.com/80x60/${match[1]}.png`;
         } else {
-            return url.href;
+            return url;
         }
     }
 </script>
 
-{#if flag}
+{#if flagURL}
     <!-- Temporary HACK to support fixed-size flags from FlagCDN -->
-    {@const src = _legacyFixedFlagSrc(flag)}
+    {@const src = _legacyFixedFlagSrc(flagURL)}
     <img
         {src}
         alt="Flag of {label}"
diff --git a/src/lib/components/del-label/DelLabel.svelte b/src/lib/components/del-label/DelLabel.svelte
index c84fb16..4ed1809 100644
--- a/src/lib/components/del-label/DelLabel.svelte
+++ b/src/lib/components/del-label/DelLabel.svelte
@@ -1,18 +1,41 @@
+<!-- 
+  @component A wrapper that displays a delegate's name and their flag.
+
+  This handles accessibility and differences between inline/non-inline labels.
+-->
+
 <script lang="ts">
     import DelFlag from "$lib/components/del-label/DelFlag.svelte";
     import type { DelegateAttrs } from "$lib/types";
 
     interface Props {
+        /**
+         * The attributes of the delegate
+         * (this can be undefined to indicate no delegate).
+         */
         attrs: DelegateAttrs | undefined;
-        height?: string | undefined;
+        /**
+         * Height of the flag, defined with Tailwind CSS classes.
+         */
+        flagHeight?: string | undefined;
+        /**
+         * Whether this label is inline text or not.
+         * This decides whether it is a large block or text with a flag.
+         */
         inline?: boolean;
+        /**
+         * The `fallback` property of `DelFlag`.
+         */
         fallbackFlag?: "un" | "icon" | "none" | undefined;
+        /**
+         * The name to use if the delegate's name could not be found.
+         */
         fallbackName?: string | undefined;
     }
 
     let {
         attrs,
-        height = undefined,
+        flagHeight: height = undefined,
         inline = false,
         fallbackFlag = undefined,
         fallbackName = undefined

From f5591cf797c4dfa9a71f14e90ece377bbbf7ac66 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Wed, 15 Jan 2025 23:28:40 -0500
Subject: [PATCH 11/21] LabeledSlideToggle

---
 src/lib/components/LabeledSlideToggle.svelte | 25 +++++++++++++++++++-
 src/lib/components/MotionForm.svelte         | 14 +++++------
 2 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/src/lib/components/LabeledSlideToggle.svelte b/src/lib/components/LabeledSlideToggle.svelte
index 72624b4..d159833 100644
--- a/src/lib/components/LabeledSlideToggle.svelte
+++ b/src/lib/components/LabeledSlideToggle.svelte
@@ -1,12 +1,35 @@
+<!--
+  @component A wrapper around Skeleton's `SlideToggle` module 
+  that adds a label that actually looks decent.
+
+  `SlideToggle` on its own can be used, but this one looks nicer.
+-->
 <script lang="ts">
     import { SlideToggle } from "@skeletonlabs/skeleton";
     import { type Snippet } from "svelte";
 
     interface Props {
+        /**
+         * HTML for the label.
+         */
         children: Snippet,
+        /**
+         * The name (as required by Skeleton's `SlideToggle`
+         * and used for accessibility purposes)
+         */
         name: string,
+        /**
+         * Whether the slide toggle is checked.
+         * This is a bindable property.
+         */
         checked?: boolean,
+        /**
+         * Whether this slide toggle is disabled.
+         */
         disabled?: boolean,
+        /**
+         * The Tailwind CSS classes applied on the label.
+         */
         labelClass?: string,
         [key: string]: any
     }
@@ -15,7 +38,7 @@
         name,
         checked = $bindable(undefined),
         disabled = undefined,
-        labelClass = "flex items-center justify-between gap-3",
+        labelClass = "flex items-center justify-between gap-3 label",
         ...rest
     }: Props = $props();
 </script>
diff --git a/src/lib/components/MotionForm.svelte b/src/lib/components/MotionForm.svelte
index 0ae070f..16b605c 100644
--- a/src/lib/components/MotionForm.svelte
+++ b/src/lib/components/MotionForm.svelte
@@ -178,13 +178,13 @@
     {/if}
     {#if hasField(inputMotion, ["topic"])}
     <label class="label">
-    <span>Topic</span>
-    <input 
-        class="input" 
-        class:input-error={inputError?.path.includes("topic")}
-        bind:value={inputMotion.topic}
-        disabled={isExtending(inputMotion)}
-    >
+        <span>Topic</span>
+        <input 
+            class="input" 
+            class:input-error={inputError?.path.includes("topic")}
+            bind:value={inputMotion.topic}
+            disabled={isExtending(inputMotion)}
+        >
     </label>
     {/if}
     {#if hasField(inputMotion, ["isExtension"]) && $selectedMotion?.kind === inputMotion.kind}

From fb2182a382f0ef80a4d4b2b7218b438d67bc2056 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Wed, 15 Jan 2025 23:45:33 -0500
Subject: [PATCH 12/21] MotionForm doc

---
 src/lib/components/MotionForm.svelte | 54 +++++++++++++++++++++-------
 1 file changed, 42 insertions(+), 12 deletions(-)

diff --git a/src/lib/components/MotionForm.svelte b/src/lib/components/MotionForm.svelte
index 16b605c..8e5d470 100644
--- a/src/lib/components/MotionForm.svelte
+++ b/src/lib/components/MotionForm.svelte
@@ -1,3 +1,7 @@
+<!--
+  @component A component that wraps around the form used 
+    to create or edit a motion.
+-->
 <script lang="ts">
     import LabeledSlideToggle from "$lib/components/LabeledSlideToggle.svelte";
     import DelAutocomplete, { autocompletePlaceholders } from "$lib/components/DelAutocomplete.svelte";
@@ -19,28 +23,40 @@
     const resetInputErrors = () => { inputError = undefined };
 
     interface Props {
+        /**
+         * The input data.
+         */
         inputMotion?: MotionInput;
+        /**
+         * A callback where the motion is submitted 
+         * if it is successfully validated and produced.
+         */
         submit: (m: Motion) => void;
+        /**
+         * Buttons on the bottom of the snippet.
+         * If not specified, this will just be an "Add Motion" button.
+         */
         buttons?: Snippet;
     }
-
-    // Input handlers:
     let {
         inputMotion = $bindable(defaultInputMotion()),
         submit,
         buttons
     }: Props = $props();
-    let inputError: z.ZodIssue | undefined = $state(undefined);
-
-    // The input after the delegate input.
-    let afterDel: HTMLElement | undefined = $state();
+    
+    // Any input validation errors.
+    let inputError = $state<z.ZodIssue>();
+    // The form element.
+    let formEl = $state<HTMLFormElement>();
 
     let noDelegatesPresent = $derived($delegates.every(d => !d.isPresent()));
     const POPUP_TARGET = "delegate-input-popup";
     
+    // Motion validation and submission.
     function submitMotion(e: SubmitEvent) {
         e.preventDefault();
 
+        // Round-Robin: Apply total speakers
         if (inputMotion.kind === "rr") {
             inputMotion.totalSpeakers = $delegates.filter(d => d.isPresent()).length.toString();
         }
@@ -52,7 +68,7 @@
             }
         }
 
-        // Validate
+        // Validate input
         const result = motionSchema.safeParse(inputMotion);
         if (result.success) {
             inputMotion = defaultInputMotion();
@@ -64,7 +80,9 @@
         }
     }
 
-    // INPUT BLUR HANDLER
+    /**
+     * When user unfocuses on a time input, update the input to include colons.
+     */
     function handleBlurTime<A extends string>(attr: A) {
         if (attr in inputMotion) {
             (inputMotion as any)[attr] = addColons((inputMotion as any)[attr] ?? "");
@@ -124,8 +142,8 @@
     }
 </script>
 
-<form onsubmit={submitMotion} oninput={resetInputErrors} class="flex flex-col gap-3 p-3">
-    <!-- Motion input form -->
+<form onsubmit={submitMotion} oninput={resetInputErrors} class="flex flex-col gap-3 p-3" bind:this={formEl}>
+    <!-- Delegate input -->
     <label class="label">
         <span>Delegate</span>
         <input 
@@ -137,12 +155,13 @@
             {...autocompletePlaceholders(noDelegatesPresent)}
         >
     </label>
+
+    <!-- Motion dropdown -->
     <label class="label">
         <span>Motion</span>
         <select 
             class="select" 
             class:input-error={inputError?.path.includes("kind")}
-            bind:this={afterDel}
             bind:value={inputMotion.kind}
             >
             {#each Object.entries(MOTION_LABELS) as [value, label]}
@@ -150,6 +169,8 @@
             {/each}
         </select>
     </label>
+
+    <!-- Total time input -->
     {#if hasField(inputMotion, ["totalTime"])}
     <label class="label">
         <span>Total Time</span>
@@ -163,6 +184,8 @@
         >
     </label>
     {/if}
+
+    <!-- Speaking time input -->
     {#if hasField(inputMotion, ["speakingTime"])}
     <label class="label">
         <span>Speaking Time</span>
@@ -176,6 +199,8 @@
         >
     </label>
     {/if}
+
+    <!-- Topic input -->
     {#if hasField(inputMotion, ["topic"])}
     <label class="label">
         <span>Topic</span>
@@ -187,17 +212,22 @@
         >
     </label>
     {/if}
+
+    <!-- Extension toggle -->
     {#if hasField(inputMotion, ["isExtension"]) && $selectedMotion?.kind === inputMotion.kind}
     <LabeledSlideToggle name="extension-toggle" bind:checked={inputMotion.isExtension}>
     <span>Extend previous motion?</span>
     </LabeledSlideToggle>
     {/if}
+
+    <!-- Number of speakers display -->
     {#if hasField(inputMotion, ["totalTime", "speakingTime"])}
     <div class="text-center">
         <strong>Number of speakers</strong>: {numSpeakersStr(inputMotion.totalTime, inputMotion.speakingTime) ?? '-'}
     </div>
     {/if}
 
+    <!-- End buttons -->
     {#if buttons}
         {@render buttons()}
     {:else}
@@ -221,7 +251,7 @@
             on:selection={e => {
                 inputMotion.delegate = e.detail.label;
                 resetInputErrors();
-                afterDel?.focus();
+                (formEl?.children[1] as HTMLElement)?.focus?.();
             }}
         />
     </div>

From 44ea749cd37ad6ac3a02659daf919a4ce2fd5870 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Fri, 17 Jan 2025 16:59:26 -0500
Subject: [PATCH 13/21] motion pages doc

---
 src/lib/components/motions/page/ModCaucus.svelte   | 6 ++++++
 src/lib/components/motions/page/README.md          | 6 +++++-
 src/lib/components/motions/page/RoundRobin.svelte  | 6 ++++++
 src/lib/components/motions/page/UnmodCaucus.svelte | 4 ++++
 src/routes/dashboard/current-motion/+page.svelte   | 9 ++++++---
 src/routes/dashboard/speaker-list/+page.svelte     | 5 +++++
 6 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/src/lib/components/motions/page/ModCaucus.svelte b/src/lib/components/motions/page/ModCaucus.svelte
index 560d946..347467e 100644
--- a/src/lib/components/motions/page/ModCaucus.svelte
+++ b/src/lib/components/motions/page/ModCaucus.svelte
@@ -1,3 +1,9 @@
+<!--
+    @component The motion page for moderated caucuses, consisting of:
+    - A header topic
+    - A timer panel with two timers (delegate and total time)
+    - An editable speaker's list
+-->
 <script lang="ts">
     import SpeakerList from "$lib/components/SpeakerList.svelte";
     import TimerPanel, { resetButton } from "$lib/components/motions/TimerPanel.svelte";
diff --git a/src/lib/components/motions/page/README.md b/src/lib/components/motions/page/README.md
index 725ea41..bfd0fa0 100644
--- a/src/lib/components/motions/page/README.md
+++ b/src/lib/components/motions/page/README.md
@@ -9,5 +9,9 @@ To be used in that route, a component in this folder should be added to the `if/
 This `motion` prop should be declared as so:
 
 ```ts
-export let motion: Motion & { kind: "accepted kind" | "other accepted kind" | ... };
+interface Props {
+    motion: Motion & { kind: "accepted motion type" | "another accepted motion type" | ... },
+    anyOtherProperties: ...
+}
+let { motion, ... } = $props();
 ```
diff --git a/src/lib/components/motions/page/RoundRobin.svelte b/src/lib/components/motions/page/RoundRobin.svelte
index 2ad81e1..9928685 100644
--- a/src/lib/components/motions/page/RoundRobin.svelte
+++ b/src/lib/components/motions/page/RoundRobin.svelte
@@ -1,3 +1,9 @@
+<!--
+    @component The motion page for round robins, consisting of:
+    - A header topic
+    - A timer panel with a timer (delegate speaking time)
+    - A speaker's list that is automatically populated with all delegates
+-->
 <script lang="ts">
     import SpeakerList, { createSpeaker } from "$lib/components/SpeakerList.svelte";
     import TimerPanel from "$lib/components/motions/TimerPanel.svelte";
diff --git a/src/lib/components/motions/page/UnmodCaucus.svelte b/src/lib/components/motions/page/UnmodCaucus.svelte
index 186a937..4167857 100644
--- a/src/lib/components/motions/page/UnmodCaucus.svelte
+++ b/src/lib/components/motions/page/UnmodCaucus.svelte
@@ -1,3 +1,7 @@
+<!--
+    @component The motion page for unmoderated caucuses, consisting of:
+    - A timer
+-->
 <script lang="ts">
     import Timer from "$lib/components/Timer.svelte";
     import type { Motion } from "$lib/types";
diff --git a/src/routes/dashboard/current-motion/+page.svelte b/src/routes/dashboard/current-motion/+page.svelte
index d95af01..9b094d1 100644
--- a/src/routes/dashboard/current-motion/+page.svelte
+++ b/src/routes/dashboard/current-motion/+page.svelte
@@ -1,3 +1,8 @@
+<!--
+  @component The page for the current motion (after it was selected in the Points & Motions page).
+
+  This page delegates to one of the motion components located in `$lib/components/motions/page`.
+-->
 <script lang="ts">
     import { base } from "$app/paths";
     import ModCaucus from "$lib/components/motions/page/ModCaucus.svelte";
@@ -6,8 +11,6 @@
     import { getSessionContext } from "$lib/context/index.svelte";
 
     const { selectedMotion, selectedMotionState } = getSessionContext();
-
-    const isExhaustive = (s: never) => s;
 </script>
 
 <div class="h-full w-full flex flex-col items-stretch justify-center">
@@ -20,7 +23,7 @@
             <RoundRobin motion={$selectedMotion} bind:order={$selectedMotionState.speakersList} />
         {:else if $selectedMotion.kind === "other"}
             <!-- TODO -->
-        {:else if isExhaustive($selectedMotion)}
+        {:else if $selectedMotion satisfies never}
             <!-- unreachable -->
         {/if}
     {:else}
diff --git a/src/routes/dashboard/speaker-list/+page.svelte b/src/routes/dashboard/speaker-list/+page.svelte
index 782f44e..57ab48d 100644
--- a/src/routes/dashboard/speaker-list/+page.svelte
+++ b/src/routes/dashboard/speaker-list/+page.svelte
@@ -1,3 +1,8 @@
+<!--
+    @component The page for standard speakers list, consisting of:
+    - A timer panel with a timer (delegate speaking time)
+    - An editable speaker's list
+-->
 <script lang="ts">
     import SpeakerList from "$lib/components/SpeakerList.svelte";
     import TimerPanel from "$lib/components/motions/TimerPanel.svelte";

From 8814663bfe2939d52cbd095b2191861a65194a2b Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Fri, 17 Jan 2025 16:59:57 -0500
Subject: [PATCH 14/21] it's `speakers list`

---
 src/lib/components/SpeakerList.svelte            | 16 ++++++++--------
 src/lib/components/motions/TimerPanel.svelte     |  2 +-
 src/lib/components/motions/page/ModCaucus.svelte |  2 +-
 .../components/motions/page/RoundRobin.svelte    |  2 +-
 src/routes/dashboard/speaker-list/+page.svelte   |  2 +-
 5 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/src/lib/components/SpeakerList.svelte b/src/lib/components/SpeakerList.svelte
index 75e5df9..5b7d2e6 100644
--- a/src/lib/components/SpeakerList.svelte
+++ b/src/lib/components/SpeakerList.svelte
@@ -3,7 +3,7 @@
   as well as providing a default method ot adding new speakers.
 
   This component handles the ability to select, delete, 
-  and rearrange speakers in the speakers' list.
+  and rearrange speakers in the speakers list.
  -->
 <script lang="ts">
     import DelLabel from "$lib/components/del-label/DelLabel.svelte";
@@ -25,7 +25,7 @@
 
     interface Props {
         /**
-         * The order of speakers for the speaker's list.
+         * The order of speakers for the speakers list.
          */
         order?: Speaker[];
         /**
@@ -91,7 +91,7 @@
     }
 
     /**
-     * Whether the speaker's list is complete (there are no other speakers left in the list).
+     * Whether the speakers list is complete (there are no other speakers left in the list).
      */
     export function isAllDone() {
         return typeof selectedSpeakerId === "undefined" && order.every(({ completed }) => completed);
@@ -133,13 +133,13 @@
     }
 
     /**
-     * Starts the speaker's list.
+     * Starts the speakers list.
      */
     export function start() {
         markComplete(selectedSpeakerId);
     }
     /**
-     * Moves to the next speaker in the speaker's list.
+     * Moves to the next speaker in the speakers list.
      */
     export function next() {
         markComplete(selectedSpeakerId);
@@ -149,7 +149,7 @@
     }
 
     /**
-     * Adds a speaker to the speaker's list.
+     * Adds a speaker to the speakers list.
      * @param name The full name of the speaker (not a key; this is parsed by the default validator)
      * @param clearControlInput Whether this function call should clear the input (by default false)
      */
@@ -185,7 +185,7 @@
         addSpeaker(addDelInput, true);
     }
     /**
-     * Deletes the speaker at index i in the speaker's list.
+     * Deletes the speaker at index i in the speakers list.
      * @param i The index.
      */
     function deleteSpeaker(i: number) {
@@ -197,7 +197,7 @@
         }
     }
     /**
-     * Remove all speakers from the speaker's list.
+     * Remove all speakers from the speakers list.
      */
     function clearSpeakers() {
         triggerConfirmModal(
diff --git a/src/lib/components/motions/TimerPanel.svelte b/src/lib/components/motions/TimerPanel.svelte
index 46827bf..4b554f3 100644
--- a/src/lib/components/motions/TimerPanel.svelte
+++ b/src/lib/components/motions/TimerPanel.svelte
@@ -93,7 +93,7 @@
     }
     
     /**
-     * Currently selected speaker from speaker's list.
+     * Currently selected speaker from speakers list.
      */
     let selectedSpeaker = $derived(speakersList?.selectedSpeaker());
     /**
diff --git a/src/lib/components/motions/page/ModCaucus.svelte b/src/lib/components/motions/page/ModCaucus.svelte
index 347467e..616aa39 100644
--- a/src/lib/components/motions/page/ModCaucus.svelte
+++ b/src/lib/components/motions/page/ModCaucus.svelte
@@ -2,7 +2,7 @@
     @component The motion page for moderated caucuses, consisting of:
     - A header topic
     - A timer panel with two timers (delegate and total time)
-    - An editable speaker's list
+    - An editable speakers list
 -->
 <script lang="ts">
     import SpeakerList from "$lib/components/SpeakerList.svelte";
diff --git a/src/lib/components/motions/page/RoundRobin.svelte b/src/lib/components/motions/page/RoundRobin.svelte
index 9928685..b4f37ee 100644
--- a/src/lib/components/motions/page/RoundRobin.svelte
+++ b/src/lib/components/motions/page/RoundRobin.svelte
@@ -2,7 +2,7 @@
     @component The motion page for round robins, consisting of:
     - A header topic
     - A timer panel with a timer (delegate speaking time)
-    - A speaker's list that is automatically populated with all delegates
+    - A speakers list that is automatically populated with all delegates
 -->
 <script lang="ts">
     import SpeakerList, { createSpeaker } from "$lib/components/SpeakerList.svelte";
diff --git a/src/routes/dashboard/speaker-list/+page.svelte b/src/routes/dashboard/speaker-list/+page.svelte
index 57ab48d..03d2df0 100644
--- a/src/routes/dashboard/speaker-list/+page.svelte
+++ b/src/routes/dashboard/speaker-list/+page.svelte
@@ -1,7 +1,7 @@
 <!--
     @component The page for standard speakers list, consisting of:
     - A timer panel with a timer (delegate speaking time)
-    - An editable speaker's list
+    - An editable speakers list
 -->
 <script lang="ts">
     import SpeakerList from "$lib/components/SpeakerList.svelte";

From 31168184cd6e16cf1442c37171b0b102636221bf Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Fri, 17 Jan 2025 17:05:42 -0500
Subject: [PATCH 15/21] various server pages

---
 src/routes/+layout.ts                | 2 ++
 src/routes/admin/+page.server.ts     | 7 +++++++
 src/routes/admin/+page.svelte        | 2 +-
 src/routes/dashboard/+page.server.ts | 6 ++++++
 src/routes/dashboard/+page.svelte    | 2 +-
 5 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/routes/+layout.ts b/src/routes/+layout.ts
index c8cacf0..fbe450c 100644
--- a/src/routes/+layout.ts
+++ b/src/routes/+layout.ts
@@ -1 +1,3 @@
+// Force use server-side rendering for static site.
+
 export const prerender = true;
\ No newline at end of file
diff --git a/src/routes/admin/+page.server.ts b/src/routes/admin/+page.server.ts
index 2e2c7a0..20e873f 100644
--- a/src/routes/admin/+page.server.ts
+++ b/src/routes/admin/+page.server.ts
@@ -1,3 +1,10 @@
+/**
+ * 307: Temporary redirect /admin/ to /admin/settings.
+ * 
+ * There is probably a universe where we make a new /admin/ page
+ * and won't redirect to /admin/settings/.
+ */
+
 import { base } from "$app/paths";
 import { redirect } from "@sveltejs/kit";
 
diff --git a/src/routes/admin/+page.svelte b/src/routes/admin/+page.svelte
index 3ce90e4..46d4db5 100644
--- a/src/routes/admin/+page.svelte
+++ b/src/routes/admin/+page.svelte
@@ -1 +1 @@
-<!-- Redirects to settings. See +page.server.ts -->
\ No newline at end of file
+<!-- Redirects to /admin/settings. See +page.server.ts -->
\ No newline at end of file
diff --git a/src/routes/dashboard/+page.server.ts b/src/routes/dashboard/+page.server.ts
index 02d0519..e54a5aa 100644
--- a/src/routes/dashboard/+page.server.ts
+++ b/src/routes/dashboard/+page.server.ts
@@ -1,3 +1,9 @@
+/**
+ * 308: Permanently redirect /dashboard/ to /dashboard/roll-call.
+ * 
+ * This is where users should start for the dashboard.
+ */
+
 import { base } from "$app/paths";
 import { redirect } from "@sveltejs/kit";
 
diff --git a/src/routes/dashboard/+page.svelte b/src/routes/dashboard/+page.svelte
index 360d973..26fb99e 100644
--- a/src/routes/dashboard/+page.svelte
+++ b/src/routes/dashboard/+page.svelte
@@ -1 +1 @@
-<!-- Redirects to dashboard/roll-call. See +page.server.ts -->
\ No newline at end of file
+<!-- Redirects to /dashboard/roll-call. See +page.server.ts -->
\ No newline at end of file

From 212281ffc8e8e330b03f2042fef409b2ae275fa7 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Fri, 17 Jan 2025 17:28:13 -0500
Subject: [PATCH 16/21] del presets

---
 src/lib/delegate_presets/README.md | 5 ++++-
 src/lib/delegate_presets/index.ts  | 7 +++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/src/lib/delegate_presets/README.md b/src/lib/delegate_presets/README.md
index 56efd04..eb01a05 100644
--- a/src/lib/delegate_presets/README.md
+++ b/src/lib/delegate_presets/README.md
@@ -1,5 +1,8 @@
 # Delegate Presets
 
-This folder contains utilities for handling delegate presets (`index.ts`) and all delegate rosters presets (`preset-xx.json`).
+This folder contains presets for delegate rosters and utilities for managing those rosters. In particular, this folder contains:
+
+- `index.ts`, a module that provides some utilities for handling presets
+- `preset-xx.json`, the preset data files
 
 Additional delegate rosters can be defined by creating a new file `preset-KEY.json` to this folder and adding an entry for `KEY` in the `PRESETS` const of `index.ts`.
diff --git a/src/lib/delegate_presets/index.ts b/src/lib/delegate_presets/index.ts
index f93124d..02fabf5 100644
--- a/src/lib/delegate_presets/index.ts
+++ b/src/lib/delegate_presets/index.ts
@@ -1,3 +1,10 @@
+/**
+ * This module provides helpers for managing presets of delegate rosters.
+ * 
+ * For example, the United Nations roster (consisting of all United Nations member states)
+ * is a frequently used roster, so it is provided for convenience!
+ */
+
 import type { DelegateAttrs } from "$lib/types";
 import DEFAULT_DELEGATES_JSON from "$lib/delegate_presets/preset-un.json";
 

From 55f070878777c4d0129d5f01a33c41048eb68200 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Fri, 17 Jan 2025 17:36:43 -0500
Subject: [PATCH 17/21] $lib/motions

---
 src/lib/motions/README.md          |  5 ++++-
 src/lib/motions/definitions.ts     | 11 ++++++++--
 src/lib/motions/form_validation.ts |  4 ++++
 src/lib/motions/sort.ts            | 32 +++++++++++++++++++++++++++---
 src/lib/types.d.ts                 | 26 +++++++++++++++++++++---
 5 files changed, 69 insertions(+), 9 deletions(-)

diff --git a/src/lib/motions/README.md b/src/lib/motions/README.md
index 5a52a4f..300ea09 100644
--- a/src/lib/motions/README.md
+++ b/src/lib/motions/README.md
@@ -1,3 +1,6 @@
 # Motions
 
-This folder contains scripts for defining motion properties (`definitions.ts`) as well as boilerplate code to handle those properties (`form_validation.ts` for form validation, `sort.ts` for motion sorting).
+This folder, in essence, contains modules for defining motions. These allow easier manipulation of motion properties and specifically enable the following:
+
+- Input validation for motions in forms
+- Sorting motions
diff --git a/src/lib/motions/definitions.ts b/src/lib/motions/definitions.ts
index 97f39d7..7f3d54f 100644
--- a/src/lib/motions/definitions.ts
+++ b/src/lib/motions/definitions.ts
@@ -1,4 +1,11 @@
-import type { Motion, MotionKind, SortEntry } from "$lib/types";
+/**
+ * Some definitions for motion properties.
+ * 
+ * This consolidates important properties under one file
+ * (other files in `$lib/motions` should only define infrastructure for using motions).
+ */
+
+import type { Motion, MotionKind, SortOrder } from "$lib/types";
 import { nonEmptyString, presentDelegateSchema, refineSpeakingTime, timeSchema, topicSchema } from "$lib/motions/form_validation";
 import type { MotionInput } from "$lib/motions/types";
 import { z } from "zod";
@@ -47,7 +54,7 @@ const _assert: Is<TypeFields, ConstFields> = {};
  * 
  * Any kinds not specified in this list are thrown at the end.
  */
-export const DEFAULT_SORT_PRIORITY: SortEntry[] = [
+export const DEFAULT_SORT_PRIORITY: SortOrder = [
     { kind: ["ext"], order: [] },
     { kind: ["unmod"], order: [{ property: "totalTime", ascending: false }] },
     { kind: ["mod", "rr"], order: [{ property: "nSpeakers", ascending: false }, { property: "totalTime", ascending: false }] }
diff --git a/src/lib/motions/form_validation.ts b/src/lib/motions/form_validation.ts
index 50905b4..3280d0b 100644
--- a/src/lib/motions/form_validation.ts
+++ b/src/lib/motions/form_validation.ts
@@ -1,3 +1,7 @@
+/**
+ * Implements form validation for motions.
+ */
+
 import type { Delegate } from "$lib/db/delegates";
 import { parseTime } from "$lib/util/time";
 import { z } from "zod";
diff --git a/src/lib/motions/sort.ts b/src/lib/motions/sort.ts
index 53c10b2..3150488 100644
--- a/src/lib/motions/sort.ts
+++ b/src/lib/motions/sort.ts
@@ -1,4 +1,14 @@
-import type { Motion, SortEntry, SortKind, SortOrderProperty } from "$lib/types";
+/**
+ * This module implements the infrastructure required to sort motions.
+ * 
+ * The most important API of this module is `compareMotions`, which is a comparator 
+ * (which can be inserted into `Array.sort`) that compares motions.
+ * 
+ * Using it requires defining a "sort order", which is the priority in which motions are ordered.
+ * See the docs for `SortOrder` in `$lib/types` for more details about how sort order is set up.
+ */
+
+import type { Motion, SortKind, SortOrder, SortOrderProperty } from "$lib/types";
 import { compare, type Comparator } from "$lib/util";
 
 export const SORT_KIND_NAMES: Record<SortKind, string> = {
@@ -29,7 +39,7 @@ function getSortKind(m: Motion): SortKind | undefined {
     if ("isExtension" in m && m.isExtension) return "ext";
     return m.kind;
 }
-function getSortIndex(m: Motion, priority: SortEntry[]): number {
+function getSortIndex(m: Motion, priority: SortOrder): number {
     let kind = getSortKind(m);
 
     // Find the index of this motion under the priority, putting it at the end if not in the list.
@@ -60,7 +70,23 @@ function getSortProperty(m: Motion, key: SortOrderProperty): unknown {
     throw Error(`Motion cannot be sorted by ${key}`);
 }
 
-export function compareMotions(priority: SortEntry[]): Comparator<Motion> {
+/**
+ * Creates a "comparator" for motions, using the provided sort order.
+ * 
+ * A comparator is a function that "compares" two motions. This can be directly input to 
+ * `Array.sort` to sort an array of motions. For example,
+ * 
+ * ```ts
+ * const motions: Motion[] = [ ... ];
+ * const comparator = compareMotions(...);
+ * 
+ * motions.sort(comparator);
+ * ```
+ * 
+ * @param priority the sort order to use.
+ * @returns the comparator
+ */
+export function compareMotions(priority: SortOrder): Comparator<Motion> {
     return (a, b) => {
         let k: number;
 
diff --git a/src/lib/types.d.ts b/src/lib/types.d.ts
index 390499c..5b2399c 100644
--- a/src/lib/types.d.ts
+++ b/src/lib/types.d.ts
@@ -77,8 +77,6 @@ export type SortOrderKey = {
  * 1. first be sorted by total time in descending order, 
  * 2. then by number of spekers in descending order,
  * 3. then (implicitly) by order received.
- * 
- * A array of `SortEntry`s (`SortEntry[]`) defines the complete sort order.
  */
 export type SortEntry = {
     /**
@@ -91,6 +89,28 @@ export type SortEntry = {
     order: SortOrderKey[]
 };
 
+/**
+ * A complete sort order.
+ * 
+ * A sort order consists of a list of sort entries.
+ * The order of the entries indicates which motion kinds get priority
+ * (with the first entry getting the highest priority and the last entry getting the least).
+ * 
+ * For example, take this `SortOrder`:
+ * ```ts
+ * [
+ *     { kind: ["ext"], order: [ ... ] },
+ *     { kind: ["unmod"], order: [ ... ] },
+ *     { kind: ["mod", "rr"], order: [ ... ] }
+ * ]
+ * ```
+ * 
+ * This indicates that extensions have higher priority than unmoderated caucuses, 
+ *     which have higher priority than moderated caucuses and round robins.
+ * It also indicates that moderated caucuses and round robins have equal priority.
+ */
+export type SortOrder = SortEntry[];
+
 // These types are used to define settings.
 
 /**
@@ -122,7 +142,7 @@ export type Settings = {
      * 
      * Any kinds not specified in this list are thrown at the end.
      */
-    sortOrder: SortEntry[],
+    sortOrder: SortOrder,
     
     /**
      * The title of the assembly.

From d93fea3228188fb4fbf83cbca4c700b61fdd80ff Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Fri, 17 Jan 2025 23:32:47 -0500
Subject: [PATCH 18/21] dnd doc

---
 src/lib/components/SpeakerList.svelte         |  8 +-
 src/lib/util/dnd.ts                           | 92 +++++++++++--------
 .../dashboard/points-motions/+page.svelte     |  8 +-
 3 files changed, 61 insertions(+), 47 deletions(-)

diff --git a/src/lib/components/SpeakerList.svelte b/src/lib/components/SpeakerList.svelte
index 5b7d2e6..7ee8148 100644
--- a/src/lib/components/SpeakerList.svelte
+++ b/src/lib/components/SpeakerList.svelte
@@ -11,7 +11,7 @@
     import { type Delegate, findDelegate } from "$lib/db/delegates";
     import { formatValidationError, presentDelegateSchema } from "$lib/motions/form_validation";
     import type { DelegateID, Speaker, SpeakerEntryID } from "$lib/types";
-    import { getDndItemId, isDndShadow, processDrag } from "$lib/util/dnd";
+    import { isDndShadow } from "$lib/util/dnd";
     import { triggerConfirmModal } from "$lib/util";
     
     import Icon from "@iconify/svelte";
@@ -81,7 +81,7 @@
     // A mapping from IDs to Speakers:
     let orderMap = $derived(Object.fromEntries(
         order.filter(s => typeof s.id === "string" && s.id)
-            .map((speaker, i) => [getDndItemId(speaker), { speaker, i }])
+            .map((speaker, i) => [speaker.id, { speaker, i }])
     ));
 
     // List item elements per order item
@@ -273,8 +273,8 @@
             }
         }
     }}
-        onconsider={(e) => dndItems = processDrag(e)}
-        onfinalize={(e) => order = dndItems = processDrag(e)}
+        onconsider={(e) => dndItems = e.detail.items}
+        onfinalize={(e) => order = dndItems = e.detail.items}
         aria-labelledby="speaker-list-header"
     >
         {#each dndItems as speaker, i (speaker.id)}
diff --git a/src/lib/util/dnd.ts b/src/lib/util/dnd.ts
index 18f0f58..2336882 100644
--- a/src/lib/util/dnd.ts
+++ b/src/lib/util/dnd.ts
@@ -1,55 +1,69 @@
-import { SHADOW_ITEM_MARKER_PROPERTY_NAME, SHADOW_PLACEHOLDER_ITEM_ID, type DndEvent } from "svelte-dnd-action";
-
-export type DndItem = {
-    id: string,
-    [SHADOW_ITEM_MARKER_PROPERTY_NAME]?: boolean
-    originalId?: string
-};
-
 /**
- * Processes a DndEvent, creating a new array which the data array can be set to.
+ * Utilities for managing svelte-dnd-action.
+ * 
+ * To implement drag-and-drop with svelte-dnd-action, the following steps should be performed:
+ * 1. Make a stateful copy of the array you want to observe.
+ * 2. Apply the `use:dndzone` or `use:dragHandleZone` onto the element that should be DnDable.
+ *     a. Set the given events: 
+ *         - `onconsider = (e) => copy = e.detail.items`, 
+ *         - `onfinalize = (e) => original = copy = e.detail.items`
+ * 3. Apply any styling to the shadow element and dragged element.
  * 
- * Typically, `order = e.detail.items` would be done to update state.
- * However, this can cause problems as ID is corrupted and original ID data can be lost.
+ * In full, that would look like the following:
+ * ```svelte
+ * <script lang="ts">
+ *   // (1)
+ *   let dndItems = $state($state.snapshot(originalItems));
+ *   $effect(() => { dndItems = originalItems });
  * 
- * Thus, this function does processing to preserve that data.
+ *   // ...
+ * </script>
  * 
- * @param e The event
- * @returns The updated array
+ * <!-- (2) -->
+ * <div 
+ *   use:dndzone={{
+ *     items: dndItems,
+ *     flipDurationMs: 150,
+ *     dropTargetStyle: {}
+ *   }}
+ *   onconsider={(e) => dndItems = e.detail.items}
+ *   onfinalize={(e) => originalItems = dndItems = e.detail.items}
+ * >
+ *   {#each dndItems as item (item.id)}
+ *     {@const shadow = isDndShadow(item)}
+ *     <!-- (3): Apply attributes, with `shadow` indicating shadow element -->
+ *   {/each}
+ * </div>
+ * 
+ * <!-- (3): Apply styling to dragged element (which should copy element's styling) -->
+ * <style lang="postcss">
+ *   :global(#dnd-action-dragged-el).dnd-list-item {
+ *     @apply ...;
+ *   }
+ *   :global(.dark #dnd-action-dragged-el).dnd-list-item {
+ *     @apply ...;
+ *   }
+ * </style>
+ * ```
  */
-export function processDrag<E extends DndItem>(e: CustomEvent<DndEvent<E>>): E[] {
-    let placeholder = e.detail.items.find(s => s.id === SHADOW_PLACEHOLDER_ITEM_ID);
-    if (placeholder) {
-        placeholder.originalId = e.detail.info.id;
-    }
 
-    return e.detail.items;
-}
+import { SHADOW_ITEM_MARKER_PROPERTY_NAME } from "svelte-dnd-action";
+
+export type DndItem = {
+    id: string,
+    [SHADOW_ITEM_MARKER_PROPERTY_NAME]?: boolean
+    originalId?: string
+};
 
 /**
  * Tests whether item is a shadow element
- * (i.e., is being dragged and needs a placeholder in DOM).
+ * (i.e., the data representing this element is being dragged
+ *    and currently has a placeholder in its original position)
  * @param item the item
  * @returns whether it is a shadow element
  */
 export function isDndShadow(item: DndItem): boolean {
-    let it: {
-        [SHADOW_ITEM_MARKER_PROPERTY_NAME]?: boolean
-    } = item;
-    return !!it[SHADOW_ITEM_MARKER_PROPERTY_NAME];
-}
-
-/**
- * Gets the true ID of a drag-and-drop item.
- * @param item The item
- * @returns The ID
- */
-export function getDndItemId(item: DndItem): string {
-    let id = item.id;
-    if (id == SHADOW_PLACEHOLDER_ITEM_ID) {
-        id = item.originalId || id;
-    }
-    return id;
+    return !!item[SHADOW_ITEM_MARKER_PROPERTY_NAME];
 }
 
 /**
diff --git a/src/routes/dashboard/points-motions/+page.svelte b/src/routes/dashboard/points-motions/+page.svelte
index 62169b0..40dfadf 100644
--- a/src/routes/dashboard/points-motions/+page.svelte
+++ b/src/routes/dashboard/points-motions/+page.svelte
@@ -11,7 +11,7 @@
   import { MOTION_LABELS } from "$lib/motions/definitions";
   import { compareMotions as motionComparator } from "$lib/motions/sort";
   import type { Motion } from "$lib/types";
-  import { createDragTr, isDndShadow, processDrag } from "$lib/util/dnd";
+  import { createDragTr, isDndShadow } from "$lib/util/dnd";
   import { stringifyTime } from "$lib/util/time";
 
   import Icon from "@iconify/svelte";
@@ -23,7 +23,7 @@
   const sortOrder = queryStore(() => db.getSetting("sortOrder"), []);
   const modalStore = getModalStore();
 
-  // A clone of $motions used solely for use:dragHandleZone
+  // A clone of $motions used solely for use:dndzone
   let dndItems = $state($state.snapshot($motions));
   $effect(() => { dndItems = $motions; });
 
@@ -151,8 +151,8 @@
             dropTargetStyle: {},
             transformDraggedElement: (el) => createDragTr(el, motionTable)
           }}
-          onconsider={(e) => dndItems = processDrag(e)}
-          onfinalize={(e) => $motions = dndItems = processDrag(e)}
+          onconsider={(e) => dndItems = e.detail.items}
+          onfinalize={(e) => $motions = dndItems = e.detail.items}
           aria-labelledby="motion-table-header"
         >
           {#each dndItems as motion, i (motion.id)}

From 0026f70d6cf75eb7a19ba4b730311bfeee454188 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Fri, 17 Jan 2025 23:45:50 -0500
Subject: [PATCH 19/21] miscellaneous additions

---
 doc/CONTRIBUTING.md                  | 38 ----------------------------
 src/lib/components/README.md         |  9 +++++++
 src/lib/components/motions/README.md |  3 +++
 src/lib/context/index.svelte.ts      | 19 ++++++++++++++
 src/lib/flags/README.md              |  3 +++
 src/lib/flags/flagcdn.ts             |  9 +++++++
 src/lib/types.d.ts                   |  4 +++
 src/lib/util/README.md               |  9 +++++++
 src/lib/util/clock.ts                |  7 +++++
 src/lib/util/index.ts                |  4 +++
 src/lib/util/time.ts                 |  9 +++++++
 11 files changed, 76 insertions(+), 38 deletions(-)
 create mode 100644 src/lib/components/README.md
 create mode 100644 src/lib/components/motions/README.md
 create mode 100644 src/lib/flags/README.md
 create mode 100644 src/lib/util/README.md

diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md
index 03021de..a57cf25 100644
--- a/doc/CONTRIBUTING.md
+++ b/doc/CONTRIBUTING.md
@@ -27,44 +27,6 @@ Note that it is not usually necessary to run these commands locally, as the Gith
 
 This script is mainly only useful when you find a bug in the deployed website that you can't reproduce with the `npm run dev` build. If you find a bug you can't reproduce, try doing `npm run build && npm run preview`.
 
-## File Structure
-
-Here's a brief summary of the file structure.
-
-```text
-doc/
-└── ...                     # Documentation pages (like this one!)
-src/
-├── lib/
-│   ├── components/
-│   │   └── ...             # various Svelte components
-│   ├── delegate-presets/
-│   │   ├── index.ts        # handles delegate presets
-│   │   ├── preset-xx.json  # a delegate preset
-│   │   └── ...
-│   ├── motions/
-│   │   └── ...             # motion management
-│   ├── stores/
-│   │   └── ...             # store management
-│   └── util/
-│       └── ...             # various utilities
-└── routes/                 # all accessible routes on the website
-    ├── admin/
-    │   ├── settings/
-    │   └── stats/
-    └── dashboard/
-        ├── current-motion/
-        ├── points-motions/
-        ├── roll-call/
-        ├── speakers-list/
-        ├── utilities/
-        └── ...
-static/
-└── ...                    # files to upload directly onto the website
-```
-
-Many of the directories will have a `README.md` that gives clarifications and more documentation for what the directory is used for.
-
 ## Making Changes
 
 This GitHub repository is the source of all changes and updates:
diff --git a/src/lib/components/README.md b/src/lib/components/README.md
new file mode 100644
index 0000000..9a254f0
--- /dev/null
+++ b/src/lib/components/README.md
@@ -0,0 +1,9 @@
+# Components
+
+This folder contains helper Svelte components used to construct the pages seen in each route. This folder is also broken up into sub-folders which further classify given helper components. This includes:
+
+- `app-bar/`: Components related to the app bar seen on the top of the page
+- `del-label/`: Components related to delegate labels and flags
+- `modals/`: Components related to modals
+- `motions/`: Components related to motions (particularly motion pages)
+- `nav/`: Components related to navigation components
diff --git a/src/lib/components/motions/README.md b/src/lib/components/motions/README.md
new file mode 100644
index 0000000..78f656e
--- /dev/null
+++ b/src/lib/components/motions/README.md
@@ -0,0 +1,3 @@
+# Motion Components
+
+Components used to define motion pages or the page components themselves! Any component that is a direct descendant of this folder is a helper component, whereas any component in `./page/` represents an actual component page.
diff --git a/src/lib/context/index.svelte.ts b/src/lib/context/index.svelte.ts
index 3e1b88c..3a32f0e 100644
--- a/src/lib/context/index.svelte.ts
+++ b/src/lib/context/index.svelte.ts
@@ -1,3 +1,22 @@
+/**
+ * A module encapsulating the session context.
+ * 
+ * A context holds data that should be preserved across pages.
+ * This includes data accessed from the database, 
+ * the header title, and the header topic.
+ * 
+ * The benefit of including database values in the context is that 
+ * the context will cache the data when traveling across pages,
+ * meaning an additional database access is not necessary 
+ * when entering a new page.
+ * 
+ * The important API here are:
+ * - `getSessionContext()`: Gets the session context.
+ * - `resetSessionContext(ctx)`: Clears related database data + session context data.
+ * - `createSessionContext()`: Creates a new session context (if one does not exist).
+ *     This typically does not need to be done since it's done once in `./routes/+layout.svelte`.
+ */
+
 import { db, DEFAULT_SESSION_DATA } from "$lib/db/index.svelte";
 import type { SessionContext } from "$lib/types";
 import { getContext, hasContext, setContext } from "svelte";
diff --git a/src/lib/flags/README.md b/src/lib/flags/README.md
new file mode 100644
index 0000000..dc0e2ab
--- /dev/null
+++ b/src/lib/flags/README.md
@@ -0,0 +1,3 @@
+# Flag Utilities
+
+This folder is meant as a helper for accessing and resolving flag URLs. At the moment, there is one supported source (FlagCDN), whose access is specified in `flagcdn.ts`.
diff --git a/src/lib/flags/flagcdn.ts b/src/lib/flags/flagcdn.ts
index 2199197..d8dfb3d 100644
--- a/src/lib/flags/flagcdn.ts
+++ b/src/lib/flags/flagcdn.ts
@@ -1,3 +1,7 @@
+/**
+ * Flag URLs via FlagCDN.
+ */
+
 import { browser } from "$app/environment";
 
 let FLAG_CODES: Record<string, string> = {};
@@ -11,6 +15,11 @@ async function _flag_codes(): Promise<typeof FLAG_CODES> {
     );
 }
 
+/**
+ * Gets the flag URL associated with a given ISO 3166-1 alpha-2 code.
+ * @param key The two-letter code
+ * @returns the URL, if it exists
+ */
 export async function getFlagUrl(key: string): Promise<URL | undefined> {
     if (!browser) return;
     if (key.toLowerCase() in await _flag_codes()) {
diff --git a/src/lib/types.d.ts b/src/lib/types.d.ts
index 5b2399c..6a6cf66 100644
--- a/src/lib/types.d.ts
+++ b/src/lib/types.d.ts
@@ -1,3 +1,7 @@
+/**
+ * This declaration file declares types that are useful all throughout the project.
+ */
+
 import type { Readable, Writable } from "svelte/store";
 
 /**
diff --git a/src/lib/util/README.md b/src/lib/util/README.md
new file mode 100644
index 0000000..afaca9c
--- /dev/null
+++ b/src/lib/util/README.md
@@ -0,0 +1,9 @@
+# Utilities
+
+This folder includes utility functions used throughout the project. Some examples include:
+
+- `index.ts`: Miscellaneous helpers
+- `clock.ts`: Worker used for synchronized timekeeping
+- `dnd.ts`: Drag-and-drop helpers
+- `popup.ts`: Popup helpers
+- `time.ts`: Helpers relating to time strings
diff --git a/src/lib/util/clock.ts b/src/lib/util/clock.ts
index 93d0f03..e051915 100644
--- a/src/lib/util/clock.ts
+++ b/src/lib/util/clock.ts
@@ -1,3 +1,10 @@
+/**
+ * A clock source.
+ * 
+ * This can be deployed in a Web Worker to create a synchronized clock independent of the UI.
+ * See `Timer`'s module script for an example.
+ */
+
 import type { ClockMessage } from "$lib/types";
 
 function loop(ts: number) {
diff --git a/src/lib/util/index.ts b/src/lib/util/index.ts
index 73eba1a..a9612a0 100644
--- a/src/lib/util/index.ts
+++ b/src/lib/util/index.ts
@@ -1,3 +1,7 @@
+/**
+ * Miscellaneous helper functions.
+ */
+
 import type { ModalSettings, ModalStore } from "@skeletonlabs/skeleton";
 import { cubicOut } from "svelte/easing";
 import type { TransitionConfig } from "svelte/transition";
diff --git a/src/lib/util/time.ts b/src/lib/util/time.ts
index 6355388..0139020 100644
--- a/src/lib/util/time.ts
+++ b/src/lib/util/time.ts
@@ -1,3 +1,10 @@
+/**
+ * This module holds helpers that are useful for managing time strings.
+ * 
+ * In particular, this module has helpers used for converting time stored in seconds
+ * to and from time strings (e.g., mm:ss).
+ */
+
 const UNITS = [60, 60, 24, 365, Infinity];
 const PADDING = [2, 2, 2, 3, undefined];
 const MIN_SEGMENTS = 2;
@@ -52,6 +59,8 @@ export function parseTime(timeStr: string): number | undefined {
 /**
  * Converts the current number of seconds to a formatted string of the form mm:ss.
  * @param secs the number of seconds
+ * @param roundingMode if a fractional number of seconds is provided, it must be rounded to the nearest integer.
+ *     This parameter decides whether it is floored, rounded, or ceil'd.
  * @returns the time string, or undefined if negative or non-finite or non-integral
  */
 export function stringifyTime(secs: number, roundingMode: "floor" | "round" | "ceil" = "ceil"): string | undefined {

From d298ce9fd00b3f9e739a8594d5f21f66501810cc Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Sat, 18 Jan 2025 11:24:29 -0500
Subject: [PATCH 20/21] modal + db

---
 .../components/modals/EditDelegateCard.svelte | 11 ++++
 src/lib/components/modals/EditModal.svelte    | 18 ++++++
 .../components/modals/EditMotionCard.svelte   | 11 ++++
 .../modals/EnableDelegatesCard.svelte         | 21 +++++--
 src/lib/db/index.svelte.ts                    | 60 +++++++++++++++++++
 5 files changed, 116 insertions(+), 5 deletions(-)

diff --git a/src/lib/components/modals/EditDelegateCard.svelte b/src/lib/components/modals/EditDelegateCard.svelte
index 50cbdd7..49d7347 100644
--- a/src/lib/components/modals/EditDelegateCard.svelte
+++ b/src/lib/components/modals/EditDelegateCard.svelte
@@ -1,8 +1,19 @@
+<!--
+  @component Modal card for editing (or creating) a delegate.
+
+  This modal consists of a simple form to specify the delegate's attributes.
+-->
 <script lang="ts">
     import type { DelegateAttrs } from "$lib/types";
     import EditModal from "$lib/components/modals/EditModal.svelte";
 
     interface Props {
+        /**
+         * Original properties of the delegate.
+         * 
+         * If `undefined`, this form will be used to "create" a delegate
+         * (rather than "edit" a delegate).
+         */
         attrs?: DelegateAttrs
     }
 
diff --git a/src/lib/components/modals/EditModal.svelte b/src/lib/components/modals/EditModal.svelte
index ff64eb1..5aa5576 100644
--- a/src/lib/components/modals/EditModal.svelte
+++ b/src/lib/components/modals/EditModal.svelte
@@ -1,11 +1,29 @@
+<!--
+  @component A basic modal wrapper. All modals in this folder likely should build on this component.
+
+  This wrapper creates a card layout which spans across the screen.
+  It also provides "close" and "submit" methods, which can be used to exit the modal.
+-->
 <script lang="ts">
     import { getModalStore } from "@skeletonlabs/skeleton";
     import { type Snippet } from "svelte";
 
     interface Props {
+        /**
+         * The title at the top of the modal
+         */
         title: string;
+        /**
+         * The inner content of the modal
+         */
         children: Snippet<[{
+            /**
+             * Submits data to the modal trigger and closes the modal.
+             */
             submit: typeof submit,
+            /**
+             * Closes the modal without submitting data to the modal trigger.
+             */
             close: typeof close
         }]>;
     }
diff --git a/src/lib/components/modals/EditMotionCard.svelte b/src/lib/components/modals/EditMotionCard.svelte
index 08a02a5..c069248 100644
--- a/src/lib/components/modals/EditMotionCard.svelte
+++ b/src/lib/components/modals/EditMotionCard.svelte
@@ -1,3 +1,11 @@
+<!--
+  @component Modal card for editing a motion.
+
+  This modal wraps around `MotionForm`.
+  Note that this will not update the provided motion object,
+  but rather "submit" the changed motion back to the trigger.
+-->
+
 <script lang="ts">
     import type { Motion } from "$lib/types";
     import MotionForm from "$lib/components/MotionForm.svelte";
@@ -6,6 +14,9 @@
     import { inputifyMotion } from "$lib/motions/definitions";
     
     interface Props {
+        /**
+         * The motion data to edit.
+         */
         motion: Motion;
     }
     let { motion }: Props = $props();
diff --git a/src/lib/components/modals/EnableDelegatesCard.svelte b/src/lib/components/modals/EnableDelegatesCard.svelte
index 21b4b39..56e7a2b 100644
--- a/src/lib/components/modals/EnableDelegatesCard.svelte
+++ b/src/lib/components/modals/EnableDelegatesCard.svelte
@@ -1,9 +1,24 @@
+<!--
+  @component Modal card for mass configuring which delegates are "enabled" (in the settings page).
+
+  This modal's content consists of a textbox where delegate names can be pasted,
+  synthesizing a list of names that will be enabled.
+
+  On submission, this modal exports the list of enabled IDs.
+  This list of enabled IDs is used as the list of "enabled" delegates 
+  (all previously "enabled" delegates not on this list will be disabled).
+-->
+
+
 <script lang="ts">
     import { SvelteSet } from "svelte/reactivity";
     import EditModal from "./EditModal.svelte";
     import type { Delegate } from "$lib/db/delegates";
 
     interface Props {
+        /**
+         * List of delegates.
+         */
         attrs: Delegate[];
     }
 
@@ -11,10 +26,6 @@
     let enabled = new SvelteSet<number>();
     let inputText: string = $state("");
 
-    function exit(submit: (value: any) => void) {
-        submit(enabled);
-    }
-
     function keydown(k: KeyboardEvent) {
         if (k.code === "Enter") {
             k.preventDefault();
@@ -50,7 +61,7 @@
             </div>
             <div class="flex justify-end gap-1">
                 <button class="btn variant-filled-error" type="button" onclick={close}>Cancel</button>
-                <button class="btn variant-filled-primary" type="button" onclick={() => exit(submit)}>Done</button>
+                <button class="btn variant-filled-primary" type="button" onclick={() => submit(enabled)}>Done</button>
             </div>
         </div>
     {/snippet}
diff --git a/src/lib/db/index.svelte.ts b/src/lib/db/index.svelte.ts
index 0f1f4c6..5791780 100644
--- a/src/lib/db/index.svelte.ts
+++ b/src/lib/db/index.svelte.ts
@@ -1,3 +1,10 @@
+/**
+ * This module holds infrastructure that handles the database 
+ * that stores much of CouchMUN's persistent data.
+ * 
+ * This module uses Dexie to interact with the IndexedDB API.
+ */
+
 import { Delegate } from "./delegates";
 import { KeyValuePair, toKeyValueArray, toObject } from "./keyval";
 import { DEFAULT_DELEGATES } from "$lib/delegate_presets";
@@ -7,10 +14,28 @@ import type { DelegateAttrs, DelegateID, DelSessionData, PrevSessionData, Sessio
 import { Dexie, liveQuery, type EntityTable, type IndexableType, type InsertType } from "dexie";
 import { readable, type Readable, type Updater, type Writable } from "svelte/store";
 
+/**
+ * The class representing the session database.
+ * This can be accessed as a singleton through the `db` const.
+ */
 export class SessionDatabase extends Dexie {
+    /**
+     * The table of delegates, which includes their attributes, enabled status, and session state.
+     */
     delegates!: EntityTable<Delegate, "id">;
+    /**
+     * The key-value store of settings.
+     */
     settings!: EntityTable<KeyValuePair, "key">;
+    /**
+     * The key-value store of global session data, 
+     * including the current speakers list and the current motion.
+     */
     sessionData!: EntityTable<KeyValuePair, "key">;
+    /**
+     * The key-value store of previous session data.
+     * This is used to access previous session data (when needed).
+     */
     prevSessions!: EntityTable<KeyValuePair<number, PrevSessionData>, "key">;
 
     constructor() {
@@ -93,6 +118,10 @@ export class SessionDatabase extends Dexie {
     }
     /**
      * Gets the setting from the settings database.
+     * 
+     * This is preferred over `db.settings.get(...)` 
+     * as this method will properly typecheck the keys you enter.
+     * 
      * @param key the key to get the setting for
      * @returns the value of the setting
      */
@@ -109,6 +138,9 @@ export class SessionDatabase extends Dexie {
     settingStore<K extends keyof Settings>(key: K, fallback?: Settings[K]): Writable<Settings[K] | undefined> {
         return getKVStore(this.settings, key, fallback);
     }
+    /**
+     * Resets all settings from the database to the default.
+     */
     async resetSettings() {
         await this.transaction("rw", this.settings, async () => {
             await this.settings.clear();
@@ -127,9 +159,21 @@ export class SessionDatabase extends Dexie {
         return getKVStore(this.sessionData, key, fallback);
     }
 
+    /**
+     * Gets a value from the session data table.
+     * 
+     * This is preferred over `db.sessionData.get(...)`
+     * as this method will properly typecheck the keys you enter.
+     * 
+     * @param key the key to get the value of
+     * @returns the value
+     */
     async getSessionValue<K extends keyof SessionData>(key: K): Promise<SessionData[K]> {
         return this.sessionData.get(key).then(e => e?.val);
     }
+    /**
+     * Resets the session data (both global and delegate session data) to default values.
+     */
     async resetSessionData() {
         await this.transaction("rw", [this.sessionData, this.delegates], async () => {
             await this.delegates.toCollection().modify(DEFAULT_DEL_SESSION_DATA);
@@ -138,6 +182,9 @@ export class SessionDatabase extends Dexie {
             await this.sessionData.bulkAdd(toKeyValueArray(DEFAULT_SESSION_DATA));
         })
     }
+    /**
+     * Saves the current session data, creating a new entry in the prevSessions table.
+     */
     async saveSessionData() {
         return this.transaction("rw", [this.delegates, this.sessionData, this.prevSessions], async () => {
             let sessionKey = await this.getSessionValue("sessionKey") ?? await this.prevSessions.count();
@@ -151,6 +198,10 @@ export class SessionDatabase extends Dexie {
             } });
         });
     }
+    /**
+     * Loads session data, pulling from an entry in the prevSessions table.
+     * @param key The associated key in the prevSessions table
+     */
     async loadSessionData(key: number) {
         return this.transaction("rw", [this.delegates, this.sessionData, this.prevSessions], async () => {
             let entry = await this.prevSessions.get(key);
@@ -178,6 +229,15 @@ export class SessionDatabase extends Dexie {
     }
 }
 
+/**
+ * A reference to the database.
+ * 
+ * This provides field access to all of the database tables
+ * (e.g., `delegates`, `settings`, `sessionData`, `prevSessions`),
+ * 
+ * as well as access to some useful methods
+ * (e.g., various stores, `addDelegate`, `getSetting`, etc.).
+ */
 export const db = new SessionDatabase();
 
 db.on("ready", async (tx) => {

From df99f27bb01aff87b5b394738513ca5104ff55a1 Mon Sep 17 00:00:00 2001
From: Henry Bui <henry.h.bui05@gmail.com>
Date: Sat, 18 Jan 2025 11:36:20 -0500
Subject: [PATCH 21/21] page doc

---
 src/routes/+layout.svelte                        | 7 +++++++
 src/routes/+page.svelte                          | 1 +
 src/routes/admin/+layout.svelte                  | 5 +++++
 src/routes/admin/settings/+page.svelte           | 3 +++
 src/routes/admin/stats/+page.svelte              | 5 ++++-
 src/routes/dashboard/+layout.svelte              | 6 ++++++
 src/routes/dashboard/points-motions/+page.svelte | 6 ++++++
 src/routes/dashboard/roll-call/+page.svelte      | 4 ++++
 src/routes/dashboard/utilities/+page.svelte      | 7 ++++++-
 9 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/src/routes/+layout.svelte b/src/routes/+layout.svelte
index 8dc1a50..970fb91 100644
--- a/src/routes/+layout.svelte
+++ b/src/routes/+layout.svelte
@@ -1,3 +1,10 @@
+<!-- 
+  @component This component is the base layout for all pages on the website 
+  (including /dashboard/ and /admin/).
+
+  It simply initializes some useful stores and listeners for the page.
+-->
+
 <script lang="ts">
     import "../app.css";
     import { computePosition, autoUpdate, offset, shift, flip, arrow, size } from '@floating-ui/dom';
diff --git a/src/routes/+page.svelte b/src/routes/+page.svelte
index b5ce1d1..a0ed836 100644
--- a/src/routes/+page.svelte
+++ b/src/routes/+page.svelte
@@ -1,3 +1,4 @@
+<!-- @component The front page. -->
 <script lang="ts">
     import { base } from "$app/paths";
     import MetaTags from "$lib/components/MetaTags.svelte";
diff --git a/src/routes/admin/+layout.svelte b/src/routes/admin/+layout.svelte
index 2cde0fa..8ed0de0 100644
--- a/src/routes/admin/+layout.svelte
+++ b/src/routes/admin/+layout.svelte
@@ -1,3 +1,8 @@
+<!--
+  @component This component is the base layout for the admin pages on the site.
+  
+  This basically initializes the admin app bar (the yellow bar on the top).
+-->
 <script lang="ts">
     import { base } from '$app/paths';
     import BarHeader from '$lib/components/app-bar/BarHeader.svelte';
diff --git a/src/routes/admin/settings/+page.svelte b/src/routes/admin/settings/+page.svelte
index d9eb2dd..5e2dfe0 100644
--- a/src/routes/admin/settings/+page.svelte
+++ b/src/routes/admin/settings/+page.svelte
@@ -1,3 +1,6 @@
+<!--
+  @component The admin settings page (used for configuring settings).
+-->
 <script lang="ts">
     import LabeledSlideToggle from "$lib/components/LabeledSlideToggle.svelte";
     import MetaTags from "$lib/components/MetaTags.svelte";
diff --git a/src/routes/admin/stats/+page.svelte b/src/routes/admin/stats/+page.svelte
index bbbebc0..3c65677 100644
--- a/src/routes/admin/stats/+page.svelte
+++ b/src/routes/admin/stats/+page.svelte
@@ -1,3 +1,6 @@
+<!--
+  @component The admin stats page (used for viewing delegate statistics).
+-->
 <script lang="ts">
     import MetaTags from "$lib/components/MetaTags.svelte";
     import DelLabel from "$lib/components/del-label/DelLabel.svelte";
@@ -10,7 +13,7 @@
     import { stringifyTime } from "$lib/util/time";
     
     import Icon from "@iconify/svelte";
-    import { ProgressBar, type PopupSettings, popup, type PaginationSettings, Paginator } from "@skeletonlabs/skeleton";
+    import { ProgressBar, popup, type PaginationSettings, Paginator } from "@skeletonlabs/skeleton";
 
     const { delegates, barTitle } = getSessionContext();
 
diff --git a/src/routes/dashboard/+layout.svelte b/src/routes/dashboard/+layout.svelte
index af070a0..cd95db0 100644
--- a/src/routes/dashboard/+layout.svelte
+++ b/src/routes/dashboard/+layout.svelte
@@ -1,3 +1,9 @@
+<!-- 
+  @component This component is the base layout for all dashboard pages.
+
+  It creates the header bar on the top menu and sets up the Navigation drawers.
+-->
+
 <script lang="ts">
     import { navigating, page } from '$app/state';
     import MetaTags from '$lib/components/MetaTags.svelte';
diff --git a/src/routes/dashboard/points-motions/+page.svelte b/src/routes/dashboard/points-motions/+page.svelte
index 40dfadf..d3ca431 100644
--- a/src/routes/dashboard/points-motions/+page.svelte
+++ b/src/routes/dashboard/points-motions/+page.svelte
@@ -1,3 +1,9 @@
+<!--
+  @component The points & motions page (used for creating and viewing the current points & motions).
+
+  This includes a MotionForm (which is used to add motions)
+  and a sortable motion table (which is used to view and rearrange and edit motions).
+-->
 <script lang="ts">
   import { goto } from "$app/navigation";
   import { base } from "$app/paths";
diff --git a/src/routes/dashboard/roll-call/+page.svelte b/src/routes/dashboard/roll-call/+page.svelte
index edc3f28..9cbf66a 100644
--- a/src/routes/dashboard/roll-call/+page.svelte
+++ b/src/routes/dashboard/roll-call/+page.svelte
@@ -1,3 +1,7 @@
+<!-- 
+  @component The page for roll call, 
+    which consists of a long list of delegates and an option to select NP/P/PV.
+-->
 <script lang="ts">
     import { base } from "$app/paths";
     import DelLabel from "$lib/components/del-label/DelLabel.svelte";
diff --git a/src/routes/dashboard/utilities/+page.svelte b/src/routes/dashboard/utilities/+page.svelte
index fe603a9..6482b93 100644
--- a/src/routes/dashboard/utilities/+page.svelte
+++ b/src/routes/dashboard/utilities/+page.svelte
@@ -1,3 +1,8 @@
+<!-- 
+  @component A utilities page, which is meant to be a page for miscellaneous situations in committee.
+
+  Notably, this page includes a timer and title, which can be used quite generically.
+-->
 <script lang="ts">
     import DelAutocomplete from "$lib/components/DelAutocomplete.svelte";
     import DelLabel from "$lib/components/del-label/DelLabel.svelte";
@@ -9,7 +14,7 @@
     import { parseTime } from "$lib/util/time";
 
     import Icon from "@iconify/svelte";
-    import { popup, type PopupSettings } from "@skeletonlabs/skeleton";
+    import { popup } from "@skeletonlabs/skeleton";
 
     const { delegates } = getSessionContext();