Merge pull request #1885 from appwrite/feat-group

feat: group api docs
2025-12-06 04:22:07 +00:00 · 2025-04-23 09:03:54 +05:30
parent 37e49365d7 d19c3e2388
commit d5a8f1df47
6 changed files with 179 additions and 67 deletions
--- a/package.json
+++ b/package.json
@@ -35,7 +35,7 @@
        "@appwrite.io/console": "^0.6.4",
        "@appwrite.io/pink": "~0.26.0",
        "@appwrite.io/pink-icons": "~0.26.0",
-        "@appwrite.io/repo": "github:appwrite/appwrite#feat-multi-region-docs",
+        "@appwrite.io/repo": "github:appwrite/appwrite#1.6.x",
        "@eslint/compat": "^1.2.7",
        "@eslint/js": "^9.21.0",
        "@fingerprintjs/fingerprintjs": "^4.5.1",
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -31,8 +31,8 @@ importers:
        specifier: ~0.26.0
        version: 0.26.0
      '@appwrite.io/repo':
-        specifier: github:appwrite/appwrite#feat-multi-region-docs
-        version: https://codeload.github.com/appwrite/appwrite/tar.gz/4d81a901cbc48b94a720392a2611da028ea934b9
+        specifier: github:appwrite/appwrite#1.6.x
+        version: https://codeload.github.com/appwrite/appwrite/tar.gz/ed8c39f649fc05973aefcddc7aad6a427cca02d5
      '@eslint/compat':
        specifier: ^1.2.7
        version: 1.2.7(eslint@9.22.0(jiti@2.4.2))
@@ -263,8 +263,8 @@ packages:
  '@appwrite.io/pink@0.26.0':
    resolution: {integrity: sha512-iPeGE56pauzxuIXt15ZswjKCErwp3QdF3XOlJZfyYY7J2nirra85JNTL+3lWuFIf8yYWL7NbvCjhf8ig79TgwA==}

-  '@appwrite.io/repo@https://codeload.github.com/appwrite/appwrite/tar.gz/4d81a901cbc48b94a720392a2611da028ea934b9':
-    resolution: {tarball: https://codeload.github.com/appwrite/appwrite/tar.gz/4d81a901cbc48b94a720392a2611da028ea934b9}
+  '@appwrite.io/repo@https://codeload.github.com/appwrite/appwrite/tar.gz/ed8c39f649fc05973aefcddc7aad6a427cca02d5':
+    resolution: {tarball: https://codeload.github.com/appwrite/appwrite/tar.gz/ed8c39f649fc05973aefcddc7aad6a427cca02d5}
    version: 0.0.0

  '@babel/runtime@7.26.10':
@@ -3955,7 +3955,7 @@ snapshots:
      normalize.css: 8.0.1
      the-new-css-reset: 1.11.3

-  '@appwrite.io/repo@https://codeload.github.com/appwrite/appwrite/tar.gz/4d81a901cbc48b94a720392a2611da028ea934b9': {}
+  '@appwrite.io/repo@https://codeload.github.com/appwrite/appwrite/tar.gz/ed8c39f649fc05973aefcddc7aad6a427cca02d5': {}

  '@babel/runtime@7.26.10':
    dependencies:
--- a/src/lib/utils/specs.ts
+++ b/src/lib/utils/specs.ts
@@ -1,6 +1,6 @@
+import { error } from '@sveltejs/kit';
 import { OpenAPIV3 } from 'openapi-types';
 import { Platform, type ServiceValue } from './references';
-import { error } from '@sveltejs/kit';

 export type SDKMethod = {
    'rate-limit': number;
@@ -10,6 +10,7 @@ export type SDKMethod = {
    title: string;
    description: string;
    demo: string;
+    group?: string;
    parameters: Array<{
        name: string;
        description: string;
@@ -34,6 +35,7 @@ type SDKMethodModel = {
 type AppwriteOperationObject = OpenAPIV3.OperationObject & {
    'x-appwrite': {
        method: string;
+        group?: string;
        weight: number;
        cookies: boolean;
        type: string;
@@ -331,7 +333,8 @@ export async function getService(

        data.methods.push({
            id: operation['x-appwrite'].method,
-            demo: demo ?? '',
+            group: operation['x-appwrite'].group,
+            demo: typeof demo === 'string' ? demo : '',
            title: operation.summary ?? '',
            description: operation.description ?? '',
            parameters: parameters ?? [],
@@ -344,6 +347,17 @@ export async function getService(
        });
    }

+    // Sort methods by weight from x-appwrite metadata
+    data.methods.sort((a, b) => {
+        const aPath = api.paths[a.url] as OpenAPIV3.PathItemObject;
+        const bPath = api.paths[b.url] as OpenAPIV3.PathItemObject;
+        const aMethod = a.method.toLowerCase() as Lowercase<OpenAPIV3.HttpMethods>;
+        const bMethod = b.method.toLowerCase() as Lowercase<OpenAPIV3.HttpMethods>;
+        const aWeight = (aPath?.[aMethod] as AppwriteOperationObject)?.['x-appwrite']?.weight ?? 0;
+        const bWeight = (bPath?.[bMethod] as AppwriteOperationObject)?.['x-appwrite']?.weight ?? 0;
+        return aWeight - bWeight;
+    });
+
    return data;
 }

--- a/src/routes/docs/references/[version]/[platform]/[service]/+page.server.ts
+++ b/src/routes/docs/references/[version]/[platform]/[service]/+page.server.ts
@@ -1,7 +1,7 @@
-import { error } from '@sveltejs/kit';
-import { getService } from '$lib/utils/specs';
-import type { EntryGenerator, PageServerLoad } from './$types';
 import { Platform, Service, type ServiceValue, versions } from '$lib/utils/references';
+import { getService } from '$lib/utils/specs';
+import { error } from '@sveltejs/kit';
+import type { EntryGenerator, PageServerLoad } from './$types';

 const services = Object.values(Service);
 const platforms = Object.values(Platform);
@@ -19,8 +19,10 @@ export const entries: EntryGenerator = () => {
 export const load: PageServerLoad = async ({ params }) => {
    const { platform, service } = params;
    const version = params.version === 'cloud' ? '1.6.x' : params.version;
+
    if (!versions.includes(version)) error(404, 'Invalid version');
-    if (!services.includes(service as ServiceValue)) error(404, 'Invalid service');
    if (!platforms.includes(platform as Platform)) error(404, 'Invalid platform');
+    if (!services.includes(service as ServiceValue)) error(404, 'Invalid service');
+
    return getService(version, platform, service);
 };
--- a/src/routes/docs/references/[version]/[platform]/[service]/+page.svelte
+++ b/src/routes/docs/references/[version]/[platform]/[service]/+page.svelte
@@ -34,6 +34,8 @@
    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);
        if (selected && noVisible) {
@@ -42,6 +44,19 @@
        for (const key in n) {
            if (n[key].visible) {
                selected = key;
+                setTimeout(() => {
+                    if (selectedMenuItem) {
+                        selectedMenuItem.scrollIntoView({ behavior: 'smooth', block: 'center' });
+
+                        const menuContainer = selectedMenuItem.closest(
+                            '.web-references-menu-content'
+                        );
+                        if (menuContainer) {
+                            const offset = 100; // offset to position the item higher in the viewport
+                            menuContainer.scrollTop = menuContainer.scrollTop - offset;
+                        }
+                    }
+                }, 0);
                break;
            }
        }
@@ -127,6 +142,62 @@
        serviceDescription.substring(0, serviceDescription.indexOf('.') + 1)
    );

+    /**
+     * Determines the order of operations based on the method title.
+     * For eg. Create account, Get account, List accounts, Update account, Delete account.
+     */
+    function getOperationOrder(methodTitle: string): number {
+        const title = methodTitle.toLowerCase();
+        if (title.startsWith('create')) return 1;
+        if (title.startsWith('read') || title.startsWith('get') || title.startsWith('list'))
+            return 2;
+        if (title.startsWith('update')) return 3;
+        if (title.startsWith('delete')) return 4;
+        return 5; // Other operations
+    }
+
+    /**
+     * Sorts methods by their operation order and title
+     */
+    function sortMethods(methods: any[]) {
+        return methods.sort((a, b) => {
+            const orderA = getOperationOrder(a.title);
+            const orderB = getOperationOrder(b.title);
+            if (orderA === orderB) {
+                return a.title.localeCompare(b.title);
+            }
+            return orderA - orderB;
+        });
+    }
+
+    /**
+     * Groups methods by their group attribute, null group goes to '' for ordering
+     */
+    function groupMethodsByGroup(methods: any[]) {
+        return methods.reduce((acc, method) => {
+            const groupKey = method.group || '';
+            if (!acc[groupKey]) {
+                acc[groupKey] = [];
+            }
+            acc[groupKey].push(method);
+            return acc;
+        }, {});
+    }
+
+    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');
@@ -242,11 +313,14 @@
                    </div>
                {/if}
            </section>
-            {#each data.methods as method (method.id)}
+            {#each Object.entries(groupMethodsByGroup(data.methods)) as [group, methods]}
+                {#each sortMethods(methods) as method (method.id)}
                    <section class="web-article-content-grid-6-4">
                        <div class="web-article-content-grid-6-4-column-1 flex flex-col gap-8">
                            <header class="web-article-content-header">
-                            <Heading id={method.id} level={2} inReferences>{method.title}</Heading>
+                                <Heading id={method.id} level={2} inReferences
+                                    >{method.title}</Heading
+                                >
                            </header>
                            <div class="flex flex-col gap-2">
                                <!-- eslint-disable-next-line svelte/no-at-html-tags -->
@@ -295,6 +369,7 @@
                        </div>
                    </section>
                {/each}
+            {/each}
        </div>
        <aside
            class="web-references-menu"
@@ -325,13 +400,27 @@
                        </button>
                    </div>
                    <ul class="web-references-menu-list">
-                        {#each data.methods as method}
+                        {#each Object.entries(groupMethodsByGroup(data.methods)) as [group, methods]}
+                            <li class="web-references-menu-group">
+                                {#if group !== ''}
+                                    <h6 class="text-micro text-greyscale-500 mb-2 uppercase">
+                                        {group}
+                                    </h6>
+                                {/if}
+                                <ul class="flex flex-col gap-2">
+                                    {#each sortMethods(methods) as method}
                                        <li class="web-references-menu-item">
                                            <a
                                                href={`#${method.id}`}
                                                class="web-references-menu-link text-caption"
-                                    class:is-selected={method.id === selected}>{method.title}</a
+                                                class:is-selected={method.id === selected}
+                                                use:bindSelectedRef={method.id === selected}
                                            >
+                                                {method.title}
+                                            </a>
+                                        </li>
+                                    {/each}
+                                </ul>
                            </li>
                        {/each}
                    </ul>
@@ -352,4 +441,11 @@
    .web-inline-code {
        translate: 0 0.125rem;
    }
+    .web-references-menu-group {
+        margin-bottom: 1.5rem;
+
+        &:last-child {
+            margin-bottom: 0;
+        }
+    }
 </style>
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -1,9 +1,9 @@
-import dynamicImport from 'vite-plugin-dynamic-import';
-import { sveltekit } from '@sveltejs/kit/vite';
-import { defineConfig } from 'vitest/config';
-import { ViteImageOptimizer } from 'vite-plugin-image-optimizer';
 import { enhancedImages } from '@sveltejs/enhanced-img';
+import { sveltekit } from '@sveltejs/kit/vite';
+import dynamicImport from 'vite-plugin-dynamic-import';
+import { ViteImageOptimizer } from 'vite-plugin-image-optimizer';
 import manifestSRI from 'vite-plugin-manifest-sri';
+import { defineConfig } from 'vitest/config';

 export default defineConfig({
    plugins: [