From 1bb699ea2d726bc04f4cfe945244b63a49d443ed Mon Sep 17 00:00:00 2001
From: Ilia Mashkov <hikkikomori7@gmail.com>
Date: Fri, 2 Jan 2026 21:15:40 +0300
Subject: [PATCH] chore: add documentation for svelte components

---
 src/app/App.svelte                          | 10 ++++++
 src/app/ui/Layout.svelte                    | 15 ++++++++
 src/routes/Page.svelte                      |  9 +++++
 src/widgets/AppSidebar/ui/AppSidebar.svelte | 12 +++++++
 src/widgets/AppSidebar/ui/Controls.svelte   | 11 ++++++
 src/widgets/AppSidebar/ui/Filters.svelte    | 40 ++++++++++++++-------
 6 files changed, 85 insertions(+), 12 deletions(-)

diff --git a/src/app/App.svelte b/src/app/App.svelte
index 92b6e0e..4934271 100644
--- a/src/app/App.svelte
+++ b/src/app/App.svelte
@@ -1,4 +1,14 @@
 <script lang="ts">
+/**
+ * App Component
+ *
+ * Application entry point component. Wraps the main page route within the shared
+ * layout shell. This is the root component mounted by the application.
+ *
+ * Structure:
+ * - Layout provides sidebar, header/footer, and page container
+ * - Page renders the current route content
+ */
 import Page from '$routes/Page.svelte';
 import Layout from './ui/Layout.svelte';
 </script>
diff --git a/src/app/ui/Layout.svelte b/src/app/ui/Layout.svelte
index 531d7ac..b250bac 100644
--- a/src/app/ui/Layout.svelte
+++ b/src/app/ui/Layout.svelte
@@ -1,8 +1,23 @@
 <script lang="ts">
+/**
+ * Layout Component
+ *
+ * Root layout wrapper that provides the application shell structure. Handles favicon,
+ * sidebar provider initialization, and renders child routes with consistent structure.
+ *
+ * Layout structure:
+ * - Header area (currently empty, reserved for future use)
+ * - Collapsible sidebar with main content area
+ * - Footer area (currently empty, reserved for future use)
+ *
+ * Uses Sidebar.Provider to enable mobile-responsive collapsible sidebar behavior
+ * throughout the application.
+ */
 import favicon from '$shared/assets/favicon.svg';
 import * as Sidebar from '$shared/shadcn/ui/sidebar/index';
 import { AppSidebar } from '$widgets/AppSidebar';
 
+/** Slot content for route pages to render */
 let { children } = $props();
 </script>
 
diff --git a/src/routes/Page.svelte b/src/routes/Page.svelte
index d8dbc14..1c3ee63 100644
--- a/src/routes/Page.svelte
+++ b/src/routes/Page.svelte
@@ -1,4 +1,13 @@
 <script>
+/**
+ * Page Component
+ *
+ * Main page route component. This is the default route that users see when
+ * accessing the application. Currently displays a welcome message.
+ *
+ * Note: This is a placeholder component. Replace with actual application content
+ * as the font comparison and filtering features are implemented.
+ */
 </script>
 
 <h1>Welcome to Svelte + Vite</h1>
diff --git a/src/widgets/AppSidebar/ui/AppSidebar.svelte b/src/widgets/AppSidebar/ui/AppSidebar.svelte
index 3762beb..1d1f276 100644
--- a/src/widgets/AppSidebar/ui/AppSidebar.svelte
+++ b/src/widgets/AppSidebar/ui/AppSidebar.svelte
@@ -1,4 +1,16 @@
 <script lang="ts">
+/**
+ * AppSidebar Component
+ *
+ * Main application sidebar widget. Contains filter controls and action buttons
+ * for font filtering operations. Organized into two sections:
+ *
+ * - Filters: Category-based filter groups (providers, subsets, categories)
+ * - Controls: Apply/Reset buttons for filter actions
+ *
+ * Uses Sidebar.Root from shadcn for responsive sidebar behavior including
+ * mobile drawer and desktop persistent sidebar modes.
+ */
 import * as Sidebar from '$shared/shadcn/ui/sidebar/index';
 import Controls from './Controls.svelte';
 import Filters from './Filters.svelte';
diff --git a/src/widgets/AppSidebar/ui/Controls.svelte b/src/widgets/AppSidebar/ui/Controls.svelte
index 3fa3d6d..c8b01e8 100644
--- a/src/widgets/AppSidebar/ui/Controls.svelte
+++ b/src/widgets/AppSidebar/ui/Controls.svelte
@@ -1,4 +1,15 @@
 <script lang="ts">
+/**
+ * Controls Component
+ *
+ * Action button group for filter operations. Provides two buttons:
+ *
+ * - Reset: Clears all active filters (outline variant for secondary action)
+ * - Apply: Applies selected filters (primary variant for main action)
+ *
+ * Buttons are equally sized (flex-1) for balanced layout. Note:
+ * Functionality not yet implemented - wire up to filter stores.
+ */
 import { Button } from '$shared/shadcn/ui/button';
 </script>
 
diff --git a/src/widgets/AppSidebar/ui/Filters.svelte b/src/widgets/AppSidebar/ui/Filters.svelte
index 30001b1..6a6af11 100644
--- a/src/widgets/AppSidebar/ui/Filters.svelte
+++ b/src/widgets/AppSidebar/ui/Filters.svelte
@@ -1,26 +1,42 @@
 <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.
+ *
+ * Uses $derived for reactive access to filter states, ensuring UI updates
+ * when selections change through any means (sidebar, programmatically, etc.).
+ */
 import { categoryFilterStore } from '$features/CategoryFilter';
 import { providersFilterStore } from '$features/ProvidersFilter';
 import { subsetsFilterStore } from '$features/SubsetsFilter';
 import CheckboxFilter from '$shared/ui/CheckboxFilter/CheckboxFilter.svelte';
 
-const { categories: providers } = $derived($providersFilterStore);
-const { categories: subsets } = $derived($subsetsFilterStore);
-const { categories } = $derived($categoryFilterStore);
+/** Reactive properties from providers filter store */
+const { properties: providers } = $derived($providersFilterStore);
+/** Reactive properties from subsets filter store */
+const { properties: subsets } = $derived($subsetsFilterStore);
+/** Reactive properties from categories filter store */
+const { properties: categories } = $derived($categoryFilterStore);
 </script>
 
 <CheckboxFilter
-    filterName="Font provider"
-    categories={providers}
-    onCategoryToggle={providersFilterStore.toggleCategory}
+    displayedLabel="Font provider"
+    properties={providers}
+    onPropertyToggle={providersFilterStore.toggleProperty}
 />
 <CheckboxFilter
-    filterName="Font subset"
-    categories={subsets}
-    onCategoryToggle={subsetsFilterStore.toggleCategory}
+    displayedLabel="Font subset"
+    properties={subsets}
+    onPropertyToggle={subsetsFilterStore.toggleProperty}
 />
 <CheckboxFilter
-    filterName="Font category"
-    categories={categories}
-    onCategoryToggle={categoryFilterStore.toggleCategory}
+    displayedLabel="Font category"
+    properties={categories}
+    onPropertyToggle={categoryFilterStore.toggleProperty}
 />