wip docs, add extensions api

Author: punyflash

docs/.vitepress/config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from 'vitepress'
+import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -13,17 +14,31 @@ export default defineConfig({
         ],
 
         sidebar: [
+            { text: 'Introduction', link: '/introduction', },
             {
-                text: 'Examples',
+                text: 'Installation',
                 items: [
-                    { text: 'Markdown Examples', link: '/markdown-examples' },
-                    { text: 'Runtime API Examples', link: '/api-examples' }
+                    { text: 'Server', link: '/installation/server' },
+                    { text: 'Client', link: '/installation/client' },
+                ]
+            },
+            {
+                text: 'Usage',
+                items: [
+                    { text: 'Navigation', link: '/usage/navigation' },
+                    { text: 'Extensions API', link: '/usage/extensions' },
                 ]
             }
         ],
 
         socialLinks: [
-            { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
+            { icon: 'github', link: 'https://github.com/westacks/vortex' }
         ]
+    },
+    markdown: {
+        config(md) {
+            // @ts-ignore
+            md.use(tabsMarkdownPlugin)
+        }
     }
 })

docs/.vitepress/theme/index.ts

@@ -2,6 +2,7 @@
 import { h } from 'vue'
 import type { Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
+import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
 import './style.css'
 
 export default {
@@ -12,6 +13,6 @@ export default {
         })
     },
     enhanceApp({ app, router, siteData }) {
-        // ...
+        enhanceAppWithTabs(app)
     }
 } satisfies Theme

docs/api-examples.md docs/examples.md

@@ -4,22 +4,24 @@ layout: home
 
 hero:
   name: "Vortex"
-  text: "Server-based routing for SPA"
-  tagline: My great project tagline
+  text: "Server-side routing for SPA"
+  tagline: Low-level API, High-level Efficiency
   actions:
     - theme: brand
-      text: Markdown Examples
-      link: /markdown-examples
+      text: Learn More
+      link: /introduction
     - theme: alt
-      text: API Examples
-      link: /api-examples
+      text: Examples
+      link: /examples
 
 features:
-  - title: Feature A
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature B
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature C
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+  - title: Truly Framework-Agnostic
+    details: Works seamlessly with any front-end framework.
+
+  - title: SSR support
+    details: Provides simple API to pre-render pages on the server.
+
+  - title: Low-Level API Access
+    details: Offers full control and customization of your application.
 ---
 

docs/index.md

@@ -0,0 +1,156 @@
+# Client-Side Installation
+
+Once you have prepared [server-side](/installation/server.md) adapter, you will need to setup your client-side framework.
+
+## Install Dependencies
+
+First, you need to install Vortex client:
+
+::: tabs
+
+== npm
+```shell
+npm install @westacks/vortex
+```
+== yarn
+```shell
+yarn add @westacks/vortex
+```
+== pnpm
+```shell
+pnpm add @westacks/vortex
+```
+== bun
+```shell
+bun add @westacks/vortex
+```
+:::
+
+## Initialize Application
+
+Next, initialize Vortex client and create your application root:
+
+::: tabs
+== Svelte
+**_app.js_**
+
+Create application root and subscribe to page changes.
+```js
+import { createVortex, subscribe } from '@westacks/vortex'
+import { props } from './setup'
+import App from './App.svelte'
+
+createVortex(async (target, page, hydrate) => {
+    const app = new App({ target, props: await props(page), hydrate })
+
+    subscribe(async (page) => app.$set(await props(page)))
+})
+```
+**_setup.js_**
+
+You will need to resolve page component, using your bundler's API. We will provide example for Vite as most popular, but code below may differ depending on bundler you are using.
+```js
+export const props = async (page) => {
+    const pages = import.meta.glob('./pages/**/*.svelte')
+    const component = (await pages[`./pages/${page.component}.svelte`])?.default
+
+    return { component, props: page.props ?? {} }
+}
+```
+**_App.svelte_**
+```svelte
+<script>
+    export let component, props
+</script>
+
+{#if component}
+    <component this={component} {...props} />
+{/if}
+```
+== Solid
+TODO
+== Vue
+TODO
+== React
+TODO
+== Angular
+TODO
+:::
+
+After that you may start creating components in `./pages` directory. Each time vortex initiates page change, it will resolve corresponding component, provide it with props and render it.
+
+You are not glued to use app structure provided above, so you may modify it as you wish for your use-cases (layouts, loading states, etc).
+
+## Server-Side Rendering
+
+Optionally, you can setup bundle for server-side rendering (SSR), which can be utilized by your server to pre-render pages of your application:
+
+::: tabs
+== Svelte
+**_ssr.js_**
+```js
+import { createVortexServer } from '@westacks/vortex/server'
+import { props } from './setup'
+import App from './App.svelte'
+
+createVortexServer(async (page) => {
+    const {html, head} = App.render(await props(page))
+
+    // You should return data type, that compatible with your server API
+    return {body: html, head}
+})
+
+```
+== Solid
+TODO
+== Vue
+TODO
+== React
+TODO
+== Angular
+TODO
+:::
+
+### Using SSR bundle
+
+SSR bundle takes page data as input and returns pre-rendered HTML strings based on your client-side logic. You will need a JavaScript runtime configured on your server to use it:
+
+#### Server Mode
+
+::: tabs
+== Node.js
+```shell
+node ./dist/ssr.js
+```
+== Deno
+```shell
+deno run --allow-net ./dist/ssr.js
+```
+== Bun
+```shell
+bun run --bun ./dist/ssr.js
+```
+:::
+
+```shell
+curl -X POST http://localhost:13714/render \
+    -H 'Content-Type: application/json' \
+    -d '{"component":"Page","props":{},"url": "/","version":"..."}'
+```
+
+#### CLI Mode
+
+::: tabs
+== Node.js
+```shell
+node ./dist/ssr.js '{"component":"Page","props":{},"url": "/","version":"..."}'
+```
+== Deno
+```shell
+deno run ./dist/ssr.js '{"component":"Page","props":{},"url": "/","version":"..."}'
+```
+== Bun
+```shell
+bun run --bun ./dist/ssr.js '{"component":"Page","props":{},"url": "/","version":"..."}'
+```
+:::

docs/installation/client.md

@@ -0,0 +1,71 @@
+# Extensions API
+
+Vortex allows you easily extend your navigation logic on runtime. Extensions use [axios interceptors](https://axios-http.com/docs/interceptors) to "glue in" between your requests and responses.
+
+## Installing extensions
+```typescript
+import { extend, type VortexExtension } from '@westacks/vortex'
+
+const extension: VortexExtension = ({ request, response }) => ({
+    request: request.use(
+        function (request) {
+            // Modify request config, e.g. add headers, any custom logic
+        },
+        function (error) {
+            // Handle error
+        }
+    ),
+    response: response.use(
+        function (response) {
+            // Handle response
+        },
+        function (error) {
+            // Handle error
+        }
+    )
+})
+
+// Add extension
+const dispose = extend(extension)
+
+// You may remove extensions at any time you want by calling destructor function
+dispose()
+```
+
+## Examples
+
+### NProgress
+Adds simple progress indicator on top of the page
+```typescript
+import type { VortexExtension } from '@westacks/vortex'
+import NProgress from 'nprogress'
+
+export default ({ request, response }) => ({
+    request:request.use(
+        function (config) {
+            NProgress.start();
+            return config;
+        },
+        function (error) {
+            NProgress.done();
+            return Promise.reject(error);
+        }
+    ),
+    response: response.use(
+        function (response) {
+            NProgress.done();
+            return response;
+        },
+        function (error) {
+            NProgress.done();
+            return Promise.reject(error);
+        }
+    )
+}) as VortexExtension
+```
+
+## Community extensions
+
+Feel free to share your extensions by creating Pull Request on [GitHub](https://github.com/westacks/vortex)
+
+- _No one done anything yet, we've just released._