docs: v3 docs structure

docusaurus.config.js

@@ -44,6 +44,10 @@ const config = {
                             label: '1.x',
                             banner: 'none',
                         },
+                        '3.x': {
+                            label: '3.0 Alpha',
+                            banner: 'none',
+                        },
                     },
                 },
                 blog: false,

package.json

@@ -22,6 +22,7 @@
         "@docusaurus/theme-mermaid": "3.4.0",
         "@giscus/react": "^2.4.0",
         "@mdx-js/react": "^3.0.1",
+        "@stackblitz/sdk": "^1.11.0",
         "autoprefixer": "^10.4.13",
         "clsx": "^1.2.1",
         "postcss": "^8.4.21",

src/components/StackBlitzEmbed.tsx

@@ -0,0 +1,26 @@
+import React, { useEffect, useRef } from 'react';
+import sdk from '@stackblitz/sdk';
+
+interface StackBlitzEmbedProps {
+    projectId: string;
+    height?: string;
+}
+
+const StackBlitzEmbed: React.FC<StackBlitzEmbedProps> = ({ projectId, height = '600px' }) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        if (containerRef.current) {
+            sdk.embedProjectId(containerRef.current, projectId, {
+                openFile: 'main.ts',
+                height,
+                view: 'editor',
+                forceEmbedLayout: true,
+            });
+        }
+    }, [projectId, height]);
+
+    return <div ref={containerRef} style={{ width: '100%', height }} />;
+};
+
+export default StackBlitzEmbed;

src/components/StackBlitzGithubEmbed.tsx

@@ -0,0 +1,26 @@
+import React, { useEffect, useRef } from 'react';
+import sdk from '@stackblitz/sdk';
+
+interface StackBlitzGithubEmbedProps {
+    repoPath: string;
+    height?: string;
+}
+
+const StackBlitzGithubEmbed: React.FC<StackBlitzGithubEmbedProps> = ({ repoPath, height = '600px' }) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        if (containerRef.current) {
+            sdk.embedGithubProject(containerRef.current, repoPath, {
+                openFile: 'main.ts',
+                height,
+                view: 'editor',
+                forceEmbedLayout: true,
+            });
+        }
+    }, [repoPath, height]);
+
+    return <div ref={containerRef} style={{ width: '100%', height }} />;
+};
+
+export default StackBlitzGithubEmbed;

versioned_docs/version-3.x/_components/PackageExec.tsx

@@ -0,0 +1,28 @@
+import CodeBlock from '@theme/CodeBlock';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+interface Props {
+    command: string;
+}
+
+const pkgManagers = [
+    { name: 'npm', command: 'npx' },
+    { name: 'pnpm', command: 'pnpm' },
+    { name: 'bun', command: 'bunx' },
+    { name: 'yarn', command: 'npx' },
+];
+
+const PackageInstall = ({ command }: Props) => {
+    return (
+        <Tabs>
+            {pkgManagers.map((pkg) => (
+                <TabItem key={pkg.name} value={pkg.name} label={pkg.name}>
+                    <CodeBlock language="bash">{`${pkg.command} ${command}`}</CodeBlock>
+                </TabItem>
+            ))}
+        </Tabs>
+    );
+};
+
+export default PackageInstall;

versioned_docs/version-3.x/_components/PackageInstall.tsx

@@ -0,0 +1,33 @@
+import CodeBlock from '@theme/CodeBlock';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+interface Props {
+    devDependencies: string[];
+    dependencies: string[];
+}
+
+const pkgManagers = [
+    { name: 'npm', command: 'npm install', dev: '--save-dev' },
+    { name: 'pnpm', command: 'pnpm add', dev: '--save-dev' },
+    { name: 'bun', command: 'bun add', dev: '--dev' },
+    { name: 'yarn', command: 'yarn add', dev: '--dev' },
+];
+
+const PackageInstall = ({ devDependencies, dependencies }: Props) => {
+    return (
+        <Tabs>
+            {pkgManagers.map((pkg) => (
+                <TabItem key={pkg.name} value={pkg.name} label={pkg.name}>
+                    <CodeBlock language="bash">
+                        {`${devDependencies?.length ? `${pkg.command} ${pkg.dev} ${devDependencies.join(' ')}\n` : ''}${
+                            dependencies?.length ? `${pkg.command} ${dependencies.join(' ')}` : ''
+                        }`}
+                    </CodeBlock>
+                </TabItem>
+            ))}
+        </Tabs>
+    );
+};
+
+export default PackageInstall;

versioned_docs/version-3.x/_components/_zmodel-starter.md

@@ -0,0 +1,23 @@
+  ```zmodel
+  datasource db {
+    provider = 'sqlite'
+    url = "file:./dev.db"
+  }
+
+  model User {
+    id       String @id @default(cuid())
+    email    String @unique @email @length(6, 32)
+    posts    Post[]
+  }
+
+  model Post {
+    id        String   @id @default(cuid())
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+    title     String   @length(1, 256)
+    content   String
+    published Boolean  @default(false)
+    author    User     @relation(fields: [authorId], references: [id])
+    authorId  String
+  }
+  ```

versioned_docs/version-3.x/faq.md

@@ -0,0 +1,9 @@
+---
+description: ZenStack FAQ.
+
+slug: /faq
+sidebar_label: FAQ
+sidebar_position: 100
+---
+
+# 🙋🏻 FAQ

versioned_docs/version-3.x/migration/_category_.yml

@@ -0,0 +1,7 @@
+position: 3
+label: Migration
+collapsible: true
+collapsed: true
+link:
+    type: generated-index
+    title: Migration

versioned_docs/version-3.x/migration/introduction.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 1
+description: Introduction to ZenStack migration
+---
+
+# Introduction

versioned_docs/version-3.x/orm/_category_.yml

@@ -0,0 +1,7 @@
+position: 2
+label: ORM
+collapsible: true
+collapsed: true
+link:
+    type: generated-index
+    title: ORM

versioned_docs/version-3.x/orm/access-control/_category_.yml

@@ -0,0 +1,4 @@
+position: 8
+label: Access Control
+collapsible: true
+collapsed: true

versioned_docs/version-3.x/orm/access-control/introduction.md

@@ -0,0 +1,3 @@
+# Introduction
+
+Coming soon 🚧

versioned_docs/version-3.x/orm/api/_category_.yml

@@ -0,0 +1,7 @@
+position: 6
+label: ORM API
+collapsible: true
+collapsed: true
+link:
+    type: generated-index
+    title: ORM API

versioned_docs/version-3.x/orm/api/aggregate.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 6
+description: Aggregate API
+---
+
+# Aggregate

versioned_docs/version-3.x/orm/api/count.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 5
+description: Count API
+---
+
+# Count

versioned_docs/version-3.x/orm/api/create.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 2
+description: Create API
+---
+
+# Create

versioned_docs/version-3.x/orm/api/delete.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 4
+description: Delete API
+---
+
+# Delete

versioned_docs/version-3.x/orm/api/find.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 1
+description: Find API
+---
+
+# Find

versioned_docs/version-3.x/orm/api/transaction.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 7
+description: Transaction API
+---
+
+# Transaction

versioned_docs/version-3.x/orm/api/update.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 3
+description: Update API
+---
+
+# Update

versioned_docs/version-3.x/orm/cli.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 4
+description: Using the CLI
+---
+
+# Using the CLI

versioned_docs/version-3.x/orm/computed-fields.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 10
+description: Computed fields in ZModel
+---
+
+# Computed Fields
+

versioned_docs/version-3.x/orm/database-client.mdx

@@ -0,0 +1,65 @@
+---
+sidebar_position: 5
+description: Creating a database client
+---
+
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+import PackageInstall from '../_components/PackageInstall';
+
+# Database Client
+
+The `zen generate` command compiles the ZModel schema into TypeScript code, which we can in turn use to initialize a type-safe database client. ZenStack uses Kysely to handle the low-level database operations, so the client is initialize with a Kysely dialect - an object that encapsulates database details.
+
+The samples below only shows creating a client using SQLite (via [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) and PostgreSQL (via [node-postgres](https://github.com/brianc/node-postgres)), however you can also use any other Kysely dialects.
+
+<Tabs>
+
+<TabItem value="sqlite" label={`SQLite`}>
+
+<PackageInstall dependencies={["better-sqlite3"]} devDependencies={['@types/better-sqlite3']} />
+
+```ts title='db.ts'
+import { ZenStackClient } from '@zenstackhq/runtime';
+import { SqliteDialect } from 'kysely';
+import SQLite from 'better-sqlite3';
+import { schema } from '@/zenstack/schema';
+
+export const db = new ZenStackClient(schema, {
+    dialect: new SqliteDialect({
+        database: new SQLite(':memory:'),
+    }),
+});
+```
+</TabItem>
+
+<TabItem value="postgres" label={`PostgreSQL`}>
+
+<PackageInstall dependencies={["pg"]} devDependencies={['@types/pg']} />
+
+```ts title='db.ts'
+import { ZenStackClient } from '@zenstackhq/runtime';
+import { schema } from '@/zenstack/schema';
+import { PostgresDialect } from 'kysely';
+import { Pool } from 'pg';
+
+export const db = new ZenStackClient(schema, {
+    dialect: new PostgresDialect({
+        pool: new Pool({
+            connectionString: process.env.DATABASE_URL,
+        }),
+    }),
+});
+```
+</TabItem>
+
+</Tabs>
+
+The created `db` object has the full ORM API inferred from the type of the `schema` parameter. When necessary, you can also explicitly get the inferred client type like:
+
+```ts
+import type { ClientContract } from '@zenstackhq/runtime';
+import type { SchemaType } from '@/zenstack/schema';
+
+export type DbClient = ClientContract<SchemaType>;
+```