@carlonicora/nextjs-jsonapi 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",
@@ -8,6 +8,9 @@
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "generate-web-module": "./dist/scripts/generate-web-module/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -81,16 +84,18 @@
     }
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc -p scripts/generate-web-module/tsconfig.json",
     "dev": "tsup --watch",
     "clean": "rm -rf dist",
     "lint": "eslint \"src/**/*.ts\" --fix",
     "format": "prettier --write \"src/**/*.ts\"",
-    "prepublishOnly": "pnpm build"
+    "prepublishOnly": "pnpm build",
+    "generate-web-module": "node dist/scripts/generate-web-module/index.js"
   },
   "files": [
     "dist",
     "src",
+    "scripts",
     "README.md"
   ],
   "peerDependencies": {
@@ -113,9 +118,10 @@
     }
   },
   "dependencies": {
-    "@blocknote/core": "^0.44.0",
-    "@blocknote/react": "^0.44.0",
-    "@blocknote/shadcn": "^0.44.0",
+    "commander": "^13.1.0",
+    "@blocknote/core": "^0.44.2",
+    "@blocknote/react": "^0.44.2",
+    "@blocknote/shadcn": "^0.44.2",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -151,10 +157,10 @@
     "d3": "^7.9.0",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "jotai": "^2.15.2",
-    "lucide-react": "^0.556.0",
+    "jotai": "^2.16.0",
+    "lucide-react": "^0.561.0",
     "next-themes": "^0.4.6",
-    "react-day-picker": "^9.11.3",
+    "react-day-picker": "^9.12.0",
     "react-dropzone": "^14.3.8",
     "react-hook-form": "^7.68.0",
     "react-markdown": "^10.1.0",
@@ -165,7 +171,7 @@
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.4.0",
     "uuid": "^13.0.0",
-    "vaul": "^1.1.0",
+    "vaul": "^1.1.2",
     "zod": "^4.1.13"
   },
   "devDependencies": {
@@ -177,22 +183,22 @@
     "@eslint/js": "^9.39.1",
     "@tanstack/react-table": "^8.21.3",
     "@types/d3": "^7.4.3",
-    "@types/node": "^22.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.48.1",
-    "@typescript-eslint/parser": "^8.48.1",
+    "@types/node": "^25.0.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.49.0",
+    "@typescript-eslint/parser": "^8.49.0",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "globals": "^16.5.0",
-    "next": "^16.0.0",
-    "next-intl": "^4.1.0",
+    "next": "^16.0.10",
+    "next-intl": "^4.5.8",
     "prettier": "^3.7.4",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.0"
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
   },
   "keywords": [
     "nextjs",

package/scripts/generate-web-module/generator.ts

@@ -0,0 +1,363 @@
+/**
+ * Frontend Module Generator
+ *
+ * Main orchestrator for generating frontend modules from JSON schema.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import {
+  JsonModuleDefinition,
+  FrontendTemplateData,
+  GeneratedFile,
+  GenerateWebModuleOptions,
+} from "./types";
+import { transformNames, toCamelCase, pluralize, toTitleCase } from "./transformers/name-transformer";
+import { detectExtendsContent } from "./transformers/parent-detector";
+import { mapFields, filterInheritedFields } from "./transformers/field-mapper";
+import { resolveRelationships, generateServiceMethods } from "./transformers/relationship-resolver";
+import { buildImportStatements, buildFilePaths } from "./transformers/import-resolver";
+import { generateI18nKeys } from "./transformers/i18n-generator";
+import { parseAndValidate, validationPassed } from "./validators/json-schema-validator";
+import {
+  generateInterfaceTemplate,
+  generateModelTemplate,
+  generateServiceTemplate,
+  generateFieldsTemplate,
+  generateEditorTemplate,
+  generateDeleterTemplate,
+  generateSelectorTemplate,
+  generateMultiSelectorTemplate,
+  generateListTemplate,
+  generateDetailsTemplate,
+  generateContentTemplate,
+  generateContainerTemplate,
+  generateListContainerTemplate,
+  generateContextTemplate,
+  generateTableHookTemplate,
+  generateModuleTemplate,
+  generateListPageTemplate,
+  generateDetailPageTemplate,
+} from "./templates";
+import { writeFiles, printResults, updateBootstrapper, updateI18n } from "./utils";
+
+/**
+ * Generate all frontend module files from JSON schema
+ *
+ * @param options - Generator options
+ * @returns True if generation succeeded
+ */
+export async function generateWebModule(options: GenerateWebModuleOptions): Promise<boolean> {
+  const { jsonPath, dryRun = false, force = false, noRegister = false } = options;
+
+  console.log(`\n🔧 Frontend Module Generator`);
+  console.log(`   JSON Schema: ${jsonPath}`);
+  console.log(`   Dry Run: ${dryRun}`);
+  console.log(`   Force: ${force}`);
+  console.log(`   No Register: ${noRegister}`);
+
+  // Step 1: Validate JSON schema
+  console.log("\n📋 Validating JSON schema...");
+  const validation = parseAndValidate(jsonPath);
+
+  if (!validationPassed(validation)) {
+    console.error("\n❌ Validation failed:");
+    validation.errors.forEach((e) => console.error(`   - ${e}`));
+    return false;
+  }
+
+  if (validation.warnings.length > 0) {
+    console.log("\n⚠️  Validation warnings (non-blocking):");
+    validation.warnings.forEach((w) => console.log(`   - ${w}`));
+  }
+
+  const schema = validation.data!;
+  console.log(`   ✅ Schema valid: ${schema.moduleName}`);
+
+  // Step 2: Build template data
+  console.log("\n🔨 Building template data...");
+  const templateData = buildTemplateData(schema);
+  console.log(`   Module: ${templateData.names.pascalCase}`);
+  console.log(`   Target: ${templateData.targetDir}`);
+  console.log(`   Extends Content: ${templateData.extendsContent}`);
+  console.log(`   Fields: ${templateData.fields.length}`);
+  console.log(`   Relationships: ${templateData.relationships.length}`);
+
+  // Step 3: Generate all files
+  console.log("\n📝 Generating files...");
+  const files = generateAllFiles(templateData, schema);
+  console.log(`   Generated ${files.length} file templates`);
+
+  // Step 4: Determine web base path
+  const webBasePath = findWebBasePath(jsonPath);
+  if (!webBasePath) {
+    console.error("\n❌ Could not determine web app base path");
+    return false;
+  }
+  console.log(`   Web base path: ${webBasePath}`);
+
+  // Step 5: Write files
+  console.log("\n💾 Writing files...");
+  const results = writeFiles(files, { dryRun, force });
+  printResults(results);
+
+  // Step 6: Update Bootstrapper (unless --no-register)
+  if (!noRegister) {
+    console.log("\n🔧 Updating Bootstrapper.ts...");
+    const bootstrapResult = updateBootstrapper(templateData, webBasePath, dryRun);
+    console.log(`   ${bootstrapResult.success ? "✅" : "❌"} ${bootstrapResult.message}`);
+  }
+
+  // Step 7: Update i18n (unless --no-register)
+  if (!noRegister) {
+    console.log("\n🌐 Updating messages/en.json...");
+    const i18nResult = updateI18n(templateData, webBasePath, dryRun);
+    console.log(`   ${i18nResult.success ? "✅" : "❌"} ${i18nResult.message}`);
+  }
+
+  console.log("\n✅ Generation complete!");
+
+  if (dryRun) {
+    console.log("\n📝 This was a dry run. No files were actually written.");
+    console.log("   Remove --dry-run to generate files.");
+  }
+
+  return true;
+}
+
+/**
+ * Build template data from JSON schema
+ */
+function buildTemplateData(schema: JsonModuleDefinition): FrontendTemplateData {
+  const names = transformNames(schema.moduleName, schema.endpointName);
+  const targetDir = schema.targetDir as "features" | "foundations";
+  const extendsContent = detectExtendsContent(schema.fields);
+
+  // Map fields
+  const allFields = mapFields(schema.fields, names.camelCase);
+
+  // Get inherited fields to filter out for forms (Content fields are handled specially)
+  const inheritedFields = extendsContent ? ["name", "tldr", "abstract", "content"] : [];
+  const fields = filterInheritedFields(allFields, inheritedFields);
+
+  // Resolve relationships
+  const relationships = resolveRelationships(schema.relationships);
+  const relationshipServiceMethods = generateServiceMethods(relationships);
+
+  // Build imports
+  const imports = buildImportStatements(relationships, extendsContent);
+
+  // Generate i18n keys
+  const i18nKeys = generateI18nKeys(names, fields, relationships);
+
+  // Build table field names
+  const tableFieldNames = buildTableFieldNames(schema, extendsContent);
+
+  return {
+    names,
+    moduleId: schema.moduleId,
+    endpoint: schema.endpointName,
+    targetDir,
+    extendsContent,
+    fields: allFields, // Keep all fields for interface generation
+    relationships,
+    i18nKeys,
+    imports,
+    tableFieldNames,
+    relationshipServiceMethods,
+  };
+}
+
+/**
+ * Build field names for table display
+ */
+function buildTableFieldNames(schema: JsonModuleDefinition, extendsContent: boolean): string[] {
+  const fieldNames: string[] = [`${toCamelCase(schema.moduleName)}Id`];
+
+  // Add name for all modules
+  fieldNames.push("name");
+
+  // Add authors for content modules
+  if (extendsContent) {
+    fieldNames.push("authors");
+  }
+
+  // Add custom fields (excluding certain ones)
+  schema.fields.forEach((f) => {
+    if (!["id", "name", "tldr", "abstract", "content", "createdAt", "updatedAt"].includes(f.name)) {
+      fieldNames.push(f.name);
+    }
+  });
+
+  // Add standard date fields
+  fieldNames.push("createdAt", "updatedAt");
+
+  return fieldNames;
+}
+
+/**
+ * Generate all module files
+ */
+function generateAllFiles(data: FrontendTemplateData, schema: JsonModuleDefinition): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const paths = buildFilePaths(data, findWebBasePath(""));
+
+  // Data layer (4 files)
+  files.push({
+    path: paths.interface,
+    content: generateInterfaceTemplate(data),
+    type: "data",
+  });
+
+  files.push({
+    path: paths.model,
+    content: generateModelTemplate(data),
+    type: "data",
+  });
+
+  files.push({
+    path: paths.service,
+    content: generateServiceTemplate(data),
+    type: "data",
+  });
+
+  files.push({
+    path: paths.fields,
+    content: generateFieldsTemplate(data),
+    type: "data",
+  });
+
+  // Form components (4 files)
+  files.push({
+    path: paths.editor,
+    content: generateEditorTemplate(data),
+    type: "component",
+  });
+
+  files.push({
+    path: paths.deleter,
+    content: generateDeleterTemplate(data),
+    type: "component",
+  });
+
+  files.push({
+    path: paths.selector,
+    content: generateSelectorTemplate(data),
+    type: "component",
+  });
+
+  files.push({
+    path: paths.multiSelector,
+    content: generateMultiSelectorTemplate(data),
+    type: "component",
+  });
+
+  // Display components (4-5 files)
+  files.push({
+    path: paths.list,
+    content: generateListTemplate(data),
+    type: "component",
+  });
+
+  files.push({
+    path: paths.details,
+    content: generateDetailsTemplate(data),
+    type: "component",
+  });
+
+  // Content component only for Content-extending modules
+  const contentTemplate = generateContentTemplate(data);
+  if (contentTemplate) {
+    files.push({
+      path: paths.content,
+      content: contentTemplate,
+      type: "component",
+    });
+  }
+
+  files.push({
+    path: paths.container,
+    content: generateContainerTemplate(data),
+    type: "component",
+  });
+
+  files.push({
+    path: paths.listContainer,
+    content: generateListContainerTemplate(data),
+    type: "component",
+  });
+
+  // Context & hooks (2 files)
+  files.push({
+    path: paths.context,
+    content: generateContextTemplate(data),
+    type: "context",
+  });
+
+  files.push({
+    path: paths.tableHook,
+    content: generateTableHookTemplate(data),
+    type: "hook",
+  });
+
+  // Module (1 file)
+  files.push({
+    path: paths.module,
+    content: generateModuleTemplate(data),
+    type: "module",
+  });
+
+  // Pages (2 files)
+  files.push({
+    path: paths.listPage,
+    content: generateListPageTemplate(data),
+    type: "page",
+  });
+
+  files.push({
+    path: paths.detailPage,
+    content: generateDetailPageTemplate(data),
+    type: "page",
+  });
+
+  return files;
+}
+
+/**
+ * Find the web app base path from the JSON path
+ * Assumes JSON is in /structure folder and web app is in /apps/web
+ */
+function findWebBasePath(jsonPath: string): string {
+  // Try to find apps/web relative to current working directory
+  const cwd = process.cwd();
+
+  // Check if we're in the monorepo root
+  if (fs.existsSync(path.join(cwd, "apps/web"))) {
+    return cwd;
+  }
+
+  // Check if we're in packages/nextjs-jsonapi
+  if (fs.existsSync(path.join(cwd, "../../apps/web"))) {
+    return path.join(cwd, "../..");
+  }
+
+  // Try to derive from jsonPath
+  if (jsonPath) {
+    const resolved = path.resolve(jsonPath);
+    // Look for monorepo root by finding apps/web
+    let current = path.dirname(resolved);
+    for (let i = 0; i < 10; i++) {
+      if (fs.existsSync(path.join(current, "apps/web"))) {
+        return current;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+
+  // Default to current directory
+  return cwd;
+}
+
+export default generateWebModule;

package/scripts/generate-web-module/index.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Frontend Module Generator CLI
+ *
+ * Generates Next.js frontend modules from JSON schema definitions.
+ *
+ * Usage:
+ *   pnpm generate-web-module <json-path> [options]
+ *
+ * Options:
+ *   --dry-run      Preview without writing files
+ *   --force        Overwrite existing files
+ *   --no-register  Skip Bootstrapper and i18n updates
+ */
+
+import { Command } from "commander";
+import * as path from "path";
+import { generateWebModule } from "./generator";
+
+const program = new Command();
+
+program
+  .name("generate-web-module")
+  .description("Generate Next.js frontend module from JSON schema")
+  .version("1.0.0")
+  .argument("<json-path>", "Path to JSON schema file (relative or absolute)")
+  .option("-d, --dry-run", "Preview files without writing them", false)
+  .option("-f, --force", "Overwrite existing files", false)
+  .option("-n, --no-register", "Skip Bootstrapper.ts and i18n updates", false)
+  .action(async (jsonPath: string, options: { dryRun: boolean; force: boolean; register: boolean }) => {
+    // Resolve path
+    const resolvedPath = path.isAbsolute(jsonPath) ? jsonPath : path.resolve(process.cwd(), jsonPath);
+
+    try {
+      const success = await generateWebModule({
+        jsonPath: resolvedPath,
+        dryRun: options.dryRun,
+        force: options.force,
+        noRegister: !options.register,
+      });
+
+      process.exit(success ? 0 : 1);
+    } catch (error) {
+      console.error("\n❌ Error:", error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/scripts/generate-web-module/templates/components/container.template.ts

@@ -0,0 +1,129 @@
+/**
+ * Container Template
+ *
+ * Generates {Module}Container.tsx component for displaying item detail page.
+ */
+
+import { FrontendTemplateData } from "../../types/template-data.interface";
+
+/**
+ * Generate the container component file content
+ *
+ * @param data - Frontend template data
+ * @returns Generated file content
+ */
+export function generateContainerTemplate(data: FrontendTemplateData): string {
+  const { names, extendsContent } = data;
+
+  // Content-extending modules get full tabs with relevant content/users
+  if (extendsContent) {
+    return generateContentContainerTemplate(data);
+  }
+
+  // Non-content modules get simpler container
+  return generateSimpleContainerTemplate(data);
+}
+
+/**
+ * Generate container for Content-extending modules
+ */
+function generateContentContainerTemplate(data: FrontendTemplateData): string {
+  const { names } = data;
+
+  return `"use client";
+
+import ${names.pascalCase}Content from "@/features/${data.targetDir}/${names.kebabCase}/components/details/${names.pascalCase}Content";
+import ${names.pascalCase}Details from "@/features/${data.targetDir}/${names.kebabCase}/components/details/${names.pascalCase}Details";
+import { use${names.pascalCase}Context } from "@/features/${data.targetDir}/${names.kebabCase}/contexts/${names.pascalCase}Context";
+import { ${names.pascalCase}Interface } from "@/features/${data.targetDir}/${names.kebabCase}/data/${names.pascalCase}Interface";
+import {
+  AllowedUsersDetails,
+  PageContentContainer,
+  RelevantContentsList,
+  RelevantUsersList,
+} from "@carlonicora/nextjs-jsonapi/components";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@carlonicora/nextjs-jsonapi/shadcnui";
+import { useTranslations } from "next-intl";
+
+type ${names.pascalCase}ContainerProps = {
+  ${names.camelCase}: ${names.pascalCase}Interface;
+};
+
+function ${names.pascalCase}ContainerInternal({ ${names.camelCase} }: ${names.pascalCase}ContainerProps) {
+  const t = useTranslations();
+
+  return (
+    <PageContentContainer
+      details={<${names.pascalCase}Details />}
+      footer={
+        <AllowedUsersDetails showTitle content={${names.camelCase}} />
+      }
+      content={
+        <Tabs defaultValue={\`${names.camelCase}\`}>
+          <TabsList className="mb-4">
+            <TabsTrigger value="${names.camelCase}">{t(\`types.${names.pluralCamel}\`, { count: 1 })}</TabsTrigger>
+            <TabsTrigger value="contents">{t(\`generic.relevant\`)}</TabsTrigger>
+            <TabsTrigger value="users">{t(\`generic.relevant_users\`)}</TabsTrigger>
+          </TabsList>
+          <TabsContent value="${names.camelCase}">
+            <${names.pascalCase}Content />
+          </TabsContent>
+          <TabsContent value="contents">
+            <RelevantContentsList id={${names.camelCase}.id} />
+          </TabsContent>
+          <TabsContent value="users">
+            <RelevantUsersList id={${names.camelCase}.id} />
+          </TabsContent>
+        </Tabs>
+      }
+    />
+  );
+}
+
+export default function ${names.pascalCase}Container() {
+  const { ${names.camelCase} } = use${names.pascalCase}Context();
+  if (!${names.camelCase}) return null;
+
+  return <${names.pascalCase}ContainerInternal ${names.camelCase}={${names.camelCase}} />;
+}
+`;
+}
+
+/**
+ * Generate container for non-Content modules
+ */
+function generateSimpleContainerTemplate(data: FrontendTemplateData): string {
+  const { names } = data;
+
+  return `"use client";
+
+import ${names.pascalCase}Details from "@/features/${data.targetDir}/${names.kebabCase}/components/details/${names.pascalCase}Details";
+import { use${names.pascalCase}Context } from "@/features/${data.targetDir}/${names.kebabCase}/contexts/${names.pascalCase}Context";
+import { ${names.pascalCase}Interface } from "@/features/${data.targetDir}/${names.kebabCase}/data/${names.pascalCase}Interface";
+import { PageContentContainer } from "@carlonicora/nextjs-jsonapi/components";
+
+type ${names.pascalCase}ContainerProps = {
+  ${names.camelCase}: ${names.pascalCase}Interface;
+};
+
+function ${names.pascalCase}ContainerInternal({ ${names.camelCase} }: ${names.pascalCase}ContainerProps) {
+  return (
+    <PageContentContainer
+      details={<${names.pascalCase}Details />}
+      content={
+        <div className="flex w-full flex-col gap-y-4">
+          {/* Add custom content sections here */}
+        </div>
+      }
+    />
+  );
+}
+
+export default function ${names.pascalCase}Container() {
+  const { ${names.camelCase} } = use${names.pascalCase}Context();
+  if (!${names.camelCase}) return null;
+
+  return <${names.pascalCase}ContainerInternal ${names.camelCase}={${names.camelCase}} />;
+}
+`;
+}

package/scripts/generate-web-module/templates/components/content.template.ts

@@ -0,0 +1,40 @@
+/**
+ * Content Template
+ *
+ * Generates {Module}Content.tsx component for displaying BlockNote content.
+ * Only generated for Content-extending modules.
+ */
+
+import { FrontendTemplateData } from "../../types/template-data.interface";
+
+/**
+ * Generate the content display component file content
+ *
+ * @param data - Frontend template data
+ * @returns Generated file content or null if not Content-extending
+ */
+export function generateContentTemplate(data: FrontendTemplateData): string | null {
+  const { names, extendsContent } = data;
+
+  // Only generate for Content-extending modules
+  if (!extendsContent) {
+    return null;
+  }
+
+  return `"use client";
+
+import { use${names.pascalCase}Context } from "@/features/${data.targetDir}/${names.kebabCase}/contexts/${names.pascalCase}Context";
+import { BlockNoteEditorContainer } from "@carlonicora/nextjs-jsonapi/components";
+import { Card } from "@carlonicora/nextjs-jsonapi/shadcnui";
+
+export default function ${names.pascalCase}Content() {
+  const { ${names.camelCase} } = use${names.pascalCase}Context();
+
+  return (
+    <Card className="flex w-full flex-col p-4">
+      <BlockNoteEditorContainer id={${names.camelCase}.id} type="${names.camelCase}" initialContent={${names.camelCase}.content} />
+    </Card>
+  );
+}
+`;
+}