create-middag-ui 0.4.1 → 0.5.0

package/cli.js

@@ -28,8 +28,10 @@ import {
   scaffoldPackageJson,
   scaffoldTsconfig,
   scaffoldViteConfig,
+  scaffoldIndexHtml,
   scaffoldDemoFiles,
-  scaffoldMockFiles,
+  scaffoldPageExamples,
+  scaffoldAppFiles,
 } from "./lib/scaffold.js";
 import { runNpmInstall } from "./lib/install.js";
 import { log, success, heading, blank, info } from "./lib/ui.js";
@@ -112,6 +114,7 @@ heading(5, TOTAL_STEPS, "Scaffolding config files");
 scaffoldPackageJson(targetDir, host, cwd);
 scaffoldTsconfig(targetDir);
 scaffoldViteConfig(targetDir, host);
+scaffoldIndexHtml(targetDir);
 
 // ── Step 6: Scaffold ~/.npmrc (GitHub path only) ─────────────────────────
 
@@ -130,11 +133,12 @@ heading(7, TOTAL_STEPS, "Creating demo files");
 
 scaffoldDemoFiles(targetDir);
 
-// ── Step 8: Scaffold mock files ──────────────────────────────────────────
+// ── Step 8: Scaffold app files + page examples ─────────────────────────
 
-heading(8, TOTAL_STEPS, "Creating mock environment");
+heading(8, TOTAL_STEPS, "Creating app and page examples");
 
-scaffoldMockFiles(targetDir);
+scaffoldAppFiles(targetDir);
+scaffoldPageExamples(targetDir);
 
 // ── Step 9: npm install ──────────────────────────────────────────────────
 
@@ -156,21 +160,22 @@ if (installOk) {
   log(`MIDDAG React UI ready in ${dirName}/ (${elapsed}s)\n`);
   console.log("  Start developing:");
   console.log(`    cd ${dirName}`);
-  console.log(`    npm run dev:mock        \u2192 mock server at http://localhost:${host.port}`);
+  console.log(`    npm run dev              \u2192 dev server at http://localhost:${host.port}`);
 } else {
   log(`Scaffold complete in ${dirName}/ (${elapsed}s) \u2014 install failed\n`);
   console.log("  To retry install:");
   console.log(`    cd ${dirName}`);
   console.log("    npm install");
-  console.log(`    npm run dev:mock        \u2192 mock server at http://localhost:${host.port}`);
+  console.log(`    npm run dev              \u2192 dev server at http://localhost:${host.port}`);
 }
 
 blank();
 console.log("  Your scaffold includes:");
+console.log("    src/pages/dashboard.ts       \u2190 starter: metric_card + dense_table");
+console.log("    src/pages/connectors.ts      \u2190 intermediate: card_grid + status_strip");
+console.log("    src/pages/settings.ts        \u2190 advanced: tabbed_panel + form_panel");
 console.log("    src/blocks/hello-block.tsx    \u2190 custom block example (rename me!)");
-console.log("    src/components/greeting.tsx   \u2190 standalone component (rename me!)");
-console.log("    src/contracts.ts              \u2190 PageContract type re-export");
-console.log("    mock/hello-contract.ts        \u2190 example PageContract with data");
+console.log("    src/app.tsx                   \u2190 hash-based page router");
 
 blank();
 console.log(`  Integrate with your ${host.name} plugin:`);

package/lib/scaffold.js

@@ -1,7 +1,9 @@
 /**
  * scaffold.js — File creation for all scaffolded files.
  *
- * Creates directory structure, config files, demo files, and mock files.
+ * Creates directory structure, config files, page examples, app entry,
+ * and Inertia mock adapters. Everything lives under src/.
+ *
  * Every I/O operation is wrapped with error handling.
  */
 
@@ -83,10 +85,8 @@ export function scaffoldPackageJson(targetDir, host, cwd) {
     private: true,
     type: "module",
     scripts: {
-      dev: "vite --config vite.mock.config.ts",
-      "dev:mock": "vite --config vite.mock.config.ts",
+      dev: "vite",
       build: "vite build",
-      "build:mock": "vite build --config vite.mock.config.ts",
       typecheck: "tsc --noEmit",
       lint: "eslint .",
       "lint:fix": "eslint . --fix",
@@ -128,42 +128,89 @@ export function scaffoldTsconfig(targetDir) {
       noUnusedLocals: true,
       noUnusedParameters: true,
       skipLibCheck: true,
-      paths: { "@/*": ["./src/*"], "@mock/*": ["./mock/*"] },
+      paths: { "@/*": ["./src/*"] },
       baseUrl: ".",
     },
-    include: ["src", "mock"],
+    include: ["src"],
   };
 
   writeFile(filePath, JSON.stringify(tsconfig, null, 2) + "\n", "tsconfig.json");
 }
 
 /**
- * Scaffold vite.mock.config.ts.
+ * Scaffold vite.config.ts.
  */
 export function scaffoldViteConfig(targetDir, host) {
-  const filePath = join(targetDir, "vite.mock.config.ts");
-  if (skipIfExists(filePath, "vite.mock.config.ts")) return;
+  const filePath = join(targetDir, "vite.config.ts");
+  if (skipIfExists(filePath, "vite.config.ts")) return;
 
-  const content = `import { defineConfig } from "vite";
+  const content = `/**
+ * Vite config \u2014 used by \`npm run dev\` and \`npm run build\`.
+ *
+ * The Inertia aliases below redirect @inertiajs/* imports to local
+ * mock adapters so the dev server works standalone (no Moodle/WP).
+ * In production, the real @inertiajs packages handle routing and
+ * page resolution \u2014 these aliases have no effect.
+ */
+import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 import { resolve } from "path";
 
 export default defineConfig({
   plugins: [react()],
-  root: "mock",
   server: { port: ${host.port} },
   resolve: {
     alias: {
+      // Path alias \u2014 import from "@/components/..." resolves to src/
       "@/": resolve(__dirname, "src") + "/",
-      "@mock/": resolve(__dirname, "mock") + "/",
-      "@inertiajs/react": resolve(__dirname, "mock/adapters/inertia-react.ts"),
-      "@inertiajs/core": resolve(__dirname, "mock/adapters/inertia-core.ts"),
+      // Mock Inertia for standalone dev \u2014 see src/adapters/ for implementation
+      "@inertiajs/react": resolve(__dirname, "src/adapters/inertia-react.ts"),
+      "@inertiajs/core": resolve(__dirname, "src/adapters/inertia-core.ts"),
     },
   },
 });
 `;
 
-  writeFile(filePath, content, "vite.mock.config.ts");
+  writeFile(filePath, content, "vite.config.ts");
+}
+
+/**
+ * Scaffold index.html at project root.
+ */
+export function scaffoldIndexHtml(targetDir) {
+  const filePath = join(targetDir, "index.html");
+  if (skipIfExists(filePath, "index.html")) return;
+
+  writeFile(
+    filePath,
+    `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>MIDDAG React UI</title>
+  </head>
+  <body>
+    <!--
+      DEV ONLY \u2014 This file is used by \`npm run dev\` (Vite dev server).
+      In production, your host platform (Moodle/WordPress) serves its own
+      HTML and loads the UI via Inertia.js. This file is never deployed.
+
+      middag-root  \u2014 Required class for MIDDAG CSS tokens to apply.
+      middag-portals \u2014 Container for floating UI (modals, dropdowns, toasts).
+
+      To try a theme, add its class to #root:
+        class="middag-root theme-ocean"
+      See src/theme.css for available themes and how to create your own.
+    -->
+    <div id="root" class="middag-root"></div>
+    <div id="middag-portals" class="middag-root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`,
+    "index.html",
+  );
 }
 
 // ── Demo files in src/ ──────────────────────────────────────────────────
@@ -270,70 +317,197 @@ export type { PageContract, BlockDescriptor, SharedProps } from "@middag-io/reac
       "src/contracts.ts",
     );
   }
+
+  // src/theme.css
+  const themePath = join(targetDir, "src", "theme.css");
+  if (!skipIfExists(themePath, "src/theme.css")) {
+    writeFile(
+      themePath,
+      `/**
+ * Theme customization \u2014 override MIDDAG design tokens here.
+ *
+ * @middag-io/react uses CSS custom properties for all visual tokens.
+ * Override them in :root for global changes, or scope them to a class
+ * for switchable themes.
+ *
+ * All colors use OKLCH color space: oklch(lightness chroma hue)
+ * Visual picker: https://oklch.com
+ *
+ * Import order matters \u2014 this file is loaded AFTER @middag-io/react/style.css
+ * so overrides here take precedence.
+ */
+
+/* \u2500\u2500 Global token overrides \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+ *
+ * Uncomment to change the default appearance globally.
+ * Every MIDDAG component reads from these tokens.
+ */
+
+/*
+:root {
+  --primary: oklch(0.45 0.2 260);
+  --primary-foreground: oklch(0.98 0 0);
+  --accent: oklch(0.95 0.02 260);
+  --accent-foreground: oklch(0.21 0.014 286);
+  --radius: 0.5rem;
 }
+*/
 
-// ── Mock files ──────────────────────────────────────────────────────────
+/* \u2500\u2500 Example theme: Ocean \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+ *
+ * A complete theme override scoped to a CSS class.
+ * Apply with: <div id="root" class="middag-root theme-ocean">
+ *
+ * This is how MIDDAG themes work \u2014 redefine tokens in a scope.
+ * The scoped class overrides :root values for everything inside it.
+ */
 
-/**
- * Scaffold mock/ files (hello-contract, main.tsx, index.html, tailwind.css).
+.theme-ocean {
+  /* Brand */
+  --primary: oklch(0.45 0.18 230);
+  --primary-foreground: oklch(0.98 0 0);
+  --primary-subtle: oklch(0.92 0.04 230);
+  --primary-muted: oklch(0.85 0.06 230);
+
+  /* Accents */
+  --accent: oklch(0.94 0.03 230);
+  --accent-foreground: oklch(0.2 0.02 230);
+  --info: oklch(0.55 0.14 200);
+  --info-foreground: oklch(0.98 0 0);
+
+  /* Sidebar */
+  --sidebar: oklch(0.15 0.03 230);
+  --sidebar-foreground: oklch(0.75 0.02 230);
+  --sidebar-primary: oklch(0.55 0.15 230);
+  --sidebar-primary-foreground: oklch(0.98 0 0);
+  --sidebar-accent: oklch(0.22 0.04 230);
+  --sidebar-accent-foreground: oklch(0.9 0.005 230);
+  --sidebar-hover: oklch(0.19 0.025 230);
+  --sidebar-border: oklch(0.25 0.03 230);
+}
+
+/* \u2500\u2500 Custom project styles \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+ *
+ * Add project-specific styles below. These can target MIDDAG components
+ * or your own custom elements.
+ *
+ * Available token groups:
+ *   Colors:  var(--primary), var(--foreground), var(--background),
+ *            var(--muted), var(--card), var(--border), var(--destructive),
+ *            var(--success), var(--warning), var(--info), var(--accent)
+ *   Spacing: var(--space-1) through var(--space-20)  (4px grid)
+ *   Radius:  var(--radius-sm|md|lg|xl|2xl|full)
+ *   Shadows: var(--shadow-xs|sm|md|lg|xl|2xl)
+ *   Motion:  var(--duration-fast|normal|moderate|slow)
  */
-export function scaffoldMockFiles(targetDir) {
-  const mockDir = join(targetDir, "mock");
-  ensureDir(mockDir);
 
-  // mock/hello-contract.ts
-  const helloContractPath = join(mockDir, "hello-contract.ts");
-  if (!skipIfExists(helloContractPath, "mock/hello-contract.ts")) {
-    writeFile(
-      helloContractPath,
-      `import type { PageContract } from "@middag-io/react";
+/* Example: branded page header */
+/*
+.my-page-header {
+  background: linear-gradient(135deg, var(--primary) 0%, var(--info) 100%);
+  color: var(--primary-foreground);
+  padding: var(--space-6) var(--space-8);
+  border-radius: var(--radius-lg);
+}
+*/
+`,
+      "src/theme.css",
+    );
+  }
+}
+
+// ── Page contract examples ──────────────────────────────────────────────
 
 /**
- * Hello World contract \u2014 a minimal PageContract to verify your setup.
+ * Scaffold 3 progressive page contract examples in src/pages/.
+ */
+export function scaffoldPageExamples(targetDir) {
+  ensureDir(join(targetDir, "src", "pages"));
+
+  // ── Starter: dashboard.ts (metric_card + dense_table) ───────────────
+  const dashboardPath = join(targetDir, "src", "pages", "dashboard.ts");
+  if (!skipIfExists(dashboardPath, "src/pages/dashboard.ts")) {
+    writeFile(
+      dashboardPath,
+      `/**
+ * Dashboard page contract \u2014 STARTER example.
+ *
+ * Demonstrates the "dashboard" layout with two block types:
+ *   - metric_card (KPI indicators in the metrics region)
+ *   - dense_table (data table in the content region)
  *
- * This is what your backend will send via Inertia.
- * Replace this with real data from your server.
+ * Layout regions used: metrics, content
  */
-export const helloContract: PageContract = {
+import type { PageContract } from "@middag-io/react";
+
+export const dashboardContract: PageContract = {
   version: "1",
   shell: "product",
   page: {
-    key: "hello",
-    title: "Hello MIDDAG",
-    breadcrumbs: [
-      { label: "Home", href: "/" },
-      { label: "Hello", href: "/hello" },
-    ],
+    key: "dashboard",
+    title: "Dashboard",
+    breadcrumbs: [{ label: "Home", href: "#/" }],
   },
   layout: {
-    template: "stack",
+    template: "dashboard",
     regions: {
-      content: [
+      metrics: [
+        {
+          key: "total_users",
+          type: "metric_card",
+          data: {
+            label: "Total Users",
+            value: "1,284",
+            delta: "+12%",
+            deltaDirection: "positive",
+            icon: "users",
+          },
+        },
         {
-          key: "welcome_metrics",
+          key: "active_sessions",
           type: "metric_card",
           data: {
-            title: "Setup Complete",
-            value: "1",
-            subtitle: "@middag-io/react is working",
+            label: "Active Sessions",
+            value: "342",
+            delta: "+5%",
+            deltaDirection: "positive",
+            icon: "activity",
           },
         },
         {
-          key: "hello_table",
+          key: "completion_rate",
+          type: "metric_card",
+          data: {
+            label: "Completion Rate",
+            value: "87%",
+            delta: "-2%",
+            deltaDirection: "negative",
+            icon: "chart-line",
+          },
+        },
+      ],
+      content: [
+        {
+          key: "recent_activity",
           type: "dense_table",
+          title: "Recent Activity",
           data: {
-            title: "Example Data",
             columns: [
-              { key: "id", label: "ID", sortable: true },
-              { key: "name", label: "Name", sortable: true },
-              { key: "status", label: "Status" },
+              { key: "user", label: "User", sortable: true },
+              { key: "action", label: "Action" },
+              { key: "date", label: "Date", sortable: true },
+              { key: "status", label: "Status", variant: "status" },
             ],
             rows: [
-              { id: 1, name: "First item", status: "Active" },
-              { id: 2, name: "Second item", status: "Draft" },
-              { id: 3, name: "Third item", status: "Active" },
+              { id: 1, user: "Alice Johnson", action: "Completed module", date: "2024-01-15", status: { label: "Complete", appearance: "success" } },
+              { id: 2, user: "Bob Smith", action: "Started course", date: "2024-01-15", status: { label: "In Progress", appearance: "info" } },
+              { id: 3, user: "Carol Davis", action: "Failed quiz", date: "2024-01-14", status: { label: "Failed", appearance: "danger" } },
+              { id: 4, user: "Dave Wilson", action: "Enrolled", date: "2024-01-14", status: { label: "New", appearance: "neutral" } },
+              { id: 5, user: "Eve Brown", action: "Completed course", date: "2024-01-13", status: { label: "Complete", appearance: "success" } },
             ],
-            pagination: { page: 1, totalPages: 1, perPage: 10, totalRows: 3 },
+            pagination: { page: 1, perPage: 10, total: 5, lastPage: 1 },
+            sort: { column: "date", direction: "desc" },
+            filters: { available: [], applied: {} },
           },
         },
       ],
@@ -341,91 +515,425 @@ export const helloContract: PageContract = {
   },
 };
 `,
-      "mock/hello-contract.ts",
+      "src/pages/dashboard.ts",
     );
   }
 
-  // mock/main.tsx
-  const mainPath = join(mockDir, "main.tsx");
-  if (!skipIfExists(mainPath, "mock/main.tsx")) {
+  // ── Intermediate: connectors.ts (card_grid + status_strip + detail_panel)
+  const connectorsPath = join(targetDir, "src", "pages", "connectors.ts");
+  if (!skipIfExists(connectorsPath, "src/pages/connectors.ts")) {
+    writeFile(
+      connectorsPath,
+      `/**
+ * Connectors page contract \u2014 INTERMEDIATE example.
+ *
+ * Demonstrates the "split" layout with three block types:
+ *   - card_grid (connector cards in the main region)
+ *   - status_strip (health indicators in the aside)
+ *   - detail_panel (metadata in the aside)
+ *
+ * Layout regions used: main, aside
+ */
+import type { PageContract } from "@middag-io/react";
+
+export const connectorsContract: PageContract = {
+  version: "1",
+  shell: "product",
+  page: {
+    key: "connectors",
+    title: "Connectors",
+    breadcrumbs: [
+      { label: "Home", href: "#/" },
+      { label: "Connectors" },
+    ],
+    actions: [
+      { id: "add", label: "Add Connector", intent: "primary", icon: "plus" },
+    ],
+  },
+  layout: {
+    template: "split",
+    regions: {
+      main: [
+        {
+          key: "connector_grid",
+          type: "card_grid",
+          title: "Available Connectors",
+          data: {
+            variant: "connector",
+            columns: [
+              { key: "name", label: "Name" },
+              { key: "type", label: "Type" },
+              { key: "status", label: "Status", kind: "status" },
+            ],
+            rows: [
+              { id: 1, name: "Moodle LMS", type: "LMS", status: "Active", icon: "graduation-cap", href: "#/connectors" },
+              { id: 2, name: "Google Workspace", type: "SSO", status: "Active", icon: "shield", href: "#/connectors" },
+              { id: 3, name: "Stripe", type: "Payment", status: "Inactive", icon: "credit-card", href: "#/connectors" },
+              { id: 4, name: "Mailchimp", type: "Email", status: "Active", icon: "mail", href: "#/connectors" },
+            ],
+          },
+        },
+      ],
+      aside: [
+        {
+          key: "connector_health",
+          type: "status_strip",
+          title: "Health Overview",
+          data: {
+            score: 75,
+            tone: "success",
+            items: [
+              { key: "uptime", label: "Uptime", value: "99.9%", appearance: "success" },
+              { key: "sync", label: "Last Sync", value: "2 min ago", appearance: "success" },
+              { key: "errors", label: "Errors (24h)", value: "3", appearance: "warning" },
+              { key: "queue", label: "Queue", value: "0", appearance: "success" },
+            ],
+          },
+        },
+        {
+          key: "connector_detail",
+          type: "detail_panel",
+          title: "Selected Connector",
+          data: {
+            sections: [
+              {
+                id: "overview",
+                title: "Overview",
+                fields: [
+                  { key: "provider", label: "Provider", value: "Moodle LMS" },
+                  { key: "version", label: "API Version", value: "4.3.2" },
+                  { key: "connected", label: "Connected Since", value: "2024-01-01", kind: "timestamp" },
+                  { key: "status", label: "Status", value: "Active", kind: "status" },
+                  { key: "endpoint", label: "Endpoint", value: "https://moodle.example.com/webservice/rest", kind: "code", copyable: true },
+                ],
+              },
+            ],
+          },
+        },
+      ],
+    },
+  },
+};
+`,
+      "src/pages/connectors.ts",
+    );
+  }
+
+  // ── Advanced: settings.ts (tabbed_panel + form_panel + link_list) ────
+  const settingsPath = join(targetDir, "src", "pages", "settings.ts");
+  if (!skipIfExists(settingsPath, "src/pages/settings.ts")) {
+    writeFile(
+      settingsPath,
+      `/**
+ * Settings page contract \u2014 ADVANCED example.
+ *
+ * Demonstrates the "stack" layout with nested block types:
+ *   - tabbed_panel (tabs that contain other blocks)
+ *   - form_panel (schema-driven form inside a tab)
+ *   - link_list (navigation links inside a tab)
+ *
+ * Layout regions used: content
+ */
+import type { PageContract } from "@middag-io/react";
+
+export const settingsContract: PageContract = {
+  version: "1",
+  shell: "product",
+  page: {
+    key: "settings",
+    title: "Settings",
+    breadcrumbs: [
+      { label: "Home", href: "#/" },
+      { label: "Settings" },
+    ],
+  },
+  layout: {
+    template: "stack",
+    regions: {
+      content: [
+        {
+          key: "settings_tabs",
+          type: "tabbed_panel",
+          data: {
+            defaultTab: "general",
+            tabs: [
+              {
+                key: "general",
+                label: "General",
+                icon: "settings",
+                blocks: [
+                  {
+                    key: "general_form",
+                    type: "form_panel",
+                    data: {
+                      action: "/api/settings/general",
+                      method: "put",
+                      schema: [
+                        {
+                          kind: "section",
+                          id: "site",
+                          label: "Site Settings",
+                          children: [
+                            {
+                              kind: "field",
+                              key: "site_name",
+                              component: "text",
+                              props: { label: "Site Name", placeholder: "My Platform", required: true },
+                            },
+                            {
+                              kind: "field",
+                              key: "site_url",
+                              component: "url",
+                              props: { label: "Site URL", placeholder: "https://example.com" },
+                            },
+                            {
+                              kind: "field",
+                              key: "timezone",
+                              component: "select",
+                              props: {
+                                label: "Timezone",
+                                options: [
+                                  { value: "UTC", label: "UTC" },
+                                  { value: "America/Sao_Paulo", label: "S\\u00e3o Paulo (BRT)" },
+                                  { value: "America/New_York", label: "New York (EST)" },
+                                  { value: "Europe/London", label: "London (GMT)" },
+                                ],
+                              },
+                            },
+                          ],
+                        },
+                        {
+                          kind: "section",
+                          id: "features",
+                          label: "Features",
+                          children: [
+                            {
+                              kind: "field",
+                              key: "enable_notifications",
+                              component: "switch",
+                              props: { label: "Enable Notifications", helpText: "Send email notifications for important events" },
+                            },
+                            {
+                              kind: "field",
+                              key: "enable_analytics",
+                              component: "switch",
+                              props: { label: "Enable Analytics", helpText: "Track user activity and generate reports" },
+                            },
+                            {
+                              kind: "field",
+                              key: "maintenance_mode",
+                              component: "switch",
+                              props: { label: "Maintenance Mode", helpText: "Show maintenance page to non-admin users" },
+                            },
+                          ],
+                        },
+                      ],
+                      values: {
+                        site_name: "My Platform",
+                        site_url: "https://example.com",
+                        timezone: "UTC",
+                        enable_notifications: true,
+                        enable_analytics: true,
+                        maintenance_mode: false,
+                      },
+                      errors: {},
+                      meta: { submitLabel: "Save Changes", cancelHref: "#/" },
+                    },
+                  },
+                ],
+              },
+              {
+                key: "notifications",
+                label: "Notifications",
+                icon: "bell",
+                blocks: [
+                  {
+                    key: "notification_links",
+                    type: "link_list",
+                    data: {
+                      items: [
+                        { label: "Email Templates", href: "#/settings", icon: "mail", description: "Customize email notification templates" },
+                        { label: "Webhook Endpoints", href: "#/settings", icon: "webhook", description: "Configure webhook delivery endpoints" },
+                        { label: "Notification Rules", href: "#/settings", icon: "filter", description: "Set up conditional notification routing" },
+                      ],
+                    },
+                  },
+                ],
+              },
+            ],
+          },
+        },
+      ],
+    },
+  },
+};
+`,
+      "src/pages/settings.ts",
+    );
+  }
+}
+
+// ── App files (entry point + router + adapters) ─────────────────────────
+
+/**
+ * Scaffold src/main.tsx, src/app.tsx, and src/adapters/.
+ */
+export function scaffoldAppFiles(targetDir) {
+  ensureDir(join(targetDir, "src"));
+  ensureDir(join(targetDir, "src", "adapters"));
+
+  // src/main.tsx — entry point
+  const mainPath = join(targetDir, "src", "main.tsx");
+  if (!skipIfExists(mainPath, "src/main.tsx")) {
     writeFile(
       mainPath,
-      `import { StrictMode } from "react";
+      `/**
+ * Entry point \u2014 loaded by index.html during development.
+ *
+ * In production, your host platform (Moodle/WordPress) loads the UI
+ * via Inertia.js and provides its own entry point. This file is
+ * only used by the standalone dev server (\`npm run dev\`).
+ *
+ * Import order matters for CSS:
+ *   1. @middag-io/react/style.css \u2014 base tokens + component styles
+ *   2. ./theme.css                \u2014 your token overrides (wins by cascade)
+ *   3. @fontsource-variable/figtree \u2014 font face declarations
+ */
+import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
-import { ContractPage, registerDefaults } from "@middag-io/react";
+import { registerDefaults } from "@middag-io/react";
 import "@middag-io/react/style.css";
+import "./theme.css";
 import "@fontsource-variable/figtree";
-import { helloContract } from "./hello-contract";
+import { App } from "./app";
 
-// Make contract available to usePage() mock
-(window as any).__MIDDAG_MOCK_CONTRACT__ = helloContract;
-
-// Register all default shells, layouts, and blocks
+// Register all default shells, layouts, and blocks.
+// In production, your host entry point calls this same function.
 registerDefaults();
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
-    <ContractPage contract={helloContract} />
+    <App />
   </StrictMode>,
 );
 `,
-      "mock/main.tsx",
+      "src/main.tsx",
     );
   }
 
-  // mock/index.html
-  const indexPath = join(mockDir, "index.html");
-  if (!skipIfExists(indexPath, "mock/index.html")) {
+  // src/app.tsx — hash-based page router
+  const appPath = join(targetDir, "src", "app.tsx");
+  if (!skipIfExists(appPath, "src/app.tsx")) {
     writeFile(
-      indexPath,
-      `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>MIDDAG React UI \u2014 Mock</title>
-  </head>
-  <body>
-    <div id="root" class="middag-root"></div>
-    <div id="middag-portals" class="middag-root"></div>
-    <script type="module" src="./main.tsx"></script>
-  </body>
-</html>
+      appPath,
+      `import { useState, useEffect } from "react";
+import { ContractPage } from "@middag-io/react";
+import type { PageContract } from "@middag-io/react";
+import { dashboardContract } from "./pages/dashboard";
+import { connectorsContract } from "./pages/connectors";
+import { settingsContract } from "./pages/settings";
+
+/**
+ * Route map \u2014 hash fragment to PageContract.
+ *
+ * In production, Inertia handles routing. This hash-based approach
+ * is only for the standalone dev server. Add more pages here as
+ * you build them.
+ */
+const routes: Record<string, PageContract> = {
+  "/": dashboardContract,
+  "/connectors": connectorsContract,
+  "/settings": settingsContract,
+};
+
+function getRoute(): string {
+  return window.location.hash.replace("#", "") || "/";
+}
+
+export function App() {
+  const [route, setRoute] = useState(getRoute);
+
+  useEffect(() => {
+    const onHashChange = () => setRoute(getRoute());
+    window.addEventListener("hashchange", onHashChange);
+    return () => window.removeEventListener("hashchange", onHashChange);
+  }, []);
+
+  const contract = routes[route] || dashboardContract;
+
+  // Expose contract for usePage() mock adapter
+  (window as any).__MIDDAG_MOCK_CONTRACT__ = contract;
+
+  return <ContractPage contract={contract} />;
+}
 `,
-      "mock/index.html",
+      "src/app.tsx",
     );
   }
 
-  // mock/adapters/inertia-react.ts
-  const adaptersDir = join(mockDir, "adapters");
-  ensureDir(adaptersDir);
-
-  const inertiaReactPath = join(adaptersDir, "inertia-react.ts");
-  if (!skipIfExists(inertiaReactPath, "mock/adapters/inertia-react.ts")) {
+  // src/adapters/inertia-react.ts
+  const inertiaReactPath = join(targetDir, "src", "adapters", "inertia-react.ts");
+  if (!skipIfExists(inertiaReactPath, "src/adapters/inertia-react.ts")) {
     writeFile(
       inertiaReactPath,
       `/**
- * Mock @inertiajs/react \u2014 standalone adapter for mock dev server.
+ * Mock @inertiajs/react \u2014 standalone adapter for dev server.
+ *
  * Vite alias redirects @inertiajs/react imports here.
+ * In production, the real Inertia package handles this.
  */
-import { createElement, forwardRef, useEffect, type ReactNode, type AnchorHTMLAttributes } from "react";
+import React from "react";
 import { router } from "./inertia-core";
 
+// \u2500\u2500 Navigation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+function getActiveKey(): string {
+  const hash = window.location.hash.replace("#", "") || "/";
+  const map: Record<string, string> = {
+    "/": "overview.dashboard",
+    "/connectors": "integration.connectors",
+    "/settings": "system.settings",
+  };
+  return map[hash] || "overview.dashboard";
+}
+
+function buildNavigation() {
+  const activeKey = getActiveKey();
+  const sections = [
+    {
+      key: "overview",
+      label: "Overview",
+      icon: "house",
+      group: "main" as const,
+      items: [
+        { key: "overview.dashboard", label: "Dashboard", href: "#/", active: activeKey === "overview.dashboard", children: [] },
+      ],
+    },
+    {
+      key: "integration",
+      label: "Integration",
+      icon: "plug",
+      group: "main" as const,
+      items: [
+        { key: "integration.connectors", label: "Connectors", href: "#/connectors", active: activeKey === "integration.connectors", children: [] },
+      ],
+    },
+    {
+      key: "system",
+      label: "System",
+      icon: "settings",
+      group: "system" as const,
+      items: [
+        { key: "system.settings", label: "Settings", href: "#/settings", active: activeKey === "system.settings", children: [] },
+      ],
+    },
+  ];
+  return { sections, activeKey };
+}
+
+// \u2500\u2500 usePage \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
 const mockSharedProps = {
-  navigation: {
-    sections: [
-      {
-        key: "home",
-        label: "Home",
-        icon: "house",
-        group: "main",
-        items: [
-          { key: "home.dashboard", label: "Dashboard", href: "/", active: true, children: [] },
-        ],
-      },
-    ],
-    activeKey: "home.dashboard",
-  },
   auth: { id: 1, name: "Dev User", email: "dev@localhost", capabilities: [] },
   theme: { appearance: "light" as const },
   flash: {},
@@ -435,15 +943,24 @@ const mockSharedProps = {
 
 export function usePage<T = Record<string, unknown>>(): { props: T; url: string } {
   const contract = typeof window !== "undefined" ? (window as any).__MIDDAG_MOCK_CONTRACT__ : undefined;
-  return { props: { ...mockSharedProps, contract } as T, url: window.location.pathname };
+  return {
+    props: { ...mockSharedProps, navigation: buildNavigation(), contract } as T,
+    url: window.location.pathname,
+  };
 }
 
-export function Head({ title, children }: { title?: string; children?: ReactNode }) {
-  useEffect(() => { if (title) document.title = title; }, [title]);
-  return children ? createElement("span", { style: { display: "none" } }, children) : null;
+// \u2500\u2500 Head \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+export function Head({ title, children }: { title?: string; children?: React.ReactNode }) {
+  React.useEffect(() => {
+    if (title) document.title = title;
+  }, [title]);
+  return children ? React.createElement("span", { style: { display: "none" } }, children) : null;
 }
 
-interface MockLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+// \u2500\u2500 Link \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+interface MockLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
   href?: string;
   method?: string;
   preserveScroll?: boolean;
@@ -451,7 +968,7 @@ interface MockLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "h
   as?: string;
 }
 
-export const Link = forwardRef<HTMLAnchorElement, MockLinkProps>(function MockLink(
+export const Link = React.forwardRef<HTMLAnchorElement, MockLinkProps>(function MockLink(
   { href, onClick, children, as: _as, method: _m, preserveScroll: _ps, preserveState: _pst, ...rest },
   ref,
 ) {
@@ -461,23 +978,25 @@ export const Link = forwardRef<HTMLAnchorElement, MockLinkProps>(function MockLi
     e.preventDefault();
     if (href) window.location.hash = href;
   };
-  return createElement("a", { ...rest, href: href ?? "#", ref, onClick: handleClick }, children);
+  return React.createElement("a", { ...rest, href: href ?? "#", ref, onClick: handleClick }, children);
 });
 
 export { router };
 `,
-      "mock/adapters/inertia-react.ts",
+      "src/adapters/inertia-react.ts",
     );
   }
 
-  // mock/adapters/inertia-core.ts
-  const inertiaCorePathFile = join(adaptersDir, "inertia-core.ts");
-  if (!skipIfExists(inertiaCorePathFile, "mock/adapters/inertia-core.ts")) {
+  // src/adapters/inertia-core.ts
+  const inertiaCorePath = join(targetDir, "src", "adapters", "inertia-core.ts");
+  if (!skipIfExists(inertiaCorePath, "src/adapters/inertia-core.ts")) {
     writeFile(
-      inertiaCorePathFile,
+      inertiaCorePath,
       `/**
- * Mock @inertiajs/core \u2014 standalone adapter for mock dev server.
+ * Mock @inertiajs/core \u2014 standalone adapter for dev server.
+ *
  * Vite alias redirects @inertiajs/core imports here.
+ * In production, the real Inertia package handles this.
  */
 export const router = {
   get: (url: string) => { window.location.hash = url; },
@@ -490,7 +1009,7 @@ export const router = {
   on: () => () => {},
 };
 `,
-      "mock/adapters/inertia-core.ts",
+      "src/adapters/inertia-core.ts",
     );
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-middag-ui",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "Bootstrap a MIDDAG React UI layer in your Moodle or WordPress plugin",
   "bin": {