doc: comments for codebase and updated documentation

src/shared/lib/accessibility/motion.svelte.ts

@@ -1,6 +1,7 @@
 // Check if we are in a browser environment
 const isBrowser = typeof window !== 'undefined';
 
+// A class to manage motion preference and provide a single instance for use everywhere
 class MotionPreference {
     // Reactive state
     #reduced = $state(false);

src/shared/lib/helpers/createEntityStore/createEntityStore.svelte.ts

@@ -75,6 +75,11 @@ export class EntityStore<T extends Entity> {
     }
 }
 
+/**
+ * Creates a new EntityStore instance with the given initial entities.
+ * @param initialEntities The initial entities to populate the store with.
+ * @returns - A new EntityStore instance.
+ */
 export function createEntityStore<T extends Entity>(initialEntities: T[] = []) {
     return new EntityStore<T>(initialEntities);
 }

src/shared/lib/utils/splitArray/splitArray.ts

@@ -1,3 +1,9 @@
+/**
+ * Splits an array into two arrays based on a callback function.
+ * @param array The array to split.
+ * @param callback The callback function to determine which array to push each item to.
+ * @returns - An array containing two arrays, the first array contains items that passed the callback, the second array contains items that failed the callback.
+ */
 export function splitArray<T>(array: T[], callback: (item: T) => boolean) {
     return array.reduce<[T[], T[]]>(
         ([pass, fail], item) => (

src/shared/ui/CheckboxFilter/CheckboxFilter.svelte

@@ -1,3 +1,12 @@
+<!--
+    Component: CheckboxFilter
+    A collapsible property filter with checkboxes. Displate selected count as a badge
+    and supports reduced motion for accessibility.
+    - Open by default for immediate visibility and interaction
+    - Badge shown only when filters are active to reduce visual noise
+    - Transitions use cubicOut for natural deceleration
+    - Local transition prevents animation when component first renders
+-->
 <script lang="ts">
 import type { Filter } from '$shared/lib';
 import { motion } from '$shared/lib';
@@ -10,23 +19,9 @@ import {
 } from '$shared/shadcn/ui/collapsible';
 import { Label } from '$shared/shadcn/ui/label';
 import ChevronDownIcon from '@lucide/svelte/icons/chevron-down';
-import { onMount } from 'svelte';
 import { cubicOut } from 'svelte/easing';
 import { slide } from 'svelte/transition';
 
-/**
- * CheckboxFilter Component
- *
- * A collapsible property filter with checkboxes. Displays selected count as a badge
- * and supports reduced motion for accessibility. Used in sidebar filtering UIs.
- *
- * Design choices:
- * - Open by default for immediate visibility and interaction
- * - Badge shown only when filters are active to reduce visual noise
- * - Transitions use cubicOut for natural deceleration
- * - Local transition prevents animation when component first renders
- */
-
 interface PropertyFilterProps {
     /** Label for this filter group (e.g., "Properties", "Tags") */
     displayedLabel: string;

src/shared/ui/ComboControl/ComboControl.svelte

@@ -1,3 +1,10 @@
+<!--
+    Component: ComboControl
+    Provides multiple ways to change certain value
+    - via Increase/Decrease buttons
+    - via Slider
+    - via Input
+-->
 <script lang="ts">
 import type { TypographyControl } from '$shared/lib';
 import { Button } from '$shared/shadcn/ui/button';