@carlonicora/nextjs-jsonapi 1.2.0 → 1.3.1

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

@@ -0,0 +1,69 @@
+/**
+ * Module Template
+ *
+ * Generates {Module}Module.ts for module configuration and registration.
+ */
+
+import { FrontendTemplateData } from "../types/template-data.interface";
+import { DEFAULT_MODULE_ICON } from "../types/field-mapping.types";
+
+/**
+ * Generate the module configuration file content
+ *
+ * @param data - Frontend template data
+ * @returns Generated file content
+ */
+export function generateModuleTemplate(data: FrontendTemplateData): string {
+  const { names, moduleId, endpoint, fields, extendsContent } = data;
+
+  // Build inclusions for lists
+  const listFieldNames = getListFieldNames(data);
+  const listInclusionFields = listFieldNames.map((f) => `\`${f}\``).join(", ");
+
+  return `import { ${names.pascalCase} } from "@/features/${data.targetDir}/${names.kebabCase}/data/${names.pascalCase}";
+import { createJsonApiInclusion } from "@carlonicora/nextjs-jsonapi/core";
+import { ModuleFactory } from "@carlonicora/nextjs-jsonapi/permissions";
+import { ${DEFAULT_MODULE_ICON} } from "lucide-react";
+
+export const ${names.pascalCase}Module = (factory: ModuleFactory) =>
+  factory({
+    pageUrl: "/${names.pluralKebab}",
+    name: "${names.pluralCamel}",
+    model: ${names.pascalCase},
+    moduleId: "${moduleId}",
+    icon: ${DEFAULT_MODULE_ICON},
+    inclusions: {
+      lists: {
+        fields: [
+          createJsonApiInclusion("${endpoint}", [${listInclusionFields}]),
+          createJsonApiInclusion("users", [\`name\`, \`avatar\`]),
+        ],
+      },
+    },
+  });
+`;
+}
+
+/**
+ * Get field names suitable for list display
+ */
+function getListFieldNames(data: FrontendTemplateData): string[] {
+  const { fields, extendsContent } = data;
+  const fieldNames: string[] = [];
+
+  // Content-extending modules get name, tldr
+  if (extendsContent) {
+    fieldNames.push("name", "tldr");
+  }
+
+  // Add other displayable fields (not content or abstract)
+  fields.forEach((field) => {
+    if (!["id", "content", "abstract", "createdAt", "updatedAt"].includes(field.name)) {
+      if (!fieldNames.includes(field.name)) {
+        fieldNames.push(field.name);
+      }
+    }
+  });
+
+  return fieldNames;
+}

package/scripts/generate-web-module/templates/pages/detail-page.template.ts

@@ -0,0 +1,65 @@
+/**
+ * Detail Page Template
+ *
+ * Generates the detail page for the module at [locale]/(main)/(features)/{plural}/[id]/page.tsx
+ */
+
+import { FrontendTemplateData } from "../../types/template-data.interface";
+
+/**
+ * Generate the detail page file content
+ *
+ * @param data - Frontend template data
+ * @returns Generated file content
+ */
+export function generateDetailPageTemplate(data: FrontendTemplateData): string {
+  const { names } = data;
+
+  return `import ${names.pascalCase}Container from "@/features/${data.targetDir}/${names.kebabCase}/components/containers/${names.pascalCase}Container";
+import { ${names.pascalCase}Provider } 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 { ${names.pascalCase}Service } from "@/features/${data.targetDir}/${names.kebabCase}/data/${names.pascalCase}Service";
+import { generateSpecificMetadata } from "@/utils/metadata";
+import { PageContainer } from "@carlonicora/nextjs-jsonapi/components";
+import { Modules } from "@carlonicora/nextjs-jsonapi/core";
+import { Action } from "@carlonicora/nextjs-jsonapi/permissions";
+import { ServerSession } from "@carlonicora/nextjs-jsonapi/server";
+import { Metadata } from "next";
+import { getTranslations } from "next-intl/server";
+import { cache } from "react";
+
+const getCached${names.pascalCase} = cache(async (id: string) => ${names.pascalCase}Service.findOne({ id }));
+
+export async function generateMetadata(props: { params: Promise<{ id: string }> }): Promise<Metadata> {
+  const params = await props.params;
+  const t = await getTranslations();
+
+  const ${names.camelCase}: ${names.pascalCase}Interface = await getCached${names.pascalCase}(params.id);
+
+  const title = (await ServerSession.hasPermissionToModule({
+    module: Modules.${names.pascalCase},
+    action: Action.Read,
+    data: ${names.camelCase},
+  }))
+    ? \`[\${t(\`types.${names.pluralCamel}\`, { count: 1 })}] \${${names.camelCase}.name}\`
+    : \`\${t(\`types.${names.pluralCamel}\`, { count: 1 })}\`;
+
+  return await generateSpecificMetadata({ title: title });
+}
+
+export default async function ${names.pascalCase}Page(props: { params: Promise<{ id: string }> }) {
+  const params = await props.params;
+  const ${names.camelCase}: ${names.pascalCase}Interface = await getCached${names.pascalCase}(params.id);
+
+  ServerSession.checkPermission({ module: Modules.${names.pascalCase}, action: Action.Read, data: ${names.camelCase} });
+
+  return (
+    <${names.pascalCase}Provider dehydrated${names.pascalCase}={${names.camelCase}.dehydrate()}>
+      <PageContainer>
+        <${names.pascalCase}Container />
+      </PageContainer>
+    </${names.pascalCase}Provider>
+  );
+}
+`;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Page Templates Index
+ *
+ * Exports all page template generators.
+ */
+
+export { generateListPageTemplate } from "./list-page.template";
+export { generateDetailPageTemplate } from "./detail-page.template";

package/scripts/generate-web-module/templates/pages/list-page.template.ts

@@ -0,0 +1,37 @@
+/**
+ * List Page Template
+ *
+ * Generates the list page for the module at [locale]/(main)/(features)/{plural}/page.tsx
+ */
+
+import { FrontendTemplateData } from "../../types/template-data.interface";
+
+/**
+ * Generate the list page file content
+ *
+ * @param data - Frontend template data
+ * @returns Generated file content
+ */
+export function generateListPageTemplate(data: FrontendTemplateData): string {
+  const { names } = data;
+
+  return `import ${names.pascalCase}ListContainer from "@/features/${data.targetDir}/${names.kebabCase}/components/containers/${names.pascalCase}ListContainer";
+import { ${names.pascalCase}Provider } from "@/features/${data.targetDir}/${names.kebabCase}/contexts/${names.pascalCase}Context";
+import { PageContainer } from "@carlonicora/nextjs-jsonapi/components";
+import { Modules } from "@carlonicora/nextjs-jsonapi/core";
+import { Action } from "@carlonicora/nextjs-jsonapi/permissions";
+import { ServerSession } from "@carlonicora/nextjs-jsonapi/server";
+
+export default async function ${names.pluralPascal}ListPage() {
+  ServerSession.checkPermission({ module: Modules.${names.pascalCase}, action: Action.Read });
+
+  return (
+    <${names.pascalCase}Provider>
+      <PageContainer testId="page-${names.pluralKebab}-container">
+        <${names.pascalCase}ListContainer />
+      </PageContainer>
+    </${names.pascalCase}Provider>
+  );
+}
+`;
+}

package/scripts/generate-web-module/templates/table-hook.template.ts

@@ -0,0 +1,182 @@
+/**
+ * Table Hook Template
+ *
+ * Generates use{Module}TableStructure.tsx for table column definitions.
+ */
+
+import { FrontendTemplateData, FrontendField } from "../types/template-data.interface";
+import { toCamelCase } from "../transformers/name-transformer";
+
+/**
+ * Generate the table structure hook file content
+ *
+ * @param data - Frontend template data
+ * @returns Generated file content
+ */
+export function generateTableHookTemplate(data: FrontendTemplateData): string {
+  const { names, fields, extendsContent, tableFieldNames } = data;
+
+  const fieldColumnEntries = generateFieldColumnEntries(data);
+  const hasAuthors = extendsContent;
+  const hasRelevance = fields.some((f) => f.name === "relevance");
+
+  return `"use client";
+
+import { ${names.pascalCase}Fields } from "@/features/${data.targetDir}/${names.kebabCase}/data/${names.pascalCase}Fields";
+import { ${names.pascalCase}Interface } from "@/features/${data.targetDir}/${names.kebabCase}/data/${names.pascalCase}Interface";
+import { cellDate, cellId${hasAuthors ? ", ContributorsList" : ""} } from "@carlonicora/nextjs-jsonapi/components";
+import { Modules } from "@carlonicora/nextjs-jsonapi/core";${extendsContent ? `
+import { ContentInterface } from "@carlonicora/nextjs-jsonapi/features";` : ""}
+import {
+  registerTableGenerator,
+  TableContent,
+  usePageUrlGenerator,
+  UseTableStructureHook,
+} from "@carlonicora/nextjs-jsonapi/hooks";
+import { Link, Tooltip, TooltipContent, TooltipTrigger } from "@carlonicora/nextjs-jsonapi/shadcnui";
+import { ColumnDef } from "@tanstack/react-table";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+
+export const use${names.pascalCase}TableStructure: UseTableStructureHook<${names.pascalCase}Interface, ${names.pascalCase}Fields> = (params) => {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const tableData = useMemo(() => {
+    return params.data.map((${names.camelCase}: ${names.pascalCase}Interface) => {
+      const entry: TableContent<${names.pascalCase}Interface> = {
+        jsonApiData: ${names.camelCase},
+      };
+      entry[${names.pascalCase}Fields.${names.camelCase}Id] = ${names.camelCase}.id;
+      params.fields.forEach((field) => {
+        entry[field] = ${names.camelCase}[field as keyof ${names.pascalCase}Interface];
+      });
+      return entry;
+    });
+  }, [params.data, params.fields]);
+
+  const fieldColumnMap: Partial<Record<${names.pascalCase}Fields, () => any>> = {
+    [${names.pascalCase}Fields.${names.camelCase}Id]: () =>
+      cellId({
+        name: "${names.camelCase}Id",
+        checkedIds: params.checkedIds,
+        toggleId: params.toggleId,
+      }),
+${fieldColumnEntries}
+    [${names.pascalCase}Fields.createdAt]: () =>
+      cellDate({
+        name: "createdAt",
+        title: t(\`generic.date.create\`),
+      }),
+    [${names.pascalCase}Fields.updatedAt]: () =>
+      cellDate({
+        name: "updatedAt",
+        title: t(\`generic.date.update\`),
+      }),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<${names.pascalCase}Interface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, generateUrl]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator(Modules.${names.pascalCase}, use${names.pascalCase}TableStructure);
+`;
+}
+
+/**
+ * Generate field column map entries
+ */
+function generateFieldColumnEntries(data: FrontendTemplateData): string {
+  const { names, fields, extendsContent } = data;
+  const entries: string[] = [];
+
+  // Name field (with link and tooltip for tldr if Content-extending)
+  if (fields.some((f) => f.name === "name") || extendsContent) {
+    entries.push(`    [${names.pascalCase}Fields.name]: () => ({
+      id: "name",
+      accessorKey: "name",
+      header: t(\`features.${names.camelCase}.fields.name.label\`),
+      cell: ({ row }: { row: TableContent<${names.pascalCase}Interface> }) => {
+        const ${names.camelCase}: ${names.pascalCase}Interface = row.original.jsonApiData;
+        return (
+          <Tooltip>
+            <TooltipTrigger>
+              <Link href={generateUrl({ page: Modules.${names.pascalCase}, id: ${names.camelCase}.id })}>{${names.camelCase}.name}</Link>
+            </TooltipTrigger>${extendsContent ? `
+            <TooltipContent>{${names.camelCase}.tldr}</TooltipContent>` : `
+            <TooltipContent>{${names.camelCase}.name}</TooltipContent>`}
+          </Tooltip>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),`);
+  }
+
+  // Authors field for Content-extending modules
+  if (extendsContent) {
+    entries.push(`    [${names.pascalCase}Fields.authors]: () => ({
+      id: "authors",
+      accessorKey: "authors",
+      header: t(\`generic.relationships.author.label\`),
+      cell: ({ row }: { row: TableContent<ContentInterface> }) => {
+        const content: ContentInterface = row.original.jsonApiData;
+        return <ContributorsList content={content} />;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),`);
+  }
+
+  // Other displayable fields (excluding id, name, tldr, abstract, content, dates)
+  const displayableFields = fields.filter(
+    (f) => !["id", "name", "tldr", "abstract", "content", "createdAt", "updatedAt"].includes(f.name)
+  );
+
+  displayableFields.forEach((field) => {
+    if (field.type === "string") {
+      entries.push(`    [${names.pascalCase}Fields.${field.name}]: () => ({
+      id: "${field.name}",
+      accessorKey: "${field.name}",
+      header: t(\`features.${names.camelCase}.fields.${field.name}.label\`),
+      cell: ({ row }: { row: TableContent<${names.pascalCase}Interface> }) => {
+        const ${names.camelCase}: ${names.pascalCase}Interface = row.original.jsonApiData;
+        return <span>{${names.camelCase}.${field.name}}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),`);
+    } else if (field.type === "boolean") {
+      entries.push(`    [${names.pascalCase}Fields.${field.name}]: () => ({
+      id: "${field.name}",
+      accessorKey: "${field.name}",
+      header: t(\`features.${names.camelCase}.fields.${field.name}.label\`),
+      cell: ({ row }: { row: TableContent<${names.pascalCase}Interface> }) => {
+        const ${names.camelCase}: ${names.pascalCase}Interface = row.original.jsonApiData;
+        return <span>{${names.camelCase}.${field.name} ? t(\`generic.yes\`) : t(\`generic.no\`)}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),`);
+    } else if (field.type === "number") {
+      entries.push(`    [${names.pascalCase}Fields.${field.name}]: () => ({
+      id: "${field.name}",
+      accessorKey: "${field.name}",
+      header: t(\`features.${names.camelCase}.fields.${field.name}.label\`),
+      cell: ({ row }: { row: TableContent<${names.pascalCase}Interface> }) => {
+        const ${names.camelCase}: ${names.pascalCase}Interface = row.original.jsonApiData;
+        return <span>{${names.camelCase}.${field.name}?.toString()}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),`);
+    }
+  });
+
+  return entries.join("\n");
+}

package/scripts/generate-web-module/transformers/field-mapper.ts

@@ -0,0 +1,201 @@
+/**
+ * Field Mapper
+ *
+ * Maps JSON schema fields to their TypeScript, Zod, and form component equivalents.
+ */
+
+import { JsonFieldDefinition } from "../types/json-schema.interface";
+import { FrontendField, FormComponentType } from "../types/template-data.interface";
+import {
+  getTsType,
+  getZodBase,
+  getFormComponent,
+  isContentField,
+  SPECIAL_FIELD_COMPONENTS,
+} from "../types/field-mapping.types";
+
+/**
+ * Map a JSON field definition to a frontend field
+ *
+ * @param field - JSON field definition
+ * @param moduleName - Module name for i18n error messages
+ * @returns Frontend field representation
+ */
+export function mapField(field: JsonFieldDefinition, moduleName: string): FrontendField {
+  const formComponent = getFormComponent(field.name, field.type);
+  const isContent = isContentField(field.name);
+
+  return {
+    name: field.name,
+    type: field.type,
+    tsType: getTsType(field.type),
+    zodSchema: buildZodSchema(field, moduleName),
+    formComponent,
+    nullable: field.nullable,
+    isContentField: isContent,
+  };
+}
+
+/**
+ * Map all fields from JSON schema
+ *
+ * @param fields - Array of JSON field definitions
+ * @param moduleName - Module name for i18n error messages
+ * @returns Array of frontend field representations
+ */
+export function mapFields(fields: JsonFieldDefinition[], moduleName: string): FrontendField[] {
+  return fields.map((field) => mapField(field, moduleName));
+}
+
+/**
+ * Build complete Zod schema string for a field
+ *
+ * @param field - JSON field definition
+ * @param moduleName - Module name (lowercase) for i18n keys
+ * @returns Zod schema code string
+ */
+export function buildZodSchema(field: JsonFieldDefinition, moduleName: string): string {
+  // Content fields always use z.any()
+  if (isContentField(field.name)) {
+    return "z.any()";
+  }
+
+  const base = getZodBase(field.type);
+
+  // String fields with validation
+  if (field.type === "string") {
+    if (field.nullable) {
+      return `${base}.optional()`;
+    }
+    // Required string with error message
+    return `${base}.min(1, { message: t(\`features.${moduleName.toLowerCase()}.fields.${field.name}.error\`) })`;
+  }
+
+  // Number fields
+  if (field.type === "number") {
+    if (field.nullable) {
+      return `${base}.optional()`;
+    }
+    return base;
+  }
+
+  // Boolean fields
+  if (field.type === "boolean") {
+    if (field.nullable) {
+      return `${base}.optional()`;
+    }
+    return base;
+  }
+
+  // Date fields
+  if (field.type === "date") {
+    if (field.nullable) {
+      return `z.coerce.date().optional()`;
+    }
+    return `z.coerce.date()`;
+  }
+
+  // Default case
+  if (field.nullable) {
+    return `${base}.optional()`;
+  }
+  return base;
+}
+
+/**
+ * Get the form JSX for a field
+ *
+ * @param field - Frontend field
+ * @param moduleName - Module name for i18n keys
+ * @returns JSX code for the form field
+ */
+export function getFormFieldJsx(field: FrontendField, moduleName: string): string {
+  const lowerModuleName = moduleName.toLowerCase();
+  const isRequired = !field.nullable;
+
+  switch (field.formComponent) {
+    case "BlockNoteEditor":
+      return `<FormContainerGeneric form={form} id="${field.name}" name={t(\`features.${lowerModuleName}.fields.${field.name}.label\`)}>
+  <BlockNoteEditorContainer
+    id={form.getValues("id")}
+    type="${lowerModuleName}"
+    initialContent={form.getValues("${field.name}")}
+    onChange={(content, isEmpty, hasUnresolvedDiff) => {
+      form.setValue("${field.name}", content);
+    }}
+    placeholder={t(\`features.${lowerModuleName}.fields.${field.name}.placeholder\`)}
+    bordered
+  />
+</FormContainerGeneric>`;
+
+    case "FormTextarea":
+      return `<FormTextarea
+  form={form}
+  id="${field.name}"
+  name={t(\`features.${lowerModuleName}.fields.${field.name}.label\`)}
+  placeholder={t(\`features.${lowerModuleName}.fields.${field.name}.placeholder\`)}
+  ${isRequired ? "isRequired" : ""}
+/>`;
+
+    case "Checkbox":
+      return `<FormCheckbox
+  form={form}
+  id="${field.name}"
+  name={t(\`features.${lowerModuleName}.fields.${field.name}.label\`)}
+/>`;
+
+    case "DatePicker":
+      return `<FormDatePicker
+  form={form}
+  id="${field.name}"
+  name={t(\`features.${lowerModuleName}.fields.${field.name}.label\`)}
+  ${isRequired ? "isRequired" : ""}
+/>`;
+
+    case "FormInputNumber":
+      return `<FormInput
+  form={form}
+  id="${field.name}"
+  name={t(\`features.${lowerModuleName}.fields.${field.name}.label\`)}
+  placeholder={t(\`features.${lowerModuleName}.fields.${field.name}.placeholder\`)}
+  type="number"
+  ${isRequired ? "isRequired" : ""}
+/>`;
+
+    case "FormInput":
+    default:
+      return `<FormInput
+  form={form}
+  id="${field.name}"
+  name={t(\`features.${lowerModuleName}.fields.${field.name}.label\`)}
+  placeholder={t(\`features.${lowerModuleName}.fields.${field.name}.placeholder\`)}
+  ${isRequired ? "isRequired" : ""}
+/>`;
+  }
+}
+
+/**
+ * Filter out inherited fields that shouldn't be generated
+ *
+ * @param fields - Array of frontend fields
+ * @param inheritedFields - Array of field names inherited from parent
+ * @returns Filtered array of fields
+ */
+export function filterInheritedFields(
+  fields: FrontendField[],
+  inheritedFields: string[]
+): FrontendField[] {
+  return fields.filter((f) => !inheritedFields.includes(f.name));
+}
+
+/**
+ * Get fields that should be included in the editor form
+ *
+ * @param fields - Array of frontend fields
+ * @returns Fields suitable for form editing
+ */
+export function getEditorFields(fields: FrontendField[]): FrontendField[] {
+  // Exclude auto-generated fields like createdAt, updatedAt
+  const excludeFields = ["createdAt", "updatedAt", "id"];
+  return fields.filter((f) => !excludeFields.includes(f.name));
+}