From 9cbf4fdc48adca608206474903192323bfac7edc Mon Sep 17 00:00:00 2001
From: Ilia Mashkov <hikkikomori7@gmail.com>
Date: Sun, 18 Jan 2026 15:55:07 +0300
Subject: [PATCH] doc: comments for codebase and updated documentation

---
 .../appliedFontsStore.svelte.ts               |  7 ++++++
 .../selectedFontsStore.svelte.ts              |  3 +++
 .../ui/FontApplicator/FontApplicator.svelte   | 20 ++++++++++++----
 .../Font/ui/FontListItem/FontListItem.svelte  |  3 +++
 .../ui/FontVirtualList/FontVirtualList.svelte |  7 +++++-
 .../model/store/displayedFontsStore.svelte.ts |  5 ++++
 .../ui/FontSampler/FontSampler.svelte         |  9 ++++++++
 .../lib/filterManager/filterManager.svelte.ts |  5 ++++
 .../GetFonts/lib/mapper/mapManagerToParams.ts |  6 +++++
 .../GetFonts/ui/Filters/Filters.svelte        | 18 ++++-----------
 .../ui/FiltersControl/FilterControls.svelte   | 13 ++++-------
 .../ui/SuggestedFonts/SuggestedFonts.svelte   |  4 ++++
 .../controlManager/controlManager.svelte.ts   |  6 +++++
 .../SetupFont/ui/SetupFontMenu.svelte         |  7 +++---
 src/shared/lib/accessibility/motion.svelte.ts |  1 +
 .../createEntityStore.svelte.ts               |  5 ++++
 src/shared/lib/utils/splitArray/splitArray.ts |  6 +++++
 .../ui/CheckboxFilter/CheckboxFilter.svelte   | 23 ++++++++-----------
 .../ui/ComboControl/ComboControl.svelte       |  7 ++++++
 19 files changed, 111 insertions(+), 44 deletions(-)
diff --git a/src/entities/Font/model/store/appliedFontsStore/appliedFontsStore.svelte.ts b/src/entities/Font/model/store/appliedFontsStore/appliedFontsStore.svelte.ts
index 6e8fa63..3394b6f 100644
--- a/src/entities/Font/model/store/appliedFontsStore/appliedFontsStore.svelte.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/appliedFontsStore.svelte.ts
@@ -2,6 +2,13 @@ import { SvelteMap } from 'svelte/reactivity';
 
 export type FontStatus = 'loading' | 'loaded' | 'error';
 
+/**
+ * Manager that handles loading of the fonts
+ * Adds <link /> tags to <head />
+ * - Uses batch loading to reduce the number of requests
+ * - Uses a queue to prevent too many requests at once
+ * - Purges unused fonts after a certain time
+ */
 class AppliedFontsManager {
     // Stores: slug -> timestamp of last visibility
     #usageTracker = new Map<string, number>();
diff --git a/src/entities/Font/model/store/selectedFontsStore/selectedFontsStore.svelte.ts b/src/entities/Font/model/store/selectedFontsStore/selectedFontsStore.svelte.ts
index d90d22b..de3c3f8 100644
--- a/src/entities/Font/model/store/selectedFontsStore/selectedFontsStore.svelte.ts
+++ b/src/entities/Font/model/store/selectedFontsStore/selectedFontsStore.svelte.ts
@@ -1,4 +1,7 @@
 import { createEntityStore } from '$shared/lib';
 import type { UnifiedFont } from '../../types';
 
+/**
+ * Store that handles collection of selected fonts
+ */
 export const selectedFontsStore = createEntityStore<UnifiedFont>([]);
diff --git a/src/entities/Font/ui/FontApplicator/FontApplicator.svelte b/src/entities/Font/ui/FontApplicator/FontApplicator.svelte
index 110e596..9bd3415 100644
--- a/src/entities/Font/ui/FontApplicator/FontApplicator.svelte
+++ b/src/entities/Font/ui/FontApplicator/FontApplicator.svelte
@@ -1,19 +1,31 @@
 <!--
     Component: FontApplicator
-
     Loads fonts from fontshare with link tag
+    - Loads font only if it's not already applied
+    - Uses IntersectionObserver to detect when font is visible
+    - Adds smooth transition when font is loaded
 -->
 <script lang="ts">
-import {
-    appliedFontsManager,
-} from '$entities/Font/model/store/appliedFontsStore/appliedFontsStore.svelte';
 import { cn } from '$shared/shadcn/utils/shadcn-utils';
 import type { Snippet } from 'svelte';
+import { appliedFontsManager } from '../../model';
 
 interface Props {
+    /**
+     * Font name to set
+     */
     name: string;
+    /**
+     * Font id to load
+     */
     id: string;
+    /**
+     * Additional classes
+     */
     className?: string;
+    /**
+     * Children
+     */
     children?: Snippet;
 }
 
diff --git a/src/entities/Font/ui/FontListItem/FontListItem.svelte b/src/entities/Font/ui/FontListItem/FontListItem.svelte
index 1cb87d2..12c52a7 100644
--- a/src/entities/Font/ui/FontListItem/FontListItem.svelte
+++ b/src/entities/Font/ui/FontListItem/FontListItem.svelte
@@ -13,6 +13,9 @@ import {
 import FontApplicator from '../FontApplicator/FontApplicator.svelte';
 
 interface Props {
+    /**
+     * Object with information about font
+     */
     font: UnifiedFont;
 }
 
diff --git a/src/entities/Font/ui/FontVirtualList/FontVirtualList.svelte b/src/entities/Font/ui/FontVirtualList/FontVirtualList.svelte
index 71c9838..65102db 100644
--- a/src/entities/Font/ui/FontVirtualList/FontVirtualList.svelte
+++ b/src/entities/Font/ui/FontVirtualList/FontVirtualList.svelte
@@ -1,7 +1,12 @@
+<!--
+    Component: FontVirtualList
+    - Renders a virtualized list of fonts
+    - Handles font registration with the manager
+-->
 <script lang="ts" generics="T extends { id: string }">
 import { VirtualList } from '$shared/ui';
 import type { ComponentProps } from 'svelte';
-import { appliedFontsManager } from '../../model/store/appliedFontsStore/appliedFontsStore.svelte';
+import { appliedFontsManager } from '../../model';
 
 interface Props extends Omit<ComponentProps<typeof VirtualList<T>>, 'onVisibleItemsChange'> {
     onVisibleItemsChange?: (items: T[]) => void;
diff --git a/src/features/DisplayFont/model/store/displayedFontsStore.svelte.ts b/src/features/DisplayFont/model/store/displayedFontsStore.svelte.ts
index 6877ae8..723cec6 100644
--- a/src/features/DisplayFont/model/store/displayedFontsStore.svelte.ts
+++ b/src/features/DisplayFont/model/store/displayedFontsStore.svelte.ts
@@ -1,5 +1,10 @@
 import { selectedFontsStore } from '$entities/Font';
 
+/**
+ * Store for displayed font samples
+ * - Handles shown text
+ * - Stores selected fonts for display
+ */
 export class DisplayedFontsStore {
     #sampleText = $state('The quick brown fox jumps over the lazy dog');
 
diff --git a/src/features/DisplayFont/ui/FontSampler/FontSampler.svelte b/src/features/DisplayFont/ui/FontSampler/FontSampler.svelte
index 274c704..872e11c 100644
--- a/src/features/DisplayFont/ui/FontSampler/FontSampler.svelte
+++ b/src/features/DisplayFont/ui/FontSampler/FontSampler.svelte
@@ -10,8 +10,17 @@ import {
 import { ContentEditable } from '$shared/ui';
 
 interface Props {
+    /**
+     * Font info
+     */
     font: UnifiedFont;
+    /**
+     * Text to display
+     */
     text: string;
+    /**
+     * Font settings
+     */
     fontSize?: number;
     lineHeight?: number;
     letterSpacing?: number;
diff --git a/src/features/GetFonts/lib/filterManager/filterManager.svelte.ts b/src/features/GetFonts/lib/filterManager/filterManager.svelte.ts
index 28528c6..c32a5e6 100644
--- a/src/features/GetFonts/lib/filterManager/filterManager.svelte.ts
+++ b/src/features/GetFonts/lib/filterManager/filterManager.svelte.ts
@@ -4,6 +4,11 @@ import type { FilterConfig } from '../../model';
 
 /**
  * Create a filter manager instance.
+ * - Uses debounce to update search query for better performance.
+ * - Manages filter instances for each group.
+ *
+ * @param config - Configuration for the filter manager.
+ * @returns - An instance of the filter manager.
  */
 export function createFilterManager<TValue extends string>(config: FilterConfig<TValue>) {
     const search = createDebouncedState(config.queryValue ?? '');
diff --git a/src/features/GetFonts/lib/mapper/mapManagerToParams.ts b/src/features/GetFonts/lib/mapper/mapManagerToParams.ts
index d560a41..637a052 100644
--- a/src/features/GetFonts/lib/mapper/mapManagerToParams.ts
+++ b/src/features/GetFonts/lib/mapper/mapManagerToParams.ts
@@ -1,6 +1,12 @@
 import type { FontshareParams } from '$entities/Font';
 import type { FilterManager } from '../filterManager/filterManager.svelte';
 
+/**
+ * Maps filter manager to fontshare params.
+ *
+ * @param manager - Filter manager instance.
+ * @returns - Partial fontshare params.
+ */
 export function mapManagerToParams(manager: FilterManager): Partial<FontshareParams> {
     return {
         q: manager.debouncedQueryValue,
diff --git a/src/features/GetFonts/ui/Filters/Filters.svelte b/src/features/GetFonts/ui/Filters/Filters.svelte
index 0f7c27a..3210cd5 100644
--- a/src/features/GetFonts/ui/Filters/Filters.svelte
+++ b/src/features/GetFonts/ui/Filters/Filters.svelte
@@ -1,18 +1,8 @@
+<!--
+    Component: Filters
+    Renders a list of CheckboxFilter components for each filter group.
+-->
 <script lang="ts">
-/**
- * Filters Component
- *
- * Orchestrates all filter properties for the sidebar. Connects filter stores
- * to CheckboxFilter components, organizing them by filter type:
- *
- * - Font provider: Google Fonts vs Fontshare
- * - Font subset: Character subsets available (Latin, Latin Extended, etc.)
- * - Font category: Serif, Sans-serif, Display, etc.
- *
- * This component handles reactive sync between filterManager selections
- * and the unifiedFontStore using an $effect block to ensure filters are
- * automatically synchronized whenever selections change.
- */
 import { CheckboxFilter } from '$shared/ui';
 import { filterManager } from '../../model';
 </script>
diff --git a/src/features/GetFonts/ui/FiltersControl/FilterControls.svelte b/src/features/GetFonts/ui/FiltersControl/FilterControls.svelte
index 31ee53f..2b74696 100644
--- a/src/features/GetFonts/ui/FiltersControl/FilterControls.svelte
+++ b/src/features/GetFonts/ui/FiltersControl/FilterControls.svelte
@@ -1,14 +1,11 @@
+<!--
+    Component: FiltersControl
+    Renders a group of action buttons for filter operations.
+    - Reset: Clears all active filters (outline variant for secondary action)
+-->
 <script lang="ts">
 import { Button } from '$shared/shadcn/ui/button';
 import { filterManager } from '../../model';
-
-/**
- * Controls Component
- *
- * Action button group for filter operations. Provides two buttons:
- *
- * - Reset: Clears all active filters (outline variant for secondary action)
- */
 </script>
 
 <div class="flex flex-row gap-2">
diff --git a/src/features/GetFonts/ui/SuggestedFonts/SuggestedFonts.svelte b/src/features/GetFonts/ui/SuggestedFonts/SuggestedFonts.svelte
index 9a2565d..3c24e8c 100644
--- a/src/features/GetFonts/ui/SuggestedFonts/SuggestedFonts.svelte
+++ b/src/features/GetFonts/ui/SuggestedFonts/SuggestedFonts.svelte
@@ -1,3 +1,7 @@
+<!--
+    Component: SuggestedFonts
+    Renders a list of suggested fonts in a virtualized list to improve performance.
+-->
 <script lang="ts">
 import {
     FontListItem,
diff --git a/src/features/SetupFont/lib/controlManager/controlManager.svelte.ts b/src/features/SetupFont/lib/controlManager/controlManager.svelte.ts
index d9a2ac8..3307c4c 100644
--- a/src/features/SetupFont/lib/controlManager/controlManager.svelte.ts
+++ b/src/features/SetupFont/lib/controlManager/controlManager.svelte.ts
@@ -3,6 +3,12 @@ import {
     createTypographyControl,
 } from '$shared/lib';
 
+/**
+ * Creates a typography control manager that handles a collection of typography controls.
+ *
+ * @param configs - Array of control configurations.
+ * @returns - Typography control manager instance.
+ */
 export function createTypographyControlManager(configs: ControlModel[]) {
     const controls = $state(
         configs.map(({ id, increaseLabel, decreaseLabel, controlLabel, ...config }) => ({
diff --git a/src/features/SetupFont/ui/SetupFontMenu.svelte b/src/features/SetupFont/ui/SetupFontMenu.svelte
index 345dd22..5941585 100644
--- a/src/features/SetupFont/ui/SetupFontMenu.svelte
+++ b/src/features/SetupFont/ui/SetupFontMenu.svelte
@@ -1,7 +1,8 @@
+<!--
+    Component: SetupFontMenu
+    Contains controls for setting up font properties.
+-->
 <script lang="ts">
-/**
- * Component containing controls for setting up font properties.
- */
 import { Separator } from '$shared/shadcn/ui/separator/index';
 import { Trigger as SidebarTrigger } from '$shared/shadcn/ui/sidebar';
 import { ComboControl } from '$shared/ui';
diff --git a/src/shared/lib/accessibility/motion.svelte.ts b/src/shared/lib/accessibility/motion.svelte.ts
index c0a7c52..4dceb77 100644
--- a/src/shared/lib/accessibility/motion.svelte.ts
+++ b/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);
diff --git a/src/shared/lib/helpers/createEntityStore/createEntityStore.svelte.ts b/src/shared/lib/helpers/createEntityStore/createEntityStore.svelte.ts
index 28afcc9..14e2c30 100644
--- a/src/shared/lib/helpers/createEntityStore/createEntityStore.svelte.ts
+++ b/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);
 }
diff --git a/src/shared/lib/utils/splitArray/splitArray.ts b/src/shared/lib/utils/splitArray/splitArray.ts
index 5d8bf71..5dca87b 100644
--- a/src/shared/lib/utils/splitArray/splitArray.ts
+++ b/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) => (
diff --git a/src/shared/ui/CheckboxFilter/CheckboxFilter.svelte b/src/shared/ui/CheckboxFilter/CheckboxFilter.svelte
index 8372dd4..996dc7b 100644
--- a/src/shared/ui/CheckboxFilter/CheckboxFilter.svelte
+++ b/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;
diff --git a/src/shared/ui/ComboControl/ComboControl.svelte b/src/shared/ui/ComboControl/ComboControl.svelte
index 4f444d1..c567d13 100644
--- a/src/shared/ui/ComboControl/ComboControl.svelte
+++ b/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';
