create-middag-ui 0.10.3 → 0.12.0

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;
+}