Light refactoring and code documentation

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:

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
+/>

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 text label that is 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
     }
 

src/lib/components/LabeledSlideToggle.svelte

@@ -1,13 +1,35 @@
-<!-- @migration-task Error while migrating Svelte code: $$props is used together with named props in a way that cannot be automatically migrated. -->
+<!--
+  @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
     }
@@ -16,12 +38,11 @@
         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>
 
-<!-- svelte-ignore a11y_label_has_associated_control : SlideToggle is a control -->
 <label class={labelClass}>
     {@render children()}
     <SlideToggle 

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";