@carlonicora/nextjs-jsonapi 1.2.0 → 1.3.1

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

@@ -0,0 +1,199 @@
+/**
+ * i18n Generator
+ *
+ * Generates internationalization keys and messages for a module.
+ */
+
+import { FrontendField, FrontendRelationship, I18nKeySet, NameTransforms } from "../types/template-data.interface";
+import { toTitleCase, pluralize, toCamelCase, toKebabCase } from "./name-transformer";
+
+/**
+ * Generate complete i18n key set for a module
+ *
+ * @param names - Name transforms
+ * @param fields - Array of frontend fields
+ * @param relationships - Array of frontend relationships
+ * @returns i18n key set
+ */
+export function generateI18nKeys(
+  names: NameTransforms,
+  fields: FrontendField[],
+  relationships: FrontendRelationship[]
+): I18nKeySet {
+  const lowerModuleName = names.camelCase;
+
+  // Generate field keys
+  const fieldKeys: I18nKeySet["fields"] = {};
+  fields.forEach((field) => {
+    fieldKeys[field.name] = {
+      label: toTitleCase(field.name),
+      placeholder: `Enter ${toTitleCase(field.name).toLowerCase()}`,
+      error: `${toTitleCase(field.name)} is required`,
+    };
+  });
+
+  // Generate relationship keys
+  const relationshipKeys: I18nKeySet["relationships"] = {};
+  relationships.forEach((rel) => {
+    const effectiveName = rel.variant || rel.name;
+    const effectiveKey = toCamelCase(effectiveName);
+    relationshipKeys[effectiveKey] = {
+      label: toTitleCase(effectiveName),
+      placeholder: `Select ${toTitleCase(effectiveName).toLowerCase()}`,
+      error: `${toTitleCase(effectiveName)} is required`,
+      list: pluralize(toTitleCase(rel.name)),
+    };
+  });
+
+  // Generate type keys
+  const singularTitle = names.titleCase;
+  const pluralTitle = names.pluralTitleCase;
+
+  return {
+    moduleName: lowerModuleName,
+    fields: fieldKeys,
+    relationships: relationshipKeys,
+    type: {
+      singular: singularTitle,
+      plural: pluralTitle,
+      icuPlural: `{count, plural, =1 {${singularTitle}} other {${pluralTitle}}}`,
+    },
+  };
+}
+
+/**
+ * Build the i18n message object to merge into en.json
+ *
+ * @param i18nKeys - i18n key set
+ * @returns Object structure for en.json
+ */
+export function buildI18nMessages(i18nKeys: I18nKeySet): Record<string, any> {
+  return {
+    features: {
+      [i18nKeys.moduleName]: {
+        fields: i18nKeys.fields,
+        relationships: i18nKeys.relationships,
+      },
+    },
+    types: {
+      [i18nKeys.moduleName + "s"]: i18nKeys.type.icuPlural,
+    },
+  };
+}
+
+/**
+ * Get the translation key path for a field label
+ *
+ * @param moduleName - Module name (lowercase)
+ * @param fieldName - Field name
+ * @returns Translation key path
+ */
+export function getFieldLabelKey(moduleName: string, fieldName: string): string {
+  return `features.${moduleName}.fields.${fieldName}.label`;
+}
+
+/**
+ * Get the translation key path for a field placeholder
+ *
+ * @param moduleName - Module name (lowercase)
+ * @param fieldName - Field name
+ * @returns Translation key path
+ */
+export function getFieldPlaceholderKey(moduleName: string, fieldName: string): string {
+  return `features.${moduleName}.fields.${fieldName}.placeholder`;
+}
+
+/**
+ * Get the translation key path for a field error
+ *
+ * @param moduleName - Module name (lowercase)
+ * @param fieldName - Field name
+ * @returns Translation key path
+ */
+export function getFieldErrorKey(moduleName: string, fieldName: string): string {
+  return `features.${moduleName}.fields.${fieldName}.error`;
+}
+
+/**
+ * Get the translation key path for type pluralization
+ *
+ * @param pluralKebab - Plural kebab-case name
+ * @returns Translation key path
+ */
+export function getTypeKey(pluralKebab: string): string {
+  return `types.${pluralKebab}`;
+}
+
+/**
+ * Generate translation call for use in templates
+ *
+ * @param keyPath - Full translation key path
+ * @param params - Optional parameters for ICU messages
+ * @returns Translation function call as string
+ */
+export function generateTranslationCall(
+  keyPath: string,
+  params?: Record<string, any>
+): string {
+  if (params) {
+    const paramStr = JSON.stringify(params);
+    return `t(\`${keyPath}\`, ${paramStr})`;
+  }
+  return `t(\`${keyPath}\`)`;
+}
+
+/**
+ * Merge i18n messages into existing messages object
+ * This performs a deep merge, preserving existing keys
+ *
+ * @param existing - Existing messages object
+ * @param newMessages - New messages to merge
+ * @returns Merged messages object
+ */
+export function mergeI18nMessages(
+  existing: Record<string, any>,
+  newMessages: Record<string, any>
+): Record<string, any> {
+  const result = { ...existing };
+
+  function deepMerge(target: Record<string, any>, source: Record<string, any>): void {
+    for (const key of Object.keys(source)) {
+      if (
+        source[key] &&
+        typeof source[key] === "object" &&
+        !Array.isArray(source[key])
+      ) {
+        if (!target[key]) {
+          target[key] = {};
+        }
+        deepMerge(target[key], source[key]);
+      } else {
+        target[key] = source[key];
+      }
+    }
+  }
+
+  deepMerge(result, newMessages);
+  return result;
+}
+
+/**
+ * Sort object keys alphabetically (for consistent output)
+ *
+ * @param obj - Object to sort
+ * @returns New object with sorted keys
+ */
+export function sortObjectKeys(obj: Record<string, any>): Record<string, any> {
+  const sorted: Record<string, any> = {};
+  const keys = Object.keys(obj).sort();
+
+  for (const key of keys) {
+    if (obj[key] && typeof obj[key] === "object" && !Array.isArray(obj[key])) {
+      sorted[key] = sortObjectKeys(obj[key]);
+    } else {
+      sorted[key] = obj[key];
+    }
+  }
+
+  return sorted;
+}

package/scripts/generate-web-module/transformers/import-resolver.ts

@@ -0,0 +1,250 @@
+/**
+ * Import Resolver
+ *
+ * Builds import paths for selectors, models, and related modules.
+ */
+
+import { FrontendRelationship, ImportStatements, FrontendTemplateData } from "../types/template-data.interface";
+import { AUTHOR_VARIANT } from "../types/field-mapping.types";
+import { toKebabCase, pluralize } from "./name-transformer";
+
+/**
+ * Build all import statements needed for a module
+ *
+ * @param relationships - Array of frontend relationships
+ * @param extendsContent - Whether the module extends Content
+ * @returns Import statements grouped by category
+ */
+export function buildImportStatements(
+  relationships: FrontendRelationship[],
+  extendsContent: boolean
+): ImportStatements {
+  return {
+    models: buildModelImports(relationships),
+    selectors: buildSelectorImports(relationships),
+    library: buildLibraryImports(extendsContent),
+  };
+}
+
+/**
+ * Build model/interface import statements
+ *
+ * @param relationships - Array of frontend relationships
+ * @returns Array of import statements for models
+ */
+export function buildModelImports(relationships: FrontendRelationship[]): string[] {
+  const imports: string[] = [];
+
+  relationships.forEach((rel) => {
+    // Import interface for relationships
+    imports.push(
+      `import { ${rel.interfaceName} } from "${rel.interfaceImportPath}";`
+    );
+  });
+
+  return [...new Set(imports)]; // Deduplicate
+}
+
+/**
+ * Build selector component import statements
+ *
+ * @param relationships - Array of frontend relationships
+ * @returns Array of import statements for selectors
+ */
+export function buildSelectorImports(relationships: FrontendRelationship[]): string[] {
+  const imports: string[] = [];
+
+  relationships.forEach((rel) => {
+    // Skip author - handled specially or auto-set
+    if (rel.variant === AUTHOR_VARIANT) {
+      return;
+    }
+
+    const componentName = rel.single ? `${rel.name}Selector` : `${rel.name}MultiSelector`;
+    imports.push(
+      `import ${componentName} from "${rel.importPath}";`
+    );
+  });
+
+  return [...new Set(imports)]; // Deduplicate
+}
+
+/**
+ * Build library import statements
+ *
+ * @param extendsContent - Whether the module extends Content
+ * @returns Array of import statements for library
+ */
+export function buildLibraryImports(extendsContent: boolean): string[] {
+  const imports: string[] = [];
+
+  // Core imports always needed
+  imports.push(
+    `import { AbstractApiData } from "@carlonicora/nextjs-jsonapi/core";`
+  );
+
+  // Content import if extending
+  if (extendsContent) {
+    imports.push(
+      `import { Content, ContentInterface, ContentInput } from "@carlonicora/nextjs-jsonapi/core";`
+    );
+  }
+
+  return imports;
+}
+
+/**
+ * Build import path for a module's own files
+ *
+ * @param targetDir - Target directory
+ * @param moduleName - Module name (PascalCase)
+ * @param fileName - File name without extension
+ * @returns Import path
+ */
+export function buildModuleImportPath(
+  targetDir: string,
+  moduleName: string,
+  fileName: string
+): string {
+  const kebab = toKebabCase(moduleName);
+  return `@/features/${targetDir}/${kebab}/data/${fileName}`;
+}
+
+/**
+ * Build import path for a related module's selector
+ *
+ * @param rel - Frontend relationship
+ * @returns Import path for selector
+ */
+export function buildSelectorImportPath(rel: FrontendRelationship): string {
+  const componentName = rel.single ? `${rel.name}Selector` : `${rel.name}MultiSelector`;
+  return `@/features/${rel.directory}/${rel.modelKebab}/components/forms/${componentName}`;
+}
+
+/**
+ * Get the web base path for generated files
+ *
+ * @param targetDir - Target directory (features or foundations)
+ * @param moduleName - Module name (PascalCase)
+ * @returns Base path for generated files
+ */
+export function getWebBasePath(targetDir: string, moduleName: string): string {
+  const kebab = toKebabCase(moduleName);
+  return `apps/web/src/features/${targetDir}/${kebab}`;
+}
+
+/**
+ * Get the page path for generated pages
+ *
+ * @param pluralKebab - Plural kebab-case name (e.g., "comments")
+ * @returns Base path for page files
+ */
+export function getPageBasePath(pluralKebab: string): string {
+  return `apps/web/src/app/[locale]/(main)/(features)/${pluralKebab}`;
+}
+
+/**
+ * File paths interface
+ */
+export interface ModuleFilePaths {
+  interface: string;
+  model: string;
+  service: string;
+  fields: string;
+  editor: string;
+  deleter: string;
+  selector: string;
+  multiSelector: string;
+  list: string;
+  details: string;
+  content: string;
+  container: string;
+  listContainer: string;
+  context: string;
+  tableHook: string;
+  module: string;
+  listPage: string;
+  detailPage: string;
+}
+
+/**
+ * Build all file paths for a module from template data
+ *
+ * @param data - Frontend template data
+ * @param rootPath - Root path for the monorepo (optional, defaults to "")
+ * @returns Object with all file paths
+ */
+export function buildFilePaths(
+  data: FrontendTemplateData,
+  rootPath: string = ""
+): ModuleFilePaths {
+  const { names, targetDir } = data;
+  const prefix = rootPath ? `${rootPath}/` : "";
+  const basePath = `${prefix}apps/web/src/features/${targetDir}/${names.kebabCase}`;
+  const pagePath = `${prefix}apps/web/src/app/[locale]/(main)/(features)/${names.pluralKebab}`;
+
+  return {
+    // Data layer
+    interface: `${basePath}/data/${names.pascalCase}Interface.ts`,
+    model: `${basePath}/data/${names.pascalCase}.ts`,
+    service: `${basePath}/data/${names.pascalCase}Service.ts`,
+    fields: `${basePath}/data/${names.pascalCase}Fields.ts`,
+
+    // Components
+    editor: `${basePath}/components/forms/${names.pascalCase}Editor.tsx`,
+    deleter: `${basePath}/components/forms/${names.pascalCase}Deleter.tsx`,
+    selector: `${basePath}/components/forms/${names.pascalCase}Selector.tsx`,
+    multiSelector: `${basePath}/components/forms/${names.pascalCase}MultiSelector.tsx`,
+    list: `${basePath}/components/lists/${names.pascalCase}List.tsx`,
+    details: `${basePath}/components/details/${names.pascalCase}Details.tsx`,
+    content: `${basePath}/components/details/${names.pascalCase}Content.tsx`,
+    container: `${basePath}/components/containers/${names.pascalCase}Container.tsx`,
+    listContainer: `${basePath}/components/containers/${names.pascalCase}ListContainer.tsx`,
+
+    // Context & Hooks
+    context: `${basePath}/contexts/${names.pascalCase}Context.tsx`,
+    tableHook: `${basePath}/hooks/use${names.pascalCase}TableStructure.tsx`,
+
+    // Module
+    module: `${basePath}/${names.pascalCase}Module.ts`,
+
+    // Pages
+    listPage: `${pagePath}/page.tsx`,
+    detailPage: `${pagePath}/[id]/page.tsx`,
+  };
+}
+
+/**
+ * Build relative import path between two files
+ *
+ * @param fromPath - Source file path
+ * @param toPath - Target file path
+ * @returns Relative import path
+ */
+export function buildRelativeImport(fromPath: string, toPath: string): string {
+  // For files in same feature, use @ alias
+  if (toPath.startsWith("@/")) {
+    return toPath;
+  }
+
+  // Calculate relative path
+  const fromParts = fromPath.split("/");
+  const toParts = toPath.split("/");
+
+  // Find common prefix
+  let commonLength = 0;
+  for (let i = 0; i < Math.min(fromParts.length, toParts.length); i++) {
+    if (fromParts[i] === toParts[i]) {
+      commonLength++;
+    } else {
+      break;
+    }
+  }
+
+  // Build relative path
+  const upCount = fromParts.length - commonLength - 1; // -1 for the file itself
+  const relativeParts = toParts.slice(commonLength);
+  const prefix = upCount > 0 ? "../".repeat(upCount) : "./";
+
+  return prefix + relativeParts.join("/");
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Transformers Index
+ *
+ * Re-exports all transformer modules.
+ */
+
+export * from "./name-transformer";
+export * from "./parent-detector";
+export * from "./field-mapper";
+export * from "./relationship-resolver";
+export * from "./import-resolver";
+export * from "./i18n-generator";

package/scripts/generate-web-module/transformers/name-transformer.ts

@@ -0,0 +1,115 @@
+/**
+ * Name Transformer
+ *
+ * Transforms module names to various case conventions
+ * needed for code generation.
+ */
+
+import { NameTransforms } from "../types/template-data.interface";
+
+/**
+ * Transform a module name to all necessary case conventions
+ *
+ * @param moduleName - PascalCase module name (e.g., "Comment")
+ * @param endpoint - Optional kebab-case plural endpoint (e.g., "comments"), derived from moduleName if not provided
+ * @returns All name transformations
+ */
+export function transformNames(moduleName: string, endpoint?: string): NameTransforms {
+  const pluralPascal = toPascalCase(pluralize(moduleName));
+  const pluralCamel = toCamelCase(pluralPascal);
+  const pluralKebab = endpoint || toKebabCase(pluralize(moduleName));
+
+  return {
+    pascalCase: moduleName,
+    camelCase: toCamelCase(moduleName),
+    kebabCase: toKebabCase(moduleName),
+    pluralPascal,
+    pluralCamel,
+    pluralKebab,
+    titleCase: toTitleCase(moduleName),
+    pluralTitleCase: toTitleCase(pluralPascal),
+  };
+}
+
+/**
+ * Convert PascalCase to camelCase
+ *
+ * @param str - PascalCase string
+ * @returns camelCase string
+ */
+export function toCamelCase(str: string): string {
+  return str.charAt(0).toLowerCase() + str.slice(1);
+}
+
+/**
+ * Convert PascalCase to kebab-case
+ *
+ * @param str - PascalCase string
+ * @returns kebab-case string
+ */
+export function toKebabCase(str: string): string {
+  return str
+    .replace(/([A-Z])/g, "-$1")
+    .toLowerCase()
+    .replace(/^-/, "");
+}
+
+/**
+ * Convert string to PascalCase
+ *
+ * @param str - Any case string
+ * @returns PascalCase string
+ */
+export function toPascalCase(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Convert PascalCase/camelCase to Title Case with spaces
+ * e.g., "firstName" -> "First Name", "UserProfile" -> "User Profile"
+ *
+ * @param str - PascalCase or camelCase string
+ * @returns Title Case string with spaces
+ */
+export function toTitleCase(str: string): string {
+  return str
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, (char) => char.toUpperCase())
+    .trim();
+}
+
+/**
+ * Simple pluralization
+ * Note: This is a basic implementation. For production, consider using a library like 'pluralize'
+ *
+ * @param str - Singular form
+ * @returns Plural form
+ */
+export function pluralize(str: string): string {
+  if (str.endsWith("s")) {
+    return str + "es";
+  }
+  if (str.endsWith("y") && !["a", "e", "i", "o", "u"].includes(str[str.length - 2])) {
+    return str.slice(0, -1) + "ies";
+  }
+  return str + "s";
+}
+
+/**
+ * Simple singularization (reverse of pluralize)
+ *
+ * @param str - Plural form
+ * @returns Singular form
+ */
+export function singularize(str: string): string {
+  if (str.endsWith("ies")) {
+    return str.slice(0, -3) + "y";
+  }
+  if (str.endsWith("ses") || str.endsWith("xes") || str.endsWith("zes")) {
+    return str.slice(0, -2);
+  }
+  if (str.endsWith("s") && !str.endsWith("ss")) {
+    return str.slice(0, -1);
+  }
+  return str;
+}

package/scripts/generate-web-module/transformers/parent-detector.ts

@@ -0,0 +1,87 @@
+/**
+ * Parent Class Detector
+ *
+ * Determines whether a module should extend Content or AbstractApiData
+ * based on the presence of Content-specific fields.
+ */
+
+import { JsonFieldDefinition } from "../types/json-schema.interface";
+import { CONTENT_INDICATOR_FIELDS } from "../types/field-mapping.types";
+
+/**
+ * Check if a module should extend Content based on its fields
+ *
+ * @param fields - Array of field definitions from JSON schema
+ * @returns true if the module should extend Content
+ */
+export function detectExtendsContent(fields: JsonFieldDefinition[]): boolean {
+  const fieldNames = fields.map((f) => f.name);
+  return CONTENT_INDICATOR_FIELDS.some((indicator) => fieldNames.includes(indicator));
+}
+
+/**
+ * Get the parent class name based on detection result
+ *
+ * @param extendsContent - Whether the module extends Content
+ * @returns Parent class name
+ */
+export function getParentClassName(extendsContent: boolean): string {
+  return extendsContent ? "Content" : "AbstractApiData";
+}
+
+/**
+ * Get the parent interface name based on detection result
+ *
+ * @param extendsContent - Whether the module extends Content
+ * @returns Parent interface name
+ */
+export function getParentInterfaceName(extendsContent: boolean): string {
+  return extendsContent ? "ContentInterface" : "BaseInterface";
+}
+
+/**
+ * Get the parent input type name based on detection result
+ *
+ * @param extendsContent - Whether the module extends Content
+ * @returns Parent input type or null if standalone
+ */
+export function getParentInputType(extendsContent: boolean): string | null {
+  return extendsContent ? "ContentInput" : null;
+}
+
+/**
+ * Get the import path for the parent class
+ *
+ * @param extendsContent - Whether the module extends Content
+ * @returns Import path for parent class
+ */
+export function getParentClassImport(extendsContent: boolean): string {
+  if (extendsContent) {
+    return '@carlonicora/nextjs-jsonapi/core';
+  }
+  return '@carlonicora/nextjs-jsonapi/core';
+}
+
+/**
+ * Check if the module needs to call super.addContentInput() in createJsonApi
+ *
+ * @param extendsContent - Whether the module extends Content
+ * @returns true if super.addContentInput() should be called
+ */
+export function needsAddContentInput(extendsContent: boolean): boolean {
+  return extendsContent;
+}
+
+/**
+ * Get fields that are inherited from Content and should not be declared
+ *
+ * @param extendsContent - Whether the module extends Content
+ * @returns Array of field names to exclude from generation
+ */
+export function getInheritedFields(extendsContent: boolean): string[] {
+  if (extendsContent) {
+    // These fields are already in Content, don't redeclare them
+    return ["name", "tldr", "abstract", "relevance"];
+  }
+  return [];
+}