create-middag-ui 0.11.0 → 0.12.0

package/cli.js

@@ -33,13 +33,16 @@ import {
   scaffoldIndexHtml,
   scaffoldDemoFiles,
   scaffoldPageExamples,
-  scaffoldProApp,
   scaffoldFreeApp,
   scaffoldFreeAdapters,
   scaffoldDevShell,
   scaffoldHostEntry,
   scaffoldHostViteConfig,
   scaffoldHostThemeCSS,
+  scaffoldFreeRegister,
+  scaffoldPageResolver,
+  scaffoldRouteHelper,
+  scaffoldDemoDirectPage,
 } from "./lib/scaffold.js";
 import { runNpmInstall } from "./lib/install.js";
 import { log, success, heading, blank, info } from "./lib/ui.js";
@@ -150,10 +153,33 @@ heading(8, TOTAL_STEPS, `Creating ${isPro ? "PRO" : "FREE"} UI module`);
 
 scaffoldPageExamples(targetDir);
 
+// Shared files (both PRO and FREE)
+scaffoldPageResolver(targetDir);
+scaffoldDemoDirectPage(targetDir);
+scaffoldRouteHelper(targetDir, hostKey);
+
 if (isPro) {
-  scaffoldProApp(targetDir);
-  success("PRO: using MockProductShell from @middag-io/react/mock");
+  try {
+    const pro = await import("./lib/scaffoldPRO.js");
+    pro.scaffoldProRegister(targetDir);
+    pro.scaffoldProApp(targetDir);
+    pro.scaffoldMockNavigation(targetDir);
+    pro.scaffoldMockData(targetDir);
+    pro.scaffoldMockEntities(targetDir);
+    pro.scaffoldMockPageContracts(targetDir);
+    pro.scaffoldMockRoutes(targetDir);
+    success("PRO: using MockProductShell from @middag-io/react/mock");
+  } catch {
+    // npm version — PRO file excluded, fall back to FREE
+    info("PRO scaffold not available — using FREE path");
+    scaffoldFreeRegister(targetDir);
+    scaffoldFreeAdapters(targetDir);
+    scaffoldDevShell(targetDir);
+    scaffoldFreeApp(targetDir);
+    success("FREE: generated DevShell + local Inertia adapters");
+  }
 } else {
+  scaffoldFreeRegister(targetDir);
   scaffoldFreeAdapters(targetDir);
   scaffoldDevShell(targetDir);
   scaffoldFreeApp(targetDir);

package/lib/scaffold.js

@@ -312,6 +312,7 @@ export function scaffoldIndexHtml(targetDir) {
     -->
     <div id="root" class="middag-root"></div>
     <div id="middag-portals" class="middag-root"></div>
+    <script>window.__MIDDAG_MOCK_NAVIGATE__ = true;</script>
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>
@@ -1304,39 +1305,31 @@ export function scaffoldHostEntry(targetDir, hostKey) {
  */
 import { createRoot } from "react-dom/client";
 import { createInertiaApp } from "@inertiajs/react";
-import {
-  registerDefaults,
-  registerShell,
-  ContractPage,
-  HostProductShell,
-  I18nProvider,
-  ProgressProvider,
-  ptBR,
-} from "@middag-io/react";
-import type { PageContract } from "@middag-io/react";
+import { I18nProvider, ProgressProvider } from "@middag-io/react";
 import "@middag-io/react/style.css";
 import "./theme.css";
+import { registerDefaults } from "./app/register";
+import { resolvePageComponent } from "./app/page-resolver";
 
 registerDefaults();
-registerShell("product", HostProductShell);
 
 createInertiaApp({
   id: "middag-app",
-  resolve: () => {
-    const Page = ({ contract }: { contract: PageContract }) => (
-      <I18nProvider overrides={ptBR}>
-        <ProgressProvider>
-          <ContractPage contract={contract} />
-        </ProgressProvider>
-      </I18nProvider>
-    );
-    Page.displayName = "ContractPageWrapper";
-    return Page;
-  },
+  resolve: (name) => resolvePageComponent(name),
   setup({ el, App, props }) {
     el.classList.add("middag-root");
 ${setupCode}
-    createRoot(el).render(<App {...props} />);
+    createRoot(el).render(
+      <ProgressProvider>
+        <App {...props}>
+          {({ Component, props: pageProps, key }) => (
+            <I18nProvider>
+              <Component key={key} {...pageProps} />
+            </I18nProvider>
+          )}
+        </App>
+      </ProgressProvider>,
+    );
 ${postMountCode}
   },
 });
@@ -1445,7 +1438,7 @@ export default defineConfig({
 export function scaffoldHostThemeCSS(targetDir, hostKey, host) {
   const themePath = join(targetDir, "src", "theme.css");
 
-  let hostSection = "";
+  let hostSection;
 
   if (hostKey === "wordpress") {
     hostSection = `
@@ -1787,3 +1780,70 @@ export const router = {
     );
   }
 }
+
+// ── Template reader ─────────────────────────────────────────────────────
+
+/** Read a template file relative to this script's directory. */
+function readTemplate(relativePath) {
+  return readFileSync(join(__dirname, relativePath), "utf-8");
+}
+
+// ── Shared: register, page-resolver, route helper, demo page ────────────
+
+/**
+ * Scaffold FREE register: src/app/register.ts — minimal (5 blocks).
+ */
+export function scaffoldFreeRegister(targetDir) {
+  ensureDir(join(targetDir, "src", "app"));
+  const filePath = join(targetDir, "src", "app", "register.ts");
+  if (skipIfExists(filePath, "src/app/register.ts")) return;
+  writeFile(filePath, readTemplate("templates/shared/register-free.ts"), "src/app/register.ts (FREE)");
+}
+
+/**
+ * Scaffold page resolver: src/app/page-resolver.tsx.
+ * Supports Contract: prefix pages (ContractPage) and direct pages (glob).
+ */
+export function scaffoldPageResolver(targetDir) {
+  ensureDir(join(targetDir, "src", "app"));
+  const filePath = join(targetDir, "src", "app", "page-resolver.tsx");
+  if (skipIfExists(filePath, "src/app/page-resolver.tsx")) return;
+  writeFile(filePath, readTemplate("templates/shared/page-resolver.tsx"), "src/app/page-resolver.tsx");
+}
+
+/**
+ * Scaffold route helper: src/lib/routes.ts.
+ * Abstracts host admin URL vs dev mock path.
+ *
+ * @param {string} hostKey - 'wordpress' | 'moodle' | 'custom'
+ */
+export function scaffoldRouteHelper(targetDir, hostKey) {
+  ensureDir(join(targetDir, "src", "lib"));
+  const filePath = join(targetDir, "src", "lib", "routes.ts");
+  if (skipIfExists(filePath, "src/lib/routes.ts")) return;
+
+  const templateMap = {
+    wordpress: "templates/shared/route-helper-wp.ts",
+    moodle: "templates/shared/route-helper-moodle.ts",
+    custom: "templates/shared/route-helper-custom.ts",
+  };
+  const template = templateMap[hostKey] || templateMap.wordpress;
+
+  try {
+    writeFile(filePath, readTemplate(template), "src/lib/routes.ts");
+  } catch {
+    // Fallback to WP template if host-specific one doesn't exist
+    writeFile(filePath, readTemplate("templates/shared/route-helper-wp.ts"), "src/lib/routes.ts");
+  }
+}
+
+/**
+ * Scaffold demo direct page: src/pages/DemoPage.tsx.
+ * Shows the direct page pattern (usePage + custom React).
+ */
+export function scaffoldDemoDirectPage(targetDir) {
+  ensureDir(join(targetDir, "src", "pages"));
+  const filePath = join(targetDir, "src", "pages", "DemoPage.tsx");
+  if (skipIfExists(filePath, "src/pages/DemoPage.tsx")) return;
+  writeFile(filePath, readTemplate("templates/shared/demo-page.tsx"), "src/pages/DemoPage.tsx");
+}

package/lib/scaffoldPRO.js

@@ -0,0 +1,228 @@
+/**
+ * scaffoldPRO.js — PRO-only scaffold functions for create-middag-ui.
+ *
+ * NOT published to npm (excluded via .npmignore).
+ * Only available when installed from GitHub Packages.
+ *
+ * Generates the extended mock harness (mock/, src/app/register.ts)
+ * with 9+ blocks, extracted navigation/data/entities/routes files,
+ * and the slim app.tsx that delegates to mock/.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { success, warn, error } from "./ui.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ── Helpers (duplicated from scaffold.js — not exported there) ──────
+
+function readTemplate(relativePath) {
+  return readFileSync(join(__dirname, relativePath), "utf-8");
+}
+
+function writeFile(filePath, content, label) {
+  try {
+    writeFileSync(filePath, content);
+    success(`Created ${label}`);
+    return true;
+  } catch (err) {
+    error(`Failed to create ${label}: ${err.message}`);
+    return false;
+  }
+}
+
+function ensureDir(dirPath) {
+  try {
+    mkdirSync(dirPath, { recursive: true });
+    return true;
+  } catch (err) {
+    error(`Failed to create directory ${dirPath}: ${err.message}`);
+    return false;
+  }
+}
+
+function skipIfExists(filePath, label) {
+  if (existsSync(filePath)) {
+    warn(`${label} already exists — skipping`);
+    return true;
+  }
+  return false;
+}
+
+// ── 1. PRO register (9+ blocks) ────────────────────────────────────────
+
+/**
+ * Scaffold `src/app/register.ts` — PRO version with 9+ blocks.
+ * Overrides any FREE register that may have been scaffolded.
+ *
+ * @param {string} targetDir - Absolute path to UI project root
+ */
+export function scaffoldProRegister(targetDir) {
+  ensureDir(join(targetDir, "src", "app"));
+
+  const filePath = join(targetDir, "src", "app", "register.ts");
+  if (skipIfExists(filePath, "src/app/register.ts")) return;
+
+  writeFile(
+    filePath,
+    readTemplate("templates/pro/register-pro.ts"),
+    "src/app/register.ts",
+  );
+}
+
+// ── 2. PRO app (main.tsx + app.tsx) ────────────────────────────────────
+
+/**
+ * Scaffold `src/main.tsx` and `src/app.tsx` for the PRO path.
+ *
+ * main.tsx boots the dev server with MockProductShell.
+ * app.tsx is a slim shell that delegates to mock/ files.
+ *
+ * @param {string} targetDir - Absolute path to UI project root
+ */
+export function scaffoldProApp(targetDir) {
+  ensureDir(join(targetDir, "src"));
+
+  // ── src/main.tsx ──────────────────────────────────────────────────
+  const mainPath = join(targetDir, "src", "main.tsx");
+  if (!skipIfExists(mainPath, "src/main.tsx")) {
+    writeFile(
+      mainPath,
+      readTemplate("templates/pro/main.tsx"),
+      "src/main.tsx",
+    );
+  }
+
+  // ── src/app.tsx ───────────────────────────────────────────────────
+  const appPath = join(targetDir, "src", "app.tsx");
+  if (!skipIfExists(appPath, "src/app.tsx")) {
+    writeFile(
+      appPath,
+      readTemplate("templates/pro/app.tsx"),
+      "src/app.tsx",
+    );
+  }
+}
+
+// ── 3. Mock navigation ─────────────────────────────────────────────────
+
+/**
+ * Scaffold `mock/navigation.ts` — sidebar structure for dev server.
+ *
+ * @param {string} targetDir - Absolute path to UI project root
+ */
+export function scaffoldMockNavigation(targetDir) {
+  ensureDir(join(targetDir, "mock"));
+
+  const filePath = join(targetDir, "mock", "navigation.ts");
+  if (skipIfExists(filePath, "mock/navigation.ts")) return;
+
+  writeFile(
+    filePath,
+    readTemplate("templates/pro/mock-navigation.ts"),
+    "mock/navigation.ts",
+  );
+}
+
+// ── 4. Mock data ───────────────────────────────────────────────────────
+
+/**
+ * Scaffold `mock/data.ts` — synthetic props for dev mode pages.
+ *
+ * @param {string} targetDir - Absolute path to UI project root
+ */
+export function scaffoldMockData(targetDir) {
+  ensureDir(join(targetDir, "mock"));
+
+  const filePath = join(targetDir, "mock", "data.ts");
+  if (skipIfExists(filePath, "mock/data.ts")) return;
+
+  writeFile(
+    filePath,
+    readTemplate("templates/pro/mock-data.ts"),
+    "mock/data.ts",
+  );
+}
+
+// ── 5. Mock entities ───────────────────────────────────────────────────
+
+/**
+ * Scaffold `mock/entities.ts` — entity route map for mock contracts.
+ *
+ * @param {string} targetDir - Absolute path to UI project root
+ */
+export function scaffoldMockEntities(targetDir) {
+  ensureDir(join(targetDir, "mock"));
+
+  const filePath = join(targetDir, "mock", "entities.ts");
+  if (skipIfExists(filePath, "mock/entities.ts")) return;
+
+  writeFile(
+    filePath,
+    readTemplate("templates/pro/mock-entities.ts"),
+    "mock/entities.ts",
+  );
+}
+
+// ── 6. Mock page contracts ────────────────────────────────────────────
+
+/**
+ * Move page contract examples to `mock/page-contracts/` for PRO path.
+ *
+ * In PRO, the 3 demo contracts (dashboard, connectors, settings) live
+ * in mock/page-contracts/ instead of src/pages/ because they are dev-only
+ * mock data, not production React components.
+ *
+ * scaffoldPageExamples() already created them in src/pages/.
+ * This function reads them from there and writes to mock/page-contracts/,
+ * then removes the originals from src/pages/.
+ *
+ * @param {string} targetDir - Absolute path to UI project root
+ */
+export function scaffoldMockPageContracts(targetDir) {
+  const srcDir = join(targetDir, "src", "pages");
+  const destDir = join(targetDir, "mock", "page-contracts");
+  ensureDir(destDir);
+
+  const files = ["dashboard.ts", "connectors.ts", "settings.ts"];
+
+  for (const file of files) {
+    const src = join(srcDir, file);
+    const dest = join(destDir, file);
+
+    if (skipIfExists(dest, `mock/page-contracts/${file}`)) continue;
+
+    if (existsSync(src)) {
+      const content = readFileSync(src, "utf-8");
+      writeFile(dest, content, `mock/page-contracts/${file}`);
+      // Remove from src/pages/ — PRO keeps contracts in mock/ only
+      try {
+        unlinkSync(src);
+      } catch {
+        // Not critical — src/pages/*.ts won't interfere (glob matches .tsx only)
+      }
+    }
+  }
+}
+
+// ── 7. Mock routes ─────────────────────────────────────────────────────
+
+/**
+ * Scaffold `mock/routes.tsx` — all dev server route definitions.
+ *
+ * @param {string} targetDir - Absolute path to UI project root
+ */
+export function scaffoldMockRoutes(targetDir) {
+  ensureDir(join(targetDir, "mock"));
+
+  const filePath = join(targetDir, "mock", "routes.tsx");
+  if (skipIfExists(filePath, "mock/routes.tsx")) return;
+
+  writeFile(
+    filePath,
+    readTemplate("templates/pro/mock-routes.tsx"),
+    "mock/routes.tsx",
+  );
+}

package/lib/templates/pro/app.tsx

@@ -0,0 +1,50 @@
+/**
+ * Dev mock app — shell that never needs editing.
+ *
+ * To add pages or change navigation, edit files in mock/:
+ *   mock/routes.tsx      — route definitions
+ *   mock/navigation.ts   — sidebar structure
+ *   mock/data.ts         — synthetic page props
+ */
+import { useEffect } from "react";
+import { BrowserRouter, Routes, useNavigate } from "react-router";
+import { I18nProvider } from "@middag-io/react";
+import { MockPageProvider, MockI18nProvider, setMockNavigate } from "@middag-io/react/mock";
+import { buildNavigation } from "../mock/navigation";
+import { sharedProps } from "../mock/data";
+import { AppRoutes } from "../mock/routes";
+
+let _navigate: ((to: string) => void) | null = null;
+function NavigateBridge() {
+  const navigate = useNavigate();
+  useEffect(() => {
+    _navigate = (to: string) => navigate(to);
+    setMockNavigate((to: string) => navigate(to));
+  }, [navigate]);
+  return null;
+}
+if (typeof window !== "undefined") {
+  (window as any).__MIDDAG_MOCK_NAVIGATE__ = (to: string) => {
+    if (_navigate) _navigate(to);
+  };
+}
+
+export function App() {
+  return (
+    <MockI18nProvider>
+      <MockPageProvider
+        value={{
+          props: { ...sharedProps, contract: null, navigation: buildNavigation("") },
+          url: "/",
+        }}
+      >
+        <I18nProvider>
+          <BrowserRouter>
+            <NavigateBridge />
+            <Routes>{AppRoutes()}</Routes>
+          </BrowserRouter>
+        </I18nProvider>
+      </MockPageProvider>
+    </MockI18nProvider>
+  );
+}

package/lib/templates/pro/main.tsx

@@ -0,0 +1,16 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { MockProductShell } from "@middag-io/react/mock";
+import { registerShell } from "@middag-io/react";
+import "@middag-io/react/style.css";
+import "./theme.css";
+import "@fontsource-variable/figtree";
+import { registerDefaults } from "./app/register";
+import { App } from "./app";
+
+registerDefaults();
+registerShell("product", MockProductShell);
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode><App /></StrictMode>,
+);

package/lib/templates/pro/mock-data.ts

@@ -0,0 +1,28 @@
+/**
+ * Mock data — synthetic props for direct pages in dev mode.
+ *
+ * Used by mock/routes.tsx to feed Inertia-like props via MockPageProvider.
+ * In production, your host platform page controllers provide this data.
+ */
+
+export const sharedProps = {
+  auth: { id: 1, name: "Dev User", email: "dev@localhost", capabilities: [] },
+  theme: { appearance: "light" as const, strings: {} as Record<string, string> },
+  flash: {},
+  locale: "en",
+  version: "0.0.0-dev",
+  scope: { extension: null, context: "global" },
+};
+
+/**
+ * Props for the demo direct page (pages/DemoPage.tsx).
+ * Add more page props here as you create direct pages.
+ */
+export const mockDemoPageProps = {
+  title: "Demo Direct Page",
+  items: [
+    { id: 1, name: "Item One", status: "active" },
+    { id: 2, name: "Item Two", status: "pending" },
+    { id: 3, name: "Item Three", status: "completed" },
+  ],
+};

package/lib/templates/pro/mock-entities.ts

@@ -0,0 +1,13 @@
+/**
+ * Entity route map — shared by all mock contracts.
+ *
+ * Defines navigable entity types and their URL patterns.
+ * In production, your host platform builds the same map with admin URLs.
+ *
+ * Add entity types here as you create domain pages.
+ */
+export const mockEntities: Record<string, string> = {
+  dashboard: "/",
+  connector: "/connectors/{id}",
+  setting: "/settings/{id}",
+};

package/lib/templates/pro/mock-navigation.ts

@@ -0,0 +1,59 @@
+/**
+ * Mock navigation — sidebar structure for dev server.
+ *
+ * Used by app.tsx routes to simulate host admin navigation.
+ * In production, your host platform sends navigation via Inertia shared props.
+ */
+
+export function buildNavigation(activeKey: string) {
+  return {
+    sections: [
+      {
+        key: "overview",
+        label: "Overview",
+        icon: "home",
+        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: [],
+          },
+        ],
+      },
+    ],
+    activeKey,
+  };
+}

package/lib/templates/pro/mock-routes.tsx

@@ -0,0 +1,90 @@
+/**
+ * Mock routes — all dev server route definitions.
+ *
+ * Add new pages here. app.tsx renders these without modification.
+ */
+import { Route } from "react-router";
+import { type ReactNode } from "react";
+import { ContractPage, resolveShell, EntityRoutesProvider } from "@middag-io/react";
+import { MockPageProvider } from "@middag-io/react/mock";
+import type { PageContract } from "@middag-io/react";
+import { mockEntities } from "./entities";
+import { buildNavigation } from "./navigation";
+import { sharedProps, mockDemoPageProps } from "./data";
+import { dashboardContract } from "./page-contracts/dashboard";
+import { connectorsContract } from "./page-contracts/connectors";
+import { settingsContract } from "./page-contracts/settings";
+import DemoPage from "../src/pages/DemoPage";
+
+// Resolve shell at module level (not inside render — avoids react-hooks/static-components)
+const ProductShell = resolveShell("product");
+
+// ── Route wrappers ──────────────────────────────────────────────────
+
+function MockRoute({ contract, activeKey }: { contract: PageContract; activeKey: string }) {
+  return (
+    <MockPageProvider
+      value={{
+        props: { ...sharedProps, contract, navigation: buildNavigation(activeKey) },
+        url: window.location.pathname,
+      }}
+    >
+      <ContractPage contract={contract} />
+    </MockPageProvider>
+  );
+}
+
+function MockDirectRoute({
+  activeKey,
+  pageProps,
+  children,
+}: {
+  activeKey: string;
+  pageProps: Record<string, unknown>;
+  children: ReactNode;
+}) {
+  return (
+    <MockPageProvider
+      value={{
+        props: { ...sharedProps, ...pageProps, navigation: buildNavigation(activeKey) },
+        url: window.location.pathname,
+      }}
+    >
+      <EntityRoutesProvider entities={mockEntities}>
+        {ProductShell ? <ProductShell>{children}</ProductShell> : children}
+      </EntityRoutesProvider>
+    </MockPageProvider>
+  );
+}
+
+// ── Route list ──────────────────────────────────────────────────────
+
+export function AppRoutes() {
+  return (
+    <>
+      {/* Contract pages (rendered by lib ContractPage) */}
+      <Route
+        path="/"
+        element={<MockRoute contract={dashboardContract} activeKey="overview.dashboard" />}
+      />
+      <Route
+        path="/connectors"
+        element={<MockRoute contract={connectorsContract} activeKey="integration.connectors" />}
+      />
+      <Route
+        path="/settings"
+        element={<MockRoute contract={settingsContract} activeKey="system.settings" />}
+      />
+
+      {/* Direct page (custom React component) */}
+      <Route
+        path="/demo"
+        element={
+          <MockDirectRoute activeKey="overview.demo" pageProps={mockDemoPageProps}>
+            <DemoPage />
+          </MockDirectRoute>
+        }
+      />
+    </>
+  );
+}

package/lib/templates/pro/register-pro.ts

@@ -0,0 +1,57 @@
+/**
+ * register — selective registration for this plugin's UI (PRO).
+ *
+ * Registers shells, layouts, and blocks this plugin uses.
+ * Add or remove registrations as your pages need them.
+ *
+ * Full catalog: https://docs.middag.io/blocks
+ */
+
+import {
+  registerShell,
+  registerLayout,
+  registerBlock,
+  // Shells
+  HostProductShell,
+  // Layouts
+  StackLayout,
+  SplitLayout,
+  DashboardLayout,
+  // Blocks
+  DenseTableBlock,
+  MetricCardBlock,
+  EmptyStateBlock,
+  DetailPanelBlock,
+  StatusStripBlock,
+  FormPanelBlock,
+  TabbedPanelBlock,
+  ActivityTimelineBlock,
+  WorkflowProgressBlock,
+} from "@middag-io/react";
+
+let registered = false;
+
+export function registerDefaults(): void {
+  if (registered) return;
+  registered = true;
+
+  // Shells
+  registerShell("product", HostProductShell);
+
+  // Layouts
+  registerLayout("stack", StackLayout);
+  registerLayout("split", SplitLayout);
+  registerLayout("dashboard", DashboardLayout);
+
+  // Blocks — add more as your pages need them
+  // See: https://docs.middag.io/blocks for the full catalog
+  registerBlock("dense_table", DenseTableBlock);
+  registerBlock("metric_card", MetricCardBlock);
+  registerBlock("empty_state", EmptyStateBlock);
+  registerBlock("detail_panel", DetailPanelBlock);
+  registerBlock("status_strip", StatusStripBlock);
+  registerBlock("form_panel", FormPanelBlock);
+  registerBlock("tabbed_panel", TabbedPanelBlock);
+  registerBlock("activity_timeline", ActivityTimelineBlock);
+  registerBlock("workflow_progress", WorkflowProgressBlock);
+}

package/lib/templates/shared/demo-page.tsx

@@ -0,0 +1,45 @@
+/**
+ * Demo Direct Page — example of a custom React page.
+ *
+ * Direct pages receive props from Inertia (via usePage) and render
+ * custom UI. Use this pattern for complex pages that can't be
+ * expressed as a PageContract (workflows, wizards, dashboards).
+ *
+ * In production, the host page controller calls:
+ *   InertiaAdapter::render('DemoPage', { title: '...', items: [...] })
+ *
+ * The page-resolver matches "DemoPage" to this file via import.meta.glob.
+ */
+import { usePage } from "@inertiajs/react";
+
+interface DemoPageProps {
+  title: string;
+  items: Array<{ id: number; name: string; status: string }>;
+}
+
+export default function DemoPage() {
+  const { props } = usePage<DemoPageProps>();
+  const { title, items } = props;
+
+  return (
+    <div className="mx-auto max-w-2xl p-8">
+      <h1 className="text-foreground text-2xl font-semibold">{title}</h1>
+      <p className="text-muted-foreground mt-2 text-sm">
+        This is a direct page — it uses usePage() instead of PageContract.
+      </p>
+      <ul className="mt-6 space-y-2">
+        {items?.map((item) => (
+          <li
+            key={item.id}
+            className="bg-card border-border flex items-center justify-between rounded-lg border px-4 py-3"
+          >
+            <span className="text-foreground text-sm font-medium">{item.name}</span>
+            <span className="bg-muted text-muted-foreground rounded-full px-2 py-0.5 text-xs">
+              {item.status}
+            </span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/lib/templates/shared/page-resolver.tsx

@@ -0,0 +1,50 @@
+import { ContractPage } from "@middag-io/react";
+import { usePage } from "@inertiajs/react";
+import type { PageContract, ContractPageProps } from "@middag-io/react";
+
+// Direct pages — eager loaded (custom React pages in pages/)
+const directPages = import.meta.glob("../pages/**/*.tsx", { eager: true }) as Record<
+  string,
+  Record<string, unknown>
+>;
+
+/**
+ * Fallback component — reads PageContract from Inertia props and renders
+ * it via the lib's ContractPage. Used when no direct page matches.
+ */
+function InertiaContractPage() {
+  const { props } = usePage<{
+    contract: PageContract;
+    help?: ContractPageProps["help"];
+    inspector?: ContractPageProps["inspector"];
+  }>();
+  return <ContractPage contract={props.contract} help={props.help} inspector={props.inspector} />;
+}
+
+const contractPageModule = { default: InertiaContractPage };
+
+/**
+ * Resolve an Inertia page name to a React component module.
+ *
+ * Resolution order:
+ *   1. Direct page — if pages/{name}.tsx exists, use it
+ *   2. ContractPage — fallback, reads PageContract JSON from Inertia props
+ *
+ * This means:
+ *   - "Dashboard" with pages/Dashboard.tsx → direct React page
+ *   - "Dashboard" without matching .tsx   → ContractPage from props.contract
+ *   - "Entitlements/Show" with pages/Entitlements/Show.tsx → direct page
+ *
+ * Direct pages can also use ContractPage internally (hybrid pattern).
+ */
+export function resolvePageComponent(name: string): Record<string, unknown> {
+  // Direct page: matching .tsx file in pages/
+  const path = `../pages/${name}.tsx`;
+  const page = directPages[path];
+  if (page) {
+    return page;
+  }
+
+  // Default: ContractPage renders from Inertia props.contract
+  return contractPageModule;
+}

package/lib/templates/shared/register-free.ts

@@ -0,0 +1,52 @@
+/**
+ * register — selective registration for this plugin's UI.
+ *
+ * Registers only the shells, layouts, and blocks this plugin uses.
+ * For IIFE bundles (WordPress/Moodle), selective registration avoids
+ * pulling in heavy lazy-loaded blocks that bloat the bundle.
+ *
+ * When adding a new page that needs a block not listed here,
+ * add the import + registerBlock call.
+ *
+ * Full catalog: https://docs.middag.io/blocks
+ */
+
+import {
+  registerShell,
+  registerLayout,
+  registerBlock,
+  // Shells
+  HostProductShell,
+  // Layouts
+  StackLayout,
+  SplitLayout,
+  DashboardLayout,
+  // Blocks
+  DenseTableBlock,
+  MetricCardBlock,
+  EmptyStateBlock,
+  DetailPanelBlock,
+  FormPanelBlock,
+} from "@middag-io/react";
+
+let registered = false;
+
+export function registerDefaults(): void {
+  if (registered) return;
+  registered = true;
+
+  // Shells
+  registerShell("product", HostProductShell);
+
+  // Layouts
+  registerLayout("stack", StackLayout);
+  registerLayout("split", SplitLayout);
+  registerLayout("dashboard", DashboardLayout);
+
+  // Blocks — add more as your pages need them
+  registerBlock("dense_table", DenseTableBlock);
+  registerBlock("metric_card", MetricCardBlock);
+  registerBlock("empty_state", EmptyStateBlock);
+  registerBlock("detail_panel", DetailPanelBlock);
+  registerBlock("form_panel", FormPanelBlock);
+}

package/lib/templates/shared/route-helper-wp.ts

@@ -0,0 +1,26 @@
+/**
+ * Route helper — generates correct URLs for WordPress production vs dev mock.
+ *
+ * In production (Inertia): /wp-admin/admin.php?page=middag-{slug}
+ * In dev mock (BrowserRouter): /{slug} directly
+ *
+ * Detection: if window.__MIDDAG_MOCK_NAVIGATE__ exists, we're in dev mock.
+ */
+
+/**
+ * Build a URL for a MIDDAG admin page.
+ *
+ * Detection is lazy (checked per call) because module evaluation order
+ * means the mock flag may not be set when this module first loads.
+ *
+ * @param slug  - Domain slug (e.g. "entitlements", "organizations")
+ * @param path  - Optional sub-path (e.g. "/entitlements/1/edit")
+ */
+export function route(slug: string, path?: string): string {
+  if (typeof window !== "undefined" && "__MIDDAG_MOCK_NAVIGATE__" in window) {
+    return path ?? `/${slug}`;
+  }
+
+  const base = `/wp-admin/admin.php?page=middag-${slug}`;
+  return path ? `${base}&route=${path}` : base;
+}

package/package.json

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