create-middag-ui 0.1.4 → 0.2.1

package/lib/scaffold.js

@@ -0,0 +1,399 @@
+/**
+ * scaffold.js — File creation for all scaffolded files.
+ *
+ * Creates directory structure, config files, demo files, and mock files.
+ * Every I/O operation is wrapped with error handling.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { success, warn, error } from "./ui.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Read version from own package.json (synced from root by CI). */
+function getLibVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+    return pkg.version || "0.2.0";
+  } catch {
+    return "0.2.0";
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+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 \u2014 skipping`);
+    return true;
+  }
+  return false;
+}
+
+// ── Create target directory ──────────────────────────────────────────────
+
+/**
+ * Create the target directory.
+ * @param {string} targetDir - Absolute path
+ * @returns {boolean} true if directory exists/was created
+ */
+export function createTargetDir(targetDir) {
+  if (existsSync(targetDir)) {
+    warn(`${basename(targetDir)}/ directory already exists \u2014 will scaffold inside it`);
+    return true;
+  }
+  return ensureDir(targetDir);
+}
+
+// ── Config files ─────────────────────────────────────────────────────────
+
+/**
+ * Scaffold package.json.
+ */
+export function scaffoldPackageJson(targetDir, host, cwd) {
+  const filePath = join(targetDir, "package.json");
+  if (skipIfExists(filePath, "package.json")) return;
+
+  const projectName = basename(cwd) || "project";
+  const pkg = {
+    name: `${projectName}-ui`,
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "vite --config vite.mock.config.ts",
+      "dev:mock": "vite --config vite.mock.config.ts",
+      build: "vite build",
+      "build:mock": "vite build --config vite.mock.config.ts",
+      typecheck: "tsc --noEmit",
+      lint: "eslint .",
+      "lint:fix": "eslint . --fix",
+    },
+    dependencies: {
+      "@middag-io/react": `^${getLibVersion()}`,
+    },
+    devDependencies: {
+      "@types/react": "^19.0.0",
+      "@types/react-dom": "^19.0.0",
+      react: "^19.0.0",
+      "react-dom": "^19.0.0",
+      "@inertiajs/react": "^2.0.0",
+      "@inertiajs/core": "^2.0.0",
+      typescript: "^5.7.0",
+      vite: "^6.0.0",
+      "@vitejs/plugin-react": "^4.0.0",
+      tailwindcss: "^4.0.0",
+      "@tailwindcss/vite": "^4.0.0",
+    },
+  };
+
+  writeFile(filePath, JSON.stringify(pkg, null, 2) + "\n", "package.json");
+}
+
+/**
+ * Scaffold tsconfig.json.
+ */
+export function scaffoldTsconfig(targetDir) {
+  const filePath = join(targetDir, "tsconfig.json");
+  if (skipIfExists(filePath, "tsconfig.json")) return;
+
+  const tsconfig = {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      jsx: "react-jsx",
+      strict: true,
+      noUnusedLocals: true,
+      noUnusedParameters: true,
+      skipLibCheck: true,
+      paths: { "@/*": ["./src/*"], "@mock/*": ["./mock/*"] },
+      baseUrl: ".",
+    },
+    include: ["src", "mock"],
+  };
+
+  writeFile(filePath, JSON.stringify(tsconfig, null, 2) + "\n", "tsconfig.json");
+}
+
+/**
+ * Scaffold vite.mock.config.ts.
+ */
+export function scaffoldViteConfig(targetDir, host) {
+  const filePath = join(targetDir, "vite.mock.config.ts");
+  if (skipIfExists(filePath, "vite.mock.config.ts")) return;
+
+  const content = `import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { resolve } from "path";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  root: "mock",
+  server: { port: ${host.port} },
+  resolve: {
+    alias: {
+      "@/": resolve(__dirname, "src") + "/",
+      "@mock/": resolve(__dirname, "mock") + "/",
+    },
+  },
+});
+`;
+
+  writeFile(filePath, content, "vite.mock.config.ts");
+}
+
+// ── Demo files in src/ ──────────────────────────────────────────────────
+
+/**
+ * Scaffold demo files in src/ that teach the contract system.
+ */
+export function scaffoldDemoFiles(targetDir) {
+  ensureDir(join(targetDir, "src", "blocks"));
+  ensureDir(join(targetDir, "src", "components"));
+
+  // src/blocks/hello-block.tsx
+  const helloBlockPath = join(targetDir, "src", "blocks", "hello-block.tsx");
+  if (!skipIfExists(helloBlockPath, "src/blocks/hello-block.tsx")) {
+    writeFile(
+      helloBlockPath,
+      `// RENAME ME \u2014 This is an example custom block.
+//
+// It demonstrates how to create a block that integrates with
+// the MIDDAG contract system via registerBlock().
+//
+// After renaming, update the registration in your setup code.
+//
+// Docs: https://docs.middag.io/blocks/custom-blocks
+
+import type { BlockProps } from "@middag-io/react";
+
+/** Data shape for this block \u2014 define what the backend sends. */
+export interface HelloBlockData {
+  greeting: string;
+  name: string;
+}
+
+/** Custom block component. Receives data from the PageContract. */
+export function HelloBlock({ data }: BlockProps<HelloBlockData>) {
+  return (
+    <div className="rounded-lg border bg-card p-6 text-card-foreground">
+      <h2 className="text-lg font-semibold text-foreground">
+        {data.greeting}
+      </h2>
+      <p className="mt-2 text-muted-foreground">
+        Welcome, {data.name}! This is a custom block.
+      </p>
+      <p className="mt-4 text-sm text-muted-foreground">
+        Edit this file at <code className="text-xs bg-muted px-1 py-0.5 rounded">src/blocks/hello-block.tsx</code>
+      </p>
+    </div>
+  );
+}
+`,
+      "src/blocks/hello-block.tsx",
+    );
+  }
+
+  // src/components/greeting.tsx
+  const greetingPath = join(targetDir, "src", "components", "greeting.tsx");
+  if (!skipIfExists(greetingPath, "src/components/greeting.tsx")) {
+    writeFile(
+      greetingPath,
+      `// RENAME ME \u2014 This is an example standalone component.
+//
+// It shows you can write normal React components alongside
+// contract-driven blocks. Not everything needs to be a block.
+//
+// Use standalone components for UI that doesn't come from
+// a PageContract \u2014 headers, sidebars, modals, etc.
+
+interface GreetingProps {
+  name: string;
+  role?: string;
+}
+
+export function Greeting({ name, role = "developer" }: GreetingProps) {
+  return (
+    <div className="flex items-center gap-3 rounded-md bg-muted px-4 py-3">
+      <div className="flex h-8 w-8 items-center justify-center rounded-full bg-primary text-primary-foreground text-sm font-medium">
+        {name.charAt(0).toUpperCase()}
+      </div>
+      <div>
+        <p className="text-sm font-medium text-foreground">{name}</p>
+        <p className="text-xs text-muted-foreground">{role}</p>
+      </div>
+    </div>
+  );
+}
+`,
+      "src/components/greeting.tsx",
+    );
+  }
+
+  // src/contracts.ts
+  const contractsPath = join(targetDir, "src", "contracts.ts");
+  if (!skipIfExists(contractsPath, "src/contracts.ts")) {
+    writeFile(
+      contractsPath,
+      `// Re-export PageContract types from the lib for convenience.
+// Import from here instead of directly from @middag-io/react.
+//
+// Example:
+//   import type { PageContract } from '@/contracts';
+
+export type { PageContract, BlockDescriptor, SharedProps } from "@middag-io/react";
+`,
+      "src/contracts.ts",
+    );
+  }
+}
+
+// ── Mock files ──────────────────────────────────────────────────────────
+
+/**
+ * Scaffold mock/ files (hello-contract, main.tsx, index.html, tailwind.css).
+ */
+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";
+
+/**
+ * Hello World contract \u2014 a minimal PageContract to verify your setup.
+ *
+ * This is what your backend will send via Inertia.
+ * Replace this with real data from your server.
+ */
+export const helloContract: PageContract = {
+  shell: "admin",
+  meta: {
+    title: "Hello MIDDAG",
+    breadcrumbs: [
+      { label: "Home", href: "/" },
+      { label: "Hello", href: "/hello" },
+    ],
+  },
+  layout: {
+    template: "stack",
+    regions: {
+      content: [
+        {
+          key: "welcome_metrics",
+          type: "metric_card",
+          data: {
+            title: "Setup Complete",
+            value: "1",
+            subtitle: "@middag-io/react is working",
+            trend: { direction: "up", value: "100%", label: "Ready" },
+          },
+        },
+        {
+          key: "hello_table",
+          type: "dense_table",
+          data: {
+            title: "Example Data",
+            columns: [
+              { key: "id", label: "ID", sortable: true },
+              { key: "name", label: "Name", sortable: true },
+              { key: "status", label: "Status" },
+            ],
+            rows: [
+              { id: 1, name: "First item", status: "Active" },
+              { id: 2, name: "Second item", status: "Draft" },
+              { id: 3, name: "Third item", status: "Active" },
+            ],
+            pagination: { current: 1, total: 1, perPage: 10, totalRows: 3 },
+          },
+        },
+      ],
+    },
+  },
+};
+`,
+      "mock/hello-contract.ts",
+    );
+  }
+
+  // mock/main.tsx
+  const mainPath = join(mockDir, "main.tsx");
+  if (!skipIfExists(mainPath, "mock/main.tsx")) {
+    writeFile(
+      mainPath,
+      `import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { ContractPage, registerDefaults } from "@middag-io/react";
+import "@middag-io/react/style.css";
+import "./tailwind.css";
+import { helloContract } from "./hello-contract";
+
+// Register all default shells, layouts, and blocks
+registerDefaults();
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <ContractPage contract={helloContract} />
+  </StrictMode>,
+);
+`,
+      "mock/main.tsx",
+    );
+  }
+
+  // mock/index.html
+  const indexPath = join(mockDir, "index.html");
+  if (!skipIfExists(indexPath, "mock/index.html")) {
+    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"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>
+`,
+      "mock/index.html",
+    );
+  }
+
+  // mock/tailwind.css
+  const cssPath = join(mockDir, "tailwind.css");
+  if (!skipIfExists(cssPath, "mock/tailwind.css")) {
+    writeFile(cssPath, '@import "tailwindcss";\n', "mock/tailwind.css");
+  }
+}

package/lib/ui.js

@@ -0,0 +1,85 @@
+/* global console, process, setInterval, clearInterval */
+/**
+ * ui.js — ANSI output helpers (log, success, warn, error, spinner).
+ *
+ * Zero external deps — uses raw ANSI escape codes.
+ */
+
+const PREFIX = "\x1b[36mcreate-middag-ui\x1b[0m";
+const RESET = "\x1b[0m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const CYAN = "\x1b[36m";
+
+export function log(msg) {
+  console.log(`${PREFIX} ${msg}`);
+}
+
+export function success(msg) {
+  console.log(`  ${GREEN}\u2713${RESET} ${msg}`);
+}
+
+export function warn(msg) {
+  console.log(`  ${YELLOW}\u26A0${RESET} ${msg}`);
+}
+
+export function error(msg) {
+  console.log(`  ${RED}\u2717${RESET} ${msg}`);
+}
+
+export function info(msg) {
+  console.log(`  ${DIM}${msg}${RESET}`);
+}
+
+export function heading(step, total, msg) {
+  console.log(`\n${CYAN}[${step}/${total}]${RESET} ${BOLD}${msg}${RESET}`);
+}
+
+export function blank() {
+  console.log("");
+}
+
+// ── Spinner ──────────────────────────────────────────────────────────────
+
+const FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+
+/**
+ * Creates an inline spinner that overwrites the current line.
+ *
+ * Returns { stop(finalMsg) } — call stop() to clear the spinner
+ * and print a final message.
+ */
+export function createSpinner(msg) {
+  let i = 0;
+  const id = setInterval(() => {
+    const frame = FRAMES[i % FRAMES.length];
+    process.stdout.write(`\r  ${CYAN}${frame}${RESET} ${msg}`);
+    i++;
+  }, 80);
+
+  return {
+    /** Update the spinner message while it's running. */
+    update(newMsg) {
+      msg = newMsg;
+    },
+    /** Stop spinner and print final line. */
+    stop(finalMsg) {
+      clearInterval(id);
+      process.stdout.write(`\r\x1b[2K`); // clear line
+      if (finalMsg) {
+        success(finalMsg);
+      }
+    },
+    /** Stop spinner and print error. */
+    fail(failMsg) {
+      clearInterval(id);
+      process.stdout.write(`\r\x1b[2K`);
+      if (failMsg) {
+        error(failMsg);
+      }
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-middag-ui",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "type": "module",
   "description": "Bootstrap a MIDDAG React UI layer in your Moodle or WordPress plugin",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "cli.js",
+    "lib/",
     "README.md"
   ],
   "keywords": [