idml-ui 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# idml
+
+A configuration-driven UI framework for Next.js 15 + TypeScript + Tailwind CSS.
+
+Define your entire UI (layout, theming, data bindings) in a single JSON config file. Changes are reflected instantly in development without full page reloads.
+
+## Features
+
+- **Config-first**: Declare pages, layouts, components, and design tokens in `ui.config.json`
+- **Percentage-based scaling**: Enforced no-pixel rule — all layout dimensions use percentages of parent container
+- **Design tokens**: Centralized colors, typography, and spacing scales
+- **Data binding**: Reference named methods to wire data and event handlers
+- **Live editor**: Browser-based visual editor with click-to-select and property panel
+- **Hot reload**: File changes trigger instant UI updates in development
+- **Type-safe**: Full TypeScript support with Zod runtime validation
+
+## Quick start
+
+### 1. Install
+
+```bash
+npm install idml-ui
+```
+
+### 2. Initialize
+
+```bash
+npx idml init
+```
+
+This scaffolds `ui.config.json` and wires up the Next.js plugin.
+
+### 3. Define your UI
+
+Edit `ui.config.json`:
+
+```json
+{
+  "version": "1",
+  "tokens": {
+    "colors": [
+      { "name": "primary", "value": "#1a56db" }
+    ],
+    "typography": [
+      { "name": "heading-xl", "fontSize": "2.25rem", "fontWeight": 700 }
+    ],
+    "spacing": [
+      { "name": "gap-md", "value": "1rem" }
+    ]
+  },
+  "pages": [{
+    "route": "/",
+    "layout": {
+      "type": "flex",
+      "direction": "column",
+      "size": { "width": "100%", "height": "100%" },
+      "children": []
+    },
+    "components": []
+  }]
+}
+```
+
+### 4. Render in your app
+
+```tsx
+import { ConfigProvider, ConfigRenderer } from 'idml-ui';
+import config from './ui.config.json';
+
+export default function Home() {
+  return (
+    <ConfigProvider config={config} methods={[]} components={[]}>
+      <ConfigRenderer page="/" />
+    </ConfigProvider>
+  );
+}
+```
+
+### 5. Open the editor
+
+```bash
+npm run dev
+```
+
+Visit `http://localhost:3000/_isd-editor` to edit your UI visually.
+
+## Architecture
+
+- **3 entry points**:
+  - `idml` (client/browser) — React components for rendering
+  - `idml-ui/server` (Node.js) — Next.js plugin, file watcher, SSE routes
+  - `idml/cli` (binary) — `npx idml init` scaffolding tool
+
+- **No-pixel rule**: All `width`, `height`, `min-*`, `max-*` values must be percentages. This prevents CSS stacking issues and makes layouts predictable.
+
+- **Design tokens**: Define once, use everywhere. Token values are injected as CSS custom properties.
+
+- **Data binding**: Connect components to methods registered via `ConfigProvider.methods`.
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_commander = require("commander");
+
+// src/cli/commands/init.ts
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+
+// src/cli/templates/starter-config.ts
+var STARTER_CONFIG = {
+  $schema: "./node_modules/idml/ui.config.schema.json",
+  version: "1",
+  tokens: {
+    colors: [
+      { name: "primary", value: "#1a56db", darkValue: "#60a5fa" },
+      { name: "surface", value: "#ffffff", darkValue: "#1e1e2e" },
+      { name: "on-surface", value: "#111827", darkValue: "#f9fafb" },
+      { name: "danger", value: "#dc2626", darkValue: "#f87171" }
+    ],
+    typography: [
+      { name: "heading-xl", fontSize: "2.25rem", fontWeight: 700, lineHeight: "1.25" },
+      { name: "body-md", fontSize: "1rem", fontWeight: 400, lineHeight: "1.6" },
+      { name: "label-sm", fontSize: "0.75rem", fontWeight: 500, lineHeight: "1.4" }
+    ],
+    spacing: [
+      { name: "gap-sm", value: "0.5rem" },
+      { name: "gap-md", value: "1rem" },
+      { name: "gap-lg", value: "2rem" }
+    ]
+  },
+  pages: [
+    {
+      route: "/",
+      title: "Home",
+      layout: {
+        type: "flex",
+        direction: "column",
+        gap: "gap-lg",
+        size: { width: "100%", minHeight: "100%" },
+        children: []
+      },
+      components: [
+        {
+          id: "heading",
+          type: "Heading",
+          props: { level: 1, text: "Welcome to idml" },
+          tokenProps: { typography: "heading-xl", color: "on-surface" }
+        },
+        {
+          id: "description",
+          type: "Text",
+          props: { text: "Edit the config to build your UI. Changes appear instantly in the editor." },
+          tokenProps: { color: "on-surface" }
+        }
+      ]
+    }
+  ]
+};
+
+// src/cli/templates/editor-page-template.ts
+var EDITOR_PAGE_TEMPLATE = `import { EditorPage } from 'idml-ui/editor';
+import { notFound } from 'next/navigation';
+
+export default function Page() {
+  if (process.env.NODE_ENV !== 'development') {
+    notFound();
+  }
+
+  return <EditorPage />;
+}
+`;
+
+// src/cli/templates/events-route-template.ts
+var EVENTS_ROUTE_TEMPLATE = `import { startWatcher, addSSEWriter } from 'idml-ui/server';
+
+const CONFIG_PATH = process.env.ISD_UI_CONFIG_PATH!;
+
+startWatcher(CONFIG_PATH);
+
+export async function GET() {
+  const encoder = new TextEncoder();
+
+  const stream = new ReadableStream({
+    start(controller) {
+      controller.enqueue(encoder.encode(': ping\\n\\n'));
+
+      const interval = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(': heartbeat\\n\\n'));
+        } catch {
+          clearInterval(interval);
+        }
+      }, 25_000);
+
+      const unregister = addSSEWriter(controller as any);
+
+      return () => {
+        clearInterval(interval);
+        unregister();
+      };
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      'X-Accel-Buffering': 'no',
+      Connection: 'keep-alive',
+    },
+  });
+}
+
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+`;
+
+// src/cli/templates/config-route-template.ts
+var CONFIG_ROUTE_TEMPLATE = `import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import fs from 'node:fs/promises';
+
+const CONFIG_PATH = process.env.ISD_UI_CONFIG_PATH!;
+
+export async function GET() {
+  try {
+    const raw = await fs.readFile(CONFIG_PATH, 'utf-8');
+    return NextResponse.json(JSON.parse(raw));
+  } catch (err) {
+    return NextResponse.json(
+      { error: \`Failed to read config: \${err instanceof Error ? err.message : String(err)}\` },
+      { status: 500 }
+    );
+  }
+}
+
+export async function POST(req: NextRequest) {
+  if (process.env.NODE_ENV !== 'development') {
+    return NextResponse.json({ error: 'Not available in production' }, { status: 403 });
+  }
+
+  try {
+    const body = await req.json();
+    const tmp = CONFIG_PATH + '.tmp';
+
+    await fs.writeFile(tmp, JSON.stringify(body, null, 2), 'utf-8');
+    await fs.rename(tmp, CONFIG_PATH);
+
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    return NextResponse.json(
+      { error: \`Failed to write config: \${err instanceof Error ? err.message : String(err)}\` },
+      { status: 500 }
+    );
+  }
+}
+
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+`;
+
+// src/cli/commands/init.ts
+async function initCommand(options) {
+  const cwd = process.cwd();
+  const configPath = import_node_path.default.resolve(cwd, options.config);
+  console.log("[idml] Initializing...\n");
+  if (import_node_fs.default.existsSync(configPath)) {
+    console.log(`\u2713 Config already exists at ${options.config}`);
+  } else {
+    import_node_fs.default.writeFileSync(configPath, JSON.stringify(STARTER_CONFIG, null, 2), "utf-8");
+    console.log(`\u2713 Created ${options.config}`);
+  }
+  if (options.editor) {
+    const eventsDir = import_node_path.default.join(cwd, "app", "api", "isd", "events");
+    const configDir = import_node_path.default.join(cwd, "app", "api", "isd", "config");
+    import_node_fs.default.mkdirSync(eventsDir, { recursive: true });
+    import_node_fs.default.mkdirSync(configDir, { recursive: true });
+    const eventsRoutePath = import_node_path.default.join(eventsDir, "route.ts");
+    const configRoutePath = import_node_path.default.join(configDir, "route.ts");
+    if (!import_node_fs.default.existsSync(eventsRoutePath)) {
+      import_node_fs.default.writeFileSync(eventsRoutePath, EVENTS_ROUTE_TEMPLATE, "utf-8");
+      console.log(`\u2713 Created app/api/isd/events/route.ts`);
+    }
+    if (!import_node_fs.default.existsSync(configRoutePath)) {
+      import_node_fs.default.writeFileSync(configRoutePath, CONFIG_ROUTE_TEMPLATE, "utf-8");
+      console.log(`\u2713 Created app/api/isd/config/route.ts`);
+    }
+    const editorDir = import_node_path.default.join(cwd, "app", "isd", "editor");
+    import_node_fs.default.mkdirSync(editorDir, { recursive: true });
+    const editorPagePath = import_node_path.default.join(editorDir, "page.tsx");
+    if (!import_node_fs.default.existsSync(editorPagePath)) {
+      import_node_fs.default.writeFileSync(editorPagePath, EDITOR_PAGE_TEMPLATE, "utf-8");
+      console.log(`\u2713 Created app/isd/editor/page.tsx`);
+    }
+  }
+  const nextConfigPath = import_node_path.default.resolve(cwd, "next.config.ts");
+  const nextConfigJsPath = import_node_path.default.resolve(cwd, "next.config.js");
+  const targetPath = import_node_fs.default.existsSync(nextConfigPath) ? nextConfigPath : import_node_fs.default.existsSync(nextConfigJsPath) ? nextConfigJsPath : null;
+  if (!targetPath) {
+    console.warn(
+      '\n\u26A0 No next.config.ts/js found. Create one and manually add:\n  import { withUIConfig } from "idml-ui/server";\n  export default withUIConfig()({});\n'
+    );
+  } else {
+    const existing = import_node_fs.default.readFileSync(targetPath, "utf-8");
+    if (!existing.includes("withUIConfig")) {
+      const importLine = `import { withUIConfig } from 'idml-ui/server';
+`;
+      const isJs = targetPath.endsWith(".js");
+      let patched = existing;
+      if (patched.includes("export default")) {
+        patched = patched.replace(
+          /export default\s+({|nextConfig)/,
+          `export default withUIConfig({ configPath: '${options.config}' })($1`
+        );
+        if (patched.includes("export default withUIConfig") && patched.includes("nextConfig;")) {
+          patched = patched.replace(/nextConfig;/, "nextConfig);");
+        } else if (patched.includes("export default withUIConfig") && patched.includes("{")) {
+          const lines = patched.split("\n");
+          const lastNonEmptyLine = lines[lines.length - 2];
+          if (lastNonEmptyLine?.trim() === "}") {
+            patched = patched.replace(/^(\s*})(\s*)$/, "$1);$2", "m");
+          }
+        }
+      } else {
+        patched = patched + "\nexport default withUIConfig()({});\n";
+      }
+      import_node_fs.default.writeFileSync(targetPath, importLine + patched, "utf-8");
+      console.log(`\u2713 Patched next.config.${isJs ? "js" : "ts"} with withUIConfig`);
+    } else {
+      console.log(`\u2713 next.config already contains withUIConfig`);
+    }
+  }
+  const tailwindPath = import_node_path.default.resolve(cwd, "tailwind.config.ts");
+  const tailwindJsPath = import_node_path.default.resolve(cwd, "tailwind.config.js");
+  const tailwindTarget = import_node_fs.default.existsSync(tailwindPath) ? tailwindPath : import_node_fs.default.existsSync(tailwindJsPath) ? tailwindJsPath : null;
+  if (tailwindTarget) {
+    const tailwindContent = import_node_fs.default.readFileSync(tailwindTarget, "utf-8");
+    const isdPath = "./node_modules/idml/dist/**/*.{js,mjs}";
+    if (!tailwindContent.includes("idml")) {
+      const patched = tailwindContent.replace(
+        /content:\s*\[/,
+        `content: [
+    '${isdPath}',`
+      );
+      import_node_fs.default.writeFileSync(tailwindTarget, patched, "utf-8");
+      console.log(`\u2713 Updated tailwind.config.ts content array`);
+    }
+  }
+  console.log("\n\u2705 idml initialized!\n");
+  console.log("Next steps:");
+  console.log("  1. npm run dev");
+  console.log("  2. Visit http://localhost:3000/_isd-editor");
+  console.log("  3. Click on components in the preview to edit them");
+  console.log("\nDocumentation: https://github.com/...\n");
+}
+
+// src/cli.ts
+var program = new import_commander.Command();
+program.name("idml").description("UI configuration framework for Next.js + Tailwind").version("0.1.0");
+program.command("init").description("Scaffold ui.config.json and wire up withUIConfig in next.config.ts").option("--config <path>", "Path for the config file", "./ui.config.json").option("--no-editor", "Disable the visual editor").action(async (options) => {
+  try {
+    await initCommand(options);
+  } catch (err) {
+    console.error("[idml] Error:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+});
+program.parse(process.argv);