From 1862567bc7980c7f2b8f79d16d64c766998e68cb Mon Sep 17 00:00:00 2001
From: Torsten Dittmann <torsten.dittmann@googlemail.com>
Date: Tue, 3 Jun 2025 16:44:59 +0200
Subject: [PATCH 1/3] fix: switch docs layout to svelte 5, avoiding state
 mismatch

- Replaces PascalCase import with kebab-case, switches to modern Svelte 5 syntax including SVGAttributes type
- afterNavigate instead of navigating store
- snippet-based slots
- Makes Icon name prop optional and fixes aria attribute format.
---
 src/lib/components/shared/button.svelte   |  2 +-
 src/lib/components/ui/icon/icon.svelte    |  8 ++---
 src/lib/layouts/Docs.svelte               |  8 ++---
 src/lib/layouts/Sidebar.svelte            |  2 +-
 src/routes/docs/references/+layout.svelte | 41 +++++++++--------------
 5 files changed, 23 insertions(+), 38 deletions(-)

diff --git a/src/lib/components/shared/button.svelte b/src/lib/components/shared/button.svelte
index 07d81fee4..01c3de13b 100644
--- a/src/lib/components/shared/button.svelte
+++ b/src/lib/components/shared/button.svelte
@@ -2,7 +2,7 @@
     import { classNames } from '$lib/utils/classnames';
     import type { HTMLButtonAttributes, HTMLAnchorAttributes } from 'svelte/elements';
     import { cva, type VariantProps } from 'cva';
-    import InlineTag from '../ui/InlineTag.svelte';
+    import InlineTag from '../ui/inline-tag.svelte';
 
     const button = cva(
         [
diff --git a/src/lib/components/ui/icon/icon.svelte b/src/lib/components/ui/icon/icon.svelte
index 47bdaa899..a740af026 100644
--- a/src/lib/components/ui/icon/icon.svelte
+++ b/src/lib/components/ui/icon/icon.svelte
@@ -1,13 +1,11 @@
 <script lang="ts">
-    import { classNames } from '$lib/utils/classnames';
-    import type { SvelteHTMLElements } from 'svelte/elements';
+    import type { SVGAttributes } from 'svelte/elements';
     import type { IconType } from './types';
 
-    type Props = SvelteHTMLElements['svg'] & {
+    type Props = SVGAttributes<SVGElement> & {
         class?: string;
-        name: IconType;
+        name?: IconType;
     };
-
     const {
         xmlns = 'http://www.w3.org/2000/svg',
         viewBox = '0 0 24 24',
diff --git a/src/lib/layouts/Docs.svelte b/src/lib/layouts/Docs.svelte
index c3b813df6..953b8ee76 100644
--- a/src/lib/layouts/Docs.svelte
+++ b/src/lib/layouts/Docs.svelte
@@ -1,5 +1,4 @@
 <script lang="ts" module>
-    import { navigating } from '$app/stores';
     import { writable } from 'svelte/store';
 
     export type DocsLayoutVariant = 'default' | 'expanded' | 'two-side-navs';
@@ -40,8 +39,6 @@
 </script>
 
 <script lang="ts">
-    import { run } from 'svelte/legacy';
-
     import { Search, IsLoggedIn } from '$lib/components';
     import { isMac } from '$lib/utils/platform';
     import { getContext, setContext } from 'svelte';
@@ -49,6 +46,7 @@
     import { page } from '$app/state';
     import { getAppwriteDashboardUrl } from '$lib/utils/dashboard';
     import { Button, Icon, InlineTag } from '$lib/components/ui';
+    import { afterNavigate } from '$app/navigation';
 
     interface Props {
         variant?: DocsLayoutVariant;
@@ -67,10 +65,10 @@
     let variantClass = $derived(variantClasses[variant]);
 
     $effect(() => {
-        $layoutState.currentVariant = variant;
+        $layoutState.currentVariant = isReferences ? 'expanded' : variant;
     });
 
-    navigating.subscribe(() => {
+    afterNavigate(() => {
         layoutState.update((n) => ({
             ...n,
             showReferences: false,
diff --git a/src/lib/layouts/Sidebar.svelte b/src/lib/layouts/Sidebar.svelte
index 34adcf9b6..c7f2cfaac 100644
--- a/src/lib/layouts/Sidebar.svelte
+++ b/src/lib/layouts/Sidebar.svelte
@@ -138,7 +138,7 @@
                 rel="noopener noreferrer"
                 class="web-u-inline-width-100-percent-mobile"
             >
-                <Icon class="star" aria-hidden="true"></Icon>
+                <Icon class="star" aria-hidden />
                 <span class="text">Star on GitHub</span>
                 <InlineTag>{SOCIAL_STATS.GITHUB.STAT}</InlineTag>
             </Button>
diff --git a/src/routes/docs/references/+layout.svelte b/src/routes/docs/references/+layout.svelte
index dd1c3f46b..e602457b1 100644
--- a/src/routes/docs/references/+layout.svelte
+++ b/src/routes/docs/references/+layout.svelte
@@ -3,21 +3,25 @@
     import Docs from '$lib/layouts/Docs.svelte';
     import Sidebar, { type NavParent, type NavTree } from '$lib/layouts/Sidebar.svelte';
     import { preferredPlatform, preferredVersion } from '$lib/utils/references';
+    import type { Snippet } from 'svelte';
 
-    $: expandable = !!page.url.pathname.match(
-        /\/docs\/references\/.*?\/(client|server).*?\/.*?\/?/
+    const { children }: { children: Snippet } = $props();
+
+    const expandable = $derived(
+        !!page.url.pathname.match(/\/docs\/references\/.*?\/(client|server).*?\/.*?\/?/)
     );
 
-    $: platform = $preferredPlatform ?? page.params?.platform ?? 'client-web';
+    const platform = $derived($preferredPlatform ?? page.params?.platform ?? 'client-web');
 
-    /* correct platform prefix for references page */
-    $: resolvedPlatformPrefix = /^server-|^client-/.test(platform)
-        ? platform
-        : `server-${platform}`;
+    const resolvedPlatformPrefix = $derived(
+        /^server-|^client-/.test(platform) ? platform : `server-${platform}`
+    );
 
-    $: prefix = `/docs/references/${$preferredVersion ?? page.params?.version ?? 'cloud'}/${resolvedPlatformPrefix}`;
+    const prefix = $derived(
+        `/docs/references/${$preferredVersion ?? page.params?.version ?? 'cloud'}/${resolvedPlatformPrefix}`
+    );
 
-    $: navigation = [
+    const navigation: NavTree = $derived([
         {
             label: 'Getting started',
             items: [
@@ -93,22 +97,7 @@
                 }
             ]
         }
-        // {
-        // 	label: 'Debugging',
-        // 	items: [
-        // 		{
-        // 			icon: 'icon-document-search',
-        // 			label: 'Response codes',
-        // 			href: '/docs/advanced/platform/response-codes'
-        // 		},
-        // 		{
-        // 			icon: 'icon-document-report',
-        // 			label: 'Rate-limits',
-        // 			href: '/docs/advanced/platform/rate-limits'
-        // 		}
-        // 	]
-        // }
-    ] as NavTree;
+    ]);
 
     const parent: NavParent = {
         href: '/docs',
@@ -118,5 +107,5 @@
 
 <Docs variant={expandable ? 'expanded' : 'two-side-navs'} isReferences={expandable}>
     <Sidebar {navigation} {expandable} {parent} />
-    <slot />
+    {@render children()}
 </Docs>

From 2deddf466731a0717e89d6bf5032695a7c97c067 Mon Sep 17 00:00:00 2001
From: Torsten Dittmann <torsten.dittmann@googlemail.com>
Date: Tue, 3 Jun 2025 16:46:31 +0200
Subject: [PATCH 2/3] Remove isReferences check from currentVariant assignment

---
 src/lib/layouts/Docs.svelte | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/lib/layouts/Docs.svelte b/src/lib/layouts/Docs.svelte
index 953b8ee76..e5d50d0ed 100644
--- a/src/lib/layouts/Docs.svelte
+++ b/src/lib/layouts/Docs.svelte
@@ -65,7 +65,7 @@
     let variantClass = $derived(variantClasses[variant]);
 
     $effect(() => {
-        $layoutState.currentVariant = isReferences ? 'expanded' : variant;
+        $layoutState.currentVariant = variant;
     });
 
     afterNavigate(() => {

From 980309c7fa3abb1c5ad938d95ca4206fb10d41ae Mon Sep 17 00:00:00 2001
From: Torsten Dittmann <torsten.dittmann@googlemail.com>
Date: Tue, 3 Jun 2025 17:04:45 +0200
Subject: [PATCH 3/3] Refactor references page component

- Add type imports and improve type safety
- Remove unused selectedMenuItem variable and bindSelectedRef function
- Add early return guards for platform/version selection
- Remove replaceState parameter from goto navigation
- Clean up method grouping with proper return type
---
 .../[platform]/[service]/+page.svelte         | 35 ++++++-------------
 1 file changed, 10 insertions(+), 25 deletions(-)

diff --git a/src/routes/docs/references/[version]/[platform]/[service]/+page.svelte b/src/routes/docs/references/[version]/[platform]/[service]/+page.svelte
index 94f1f1feb..52daae2ec 100644
--- a/src/routes/docs/references/[version]/[platform]/[service]/+page.svelte
+++ b/src/routes/docs/references/[version]/[platform]/[service]/+page.svelte
@@ -26,6 +26,7 @@
     import Request from './(components)/Request.svelte';
     import Response from './(components)/Response.svelte';
     import RateLimits from './(components)/RateLimits.svelte';
+    import type { SDKMethod } from '$lib/utils/specs';
 
     let { data } = $props();
 
@@ -34,7 +35,6 @@
     const headings = getContext<LayoutContext>('headings');
 
     let selected: string | undefined = $state(undefined);
-    let selectedMenuItem: HTMLElement;
 
     headings.subscribe((n) => {
         const noVisible = Object.values(n).every((n) => !n.visible);
@@ -61,7 +61,9 @@
             correctPlatform = platform.replaceAll(`server-`, ``) as Platform;
         }
 
-        preferredPlatform.set(correctPlatform as Platform);
+        if ($preferredPlatform === correctPlatform) return;
+
+        preferredPlatform.set(correctPlatform);
 
         goto(`/docs/references/${version}/${platform}/${service}`, {
             noScroll: true
@@ -71,6 +73,8 @@
     function selectVersion(event: CustomEvent<unknown>) {
         const { platform, service } = page.params;
         const version = event.detail as Version;
+        if ($preferredVersion === version) return;
+
         preferredVersion.set(version);
         goto(`/docs/references/${version}/${platform}/${service}`, {
             noScroll: true
@@ -110,8 +114,7 @@
                 : `server-${$preferredPlatform}`;
 
             goto(`/docs/references/${$preferredVersion}/${platformMode}/${page.params.service}`, {
-                noScroll: true,
-                replaceState: false
+                noScroll: true
             });
         }
 
@@ -145,7 +148,7 @@
     /**
      * Sorts methods by their operation order and title
      */
-    function sortMethods(methods: any[]) {
+    function sortMethods(methods: SDKMethod[]) {
         return methods.sort((a, b) => {
             const orderA = getOperationOrder(a.title);
             const orderB = getOperationOrder(b.title);
@@ -156,11 +159,8 @@
         });
     }
 
-    /**
-     * Groups methods by their group attribute, null group goes to '' for ordering
-     */
-    function groupMethodsByGroup(methods: any[]) {
-        return methods.reduce((acc, method) => {
+    function groupMethodsByGroup(methods: SDKMethod[]) {
+        return methods.reduce<Record<string, SDKMethod[]>>((acc, method) => {
             const groupKey = method.group || '';
             if (!acc[groupKey]) {
                 acc[groupKey] = [];
@@ -170,20 +170,6 @@
         }, {});
     }
 
-    function bindSelectedRef(node: HTMLElement, isSelected: boolean) {
-        if (isSelected) {
-            selectedMenuItem = node;
-        }
-
-        return {
-            update(newIsSelected: boolean) {
-                if (newIsSelected) {
-                    selectedMenuItem = node;
-                }
-            }
-        };
-    }
-
     let platformBindingForSelect = $derived(page.params.platform as Platform);
     let platform = $derived(/**$preferredPlatform ?? */ page.params.platform as Platform);
     let platformType = $derived(platform.startsWith('client-') ? 'CLIENT' : 'SERVER');
@@ -400,7 +386,6 @@
                                                 href={`#${method.id}`}
                                                 class="web-references-menu-link text-caption"
                                                 class:is-selected={method.id === selected}
-                                                use:bindSelectedRef={method.id === selected}
                                             >
                                                 {method.title}
                                             </a>