From 7ea8414d6c218525e877c752f2f54ed32fae87d7 Mon Sep 17 00:00:00 2001
From: Jacob Marshall <me@jhqcat.com>
Date: Wed, 5 Feb 2025 14:01:49 +0000
Subject: [PATCH] docs: write page for `dynamic` function (#503)

---
 .../src/components/Sidebar/sidebarElements.ts | 21 +++-----
 .../core-concepts/multithreading.mdx          | 14 -----
 .../documentation/functions/dynamic.mdx       | 54 +++++++++++++++++++
 .../{hooks => functions}/use-router.mdx       |  0
 4 files changed, 61 insertions(+), 28 deletions(-)
 delete mode 100644 apps/documentation/src/routes/documentation/core-concepts/multithreading.mdx
 create mode 100644 apps/documentation/src/routes/documentation/functions/dynamic.mdx
 rename apps/documentation/src/routes/documentation/{hooks => functions}/use-router.mdx (100%)

diff --git a/apps/documentation/src/components/Sidebar/sidebarElements.ts b/apps/documentation/src/components/Sidebar/sidebarElements.ts
index 8d1722cd..530c80a8 100644
--- a/apps/documentation/src/components/Sidebar/sidebarElements.ts
+++ b/apps/documentation/src/components/Sidebar/sidebarElements.ts
@@ -169,18 +169,6 @@ export const sidebarElements: Array<SidebarElement> = [
       },
     ],
   },
-  {
-    type: 'element',
-    label: 'Core concepts',
-    href: '#focus',
-    children: [
-      {
-        type: 'element',
-        label: 'Multithreading',
-        href: '/documentation/core-concepts/multithreading',
-      },
-    ],
-  },
   { type: 'divider' },
   { type: 'title', label: 'API reference' },
   {
@@ -197,13 +185,18 @@ export const sidebarElements: Array<SidebarElement> = [
   },
   {
     type: 'element',
-    label: 'Hooks',
+    label: 'Functions',
     href: '#focus',
     children: [
+      {
+        type: 'element',
+        label: 'dynamic',
+        href: '/documentation/functions/dynamic',
+      },
       {
         type: 'element',
         label: 'useRouter',
-        href: '/documentation/hooks/use-router',
+        href: '/documentation/functions/use-router',
       },
     ],
   },
diff --git a/apps/documentation/src/routes/documentation/core-concepts/multithreading.mdx b/apps/documentation/src/routes/documentation/core-concepts/multithreading.mdx
deleted file mode 100644
index 437de286..00000000
--- a/apps/documentation/src/routes/documentation/core-concepts/multithreading.mdx
+++ /dev/null
@@ -1,14 +0,0 @@
-import MetaTags from '@/components/MetaTags'
-
-<MetaTags
-  title="Tuono - Multithreading"
-  canonical="https://tuono.dev/documentation/core-concepts/multithreading"
-/>
-
-import Breadcrumbs from '@/components/Breadcrumbs'
-
-<Breadcrumbs breadcrumbs={[{ label: 'Core concepts' }]} />
-
-# Multithreading
-
-TODO
diff --git a/apps/documentation/src/routes/documentation/functions/dynamic.mdx b/apps/documentation/src/routes/documentation/functions/dynamic.mdx
new file mode 100644
index 00000000..d49276f9
--- /dev/null
+++ b/apps/documentation/src/routes/documentation/functions/dynamic.mdx
@@ -0,0 +1,54 @@
+import MetaTags from '@/components/MetaTags'
+
+<MetaTags
+  title="Tuono - dynamic"
+  canonical="https://tuono.dev/documentation/functions/dynamic"
+  description="Lazy load components using the 'dynamic' function"
+/>
+
+import Breadcrumbs from '@/components/Breadcrumbs'
+
+<Breadcrumbs breadcrumbs={[{ label: 'dynamic' }]} />
+
+# dynamic
+
+Tuono supports lazy loading through the `dynamic` function, which uses `Suspense` and `React.lazy` to load components lazily with fallback support.
+
+Lazy loading helps reduce the amount of JavaScript required for the initial page render by deferring the loading of components and libraries until they are needed.
+
+It's most effective when deferring content that isn't initially visible, like a component below the fold or one in a modal.
+
+## Usage
+
+Here is an example using all the exposed options as referenced below.
+
+```typescript jsx
+import { dynamic } from 'tuono'
+
+const LazyComponent = dynamic(() => import('./MyComponent'), {
+  ssr: false,
+  loading: () => <div>Loading...</div>,
+})
+
+function App() {
+  return (
+    <div>
+      <h1>Welcome</h1>
+      <LazyComponent />
+    </div>
+  )
+}
+```
+
+> ⚠️ Note that the first argument must be a function that returns a promise (e.g., `() => import('./MyComponent')`), not a direct call to `import('./MyComponent')`, which would execute immediately instead of lazily loading.
+
+> 💡 It’s good practice to ensure that your fallback component matches the dimensions of the actual component. This helps prevent layout shifts and the ugly resizing of modals as their content loads.
+
+## Options
+
+| Name           | Type                                                                     | Default value | Description                                                                    |
+| -------------- | ------------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------------ |
+| `importFn`     | `() => Promise<React.ComponentType<T> \| ComponentModule<T>>` (Required) | -             | Function to import your component.                                             |
+| `opts`         | `DynamicOptions`                                                         | -             | Optional config object for additional control.                                 |
+| `opts.ssr`     | `boolean`                                                                | `true`        | Whether to enable server-side rendering for the component.                     |
+| `opts.loading` | `React.ComponentType<unknown>`                                           | `null`        | A fallback component to show while the lazy-loaded component is being fetched. |
diff --git a/apps/documentation/src/routes/documentation/hooks/use-router.mdx b/apps/documentation/src/routes/documentation/functions/use-router.mdx
similarity index 100%
rename from apps/documentation/src/routes/documentation/hooks/use-router.mdx
rename to apps/documentation/src/routes/documentation/functions/use-router.mdx