@carlonicora/nextjs-jsonapi 1.108.0 → 1.110.0

package/src/features/how-to/components/forms/HowToEditor.tsx

@@ -3,12 +3,12 @@
 import { zodResolver } from "@hookform/resolvers/zod";
 import { PlusIcon, SearchIcon, XIcon } from "lucide-react";
 import { useTranslations } from "next-intl";
-import { ReactNode, useCallback, useMemo, useState } from "react";
+import { ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useForm } from "react-hook-form";
 import { v4 } from "uuid";
 import { z } from "zod";
 
-import { EditorSheet, FormInput } from "../../../../components";
+import { EditorSheet, FormInput, FormSelect, FormTextarea, FormCheckbox } from "../../../../components";
 import { BlockNoteEditorContainer } from "../../../../components";
 import { ModuleRegistry, Modules } from "../../../../core";
 import { useI18nRouter } from "../../../../hooks";
@@ -27,6 +27,9 @@ import {
 import { HowTo } from "../../data/HowTo";
 import { HowToInput, HowToInterface } from "../../data/HowToInterface";
 import { HowToService } from "../../data/HowToService";
+import HowToMultiSelector from "./HowToMultiSelector";
+
+const HOW_TO_TYPES = ["tutorial", "how-to", "reference", "explanation"] as const;
 
 function PageSelector({
   value,
@@ -140,6 +143,14 @@ function HowToEditorInternal({
         name: z.string().min(1, { message: t(`howto.fields.name.error`) }),
         description: z.any(),
         pages: z.array(z.string()),
+        howToType: z.enum(HOW_TO_TYPES),
+        slug: z.string().min(1, { message: t(`howto.fields.slug.error`) }),
+        order: z.number().int().min(0),
+        summary: z.string().optional(),
+        tags: z.string().optional(),
+        contextualKeys: z.string().optional(),
+        draft: z.boolean().optional(),
+        relatedArticles: z.array(z.object({ id: z.string().uuid(), name: z.string() })).optional(),
       }),
     [t],
   );
@@ -150,6 +161,14 @@ function HowToEditorInternal({
       name: howTo?.name || "",
       description: howTo?.description || [],
       pages: HowTo.parsePagesFromString(howTo?.pages),
+      howToType: (howTo?.howToType as (typeof HOW_TO_TYPES)[number]) ?? "how-to",
+      slug: howTo?.slug ?? "",
+      order: howTo?.order ?? 0,
+      summary: howTo?.summary ?? "",
+      tags: (howTo?.tags ?? []).join(", "),
+      contextualKeys: (howTo?.contextualKeys ?? []).join(", "),
+      draft: howTo?.draft ?? false,
+      relatedArticles: [] as { id: string; name: string }[],
     }),
     [howTo],
   );
@@ -159,6 +178,26 @@ function HowToEditorInternal({
     defaultValues: getDefaultValues(),
   });
 
+  const initialRelatedIds = useRef<string[]>([]);
+  useEffect(() => {
+    if (!howTo?.howToType || !howTo?.slug) return;
+    let active = true;
+    HowToService.findRelated({ howToType: howTo.howToType, slug: howTo.slug })
+      .then((list) => {
+        if (!active) return;
+        initialRelatedIds.current = list.map((r) => r.id);
+        form.setValue(
+          "relatedArticles",
+          list.map((r) => ({ id: r.id, name: r.name })),
+          { shouldDirty: false },
+        );
+      })
+      .catch(() => {});
+    return () => {
+      active = false;
+    };
+  }, [howTo, form]);
+
   const handleDescriptionChange = useCallback(
     (content: any) => {
       form.setValue("description", content, { shouldDirty: true });
@@ -191,17 +230,40 @@ function HowToEditorInternal({
       propagateChanges={propagateChanges}
       size="lg"
       onSubmit={async (values) => {
+        const toList = (s?: string) =>
+          (s ?? "")
+            .split(",")
+            .map((x) => x.trim())
+            .filter(Boolean);
+
         const payload: HowToInput = {
           id: values.id,
           name: values.name,
           authorId: "",
           description: values.description,
           pages: HowTo.serializePagesToString(values.pages),
+          howToType: values.howToType,
+          slug: values.slug,
+          order: values.order,
+          summary: values.summary,
+          tags: toList(values.tags),
+          contextualKeys: toList(values.contextualKeys),
+          draft: values.draft ?? false,
         };
 
-        const updatedHowTo = howTo ? await HowToService.update(payload) : await HowToService.create(payload);
+        const saved = howTo ? await HowToService.update(payload) : await HowToService.create(payload);
 
-        return updatedHowTo;
+        const desired = new Set((values.relatedArticles ?? []).map((r) => r.id));
+        const current = new Set(initialRelatedIds.current);
+        for (const relatedId of desired) {
+          if (!current.has(relatedId)) await HowToService.addRelated({ howToId: values.id, relatedId });
+        }
+        for (const relatedId of current) {
+          if (!desired.has(relatedId)) await HowToService.removeRelated({ howToId: values.id, relatedId });
+        }
+        initialRelatedIds.current = Array.from(desired);
+
+        return saved;
       }}
       onReset={() => {
         return getDefaultValues();
@@ -222,6 +284,28 @@ function HowToEditorInternal({
           placeholder={t(`howto.fields.name.placeholder`)}
           isRequired
         />
+        <FormSelect
+          form={form}
+          id="howToType"
+          name={t(`howto.fields.howToType.label`)}
+          placeholder={t(`howto.fields.howToType.placeholder`)}
+          values={HOW_TO_TYPES.map((m) => ({ id: m, text: t(`howto.howToType.${m}` as any) }))}
+          isRequired
+        />
+        <FormInput
+          form={form}
+          id="slug"
+          name={t(`howto.fields.slug.label`)}
+          placeholder={t(`howto.fields.slug.placeholder`)}
+          isRequired
+        />
+        <FormInput form={form} id="order" name={t(`howto.fields.order.label`)} type="number" />
+        <FormTextarea
+          form={form}
+          id="summary"
+          name={t(`howto.fields.summary.label`)}
+          placeholder={t(`howto.fields.summary.placeholder`)}
+        />
         <div className="space-y-2">
           <Label>{t(`howto.fields.description.label`)}</Label>
           <div className="max-h-80 overflow-y-auto rounded-md border">
@@ -260,6 +344,26 @@ function HowToEditorInternal({
             </Button>
           </div>
         </div>
+        <FormInput
+          form={form}
+          id="tags"
+          name={t(`howto.fields.tags.label`)}
+          placeholder={t(`howto.fields.tags.placeholder`)}
+        />
+        <FormInput
+          form={form}
+          id="contextualKeys"
+          name={t(`howto.fields.contextualKeys.label`)}
+          placeholder={t(`howto.fields.contextualKeys.placeholder`)}
+        />
+        <HowToMultiSelector
+          id="relatedArticles"
+          form={form}
+          currentHowTo={howTo}
+          label={t(`howto.fields.relatedArticles.label`)}
+          placeholder={t(`howto.fields.relatedArticles.placeholder`)}
+        />
+        <FormCheckbox form={form} id="draft" name={t(`howto.fields.draft.label`)} />
       </div>
     </EditorSheet>
   );

package/src/features/how-to/data/HowTo.spec.ts

@@ -0,0 +1,43 @@
+import { beforeAll, describe, it, expect } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { HowTo } from "./HowTo";
+
+// createJsonApi reads Modules.HowTo.name (resolved lazily via ModuleRegistry),
+// so the module must be registered before the model serialises — mirrors the
+// AssistantMessage.spec setup convention in this package.
+const howToModule: ApiRequestDataTypeInterface = {
+  name: "howtos",
+  model: HowTo,
+} as any;
+
+beforeAll(() => {
+  ModuleRegistry.register("HowTo", howToModule);
+});
+
+describe("HowTo.createJsonApi", () => {
+  it("serialises the new attributes", () => {
+    const res = new HowTo().createJsonApi({
+      id: "11111111-1111-4111-8111-111111111111",
+      name: "Add an NPC",
+      authorId: "",
+      description: [{ type: "paragraph", content: [] }],
+      howToType: "how-to",
+      slug: "add-an-npc",
+      order: 30,
+      summary: "Create a Non-Player Character.",
+      tags: ["world"],
+      contextualKeys: ["npc.editor"],
+      draft: false,
+    });
+    const a = res.data.attributes;
+    expect(a.howToType).toBe("how-to");
+    expect(a.slug).toBe("add-an-npc");
+    expect(a.order).toBe(30);
+    expect(a.summary).toBe("Create a Non-Player Character.");
+    expect(a.tags).toEqual(["world"]);
+    expect(a.contextualKeys).toEqual(["npc.editor"]);
+    expect(a.draft).toBe(false);
+    expect(typeof a.description).toBe("string"); // existing: BlockNote JSON stringified
+  });
+});

package/src/features/how-to/data/HowTo.ts

@@ -5,6 +5,13 @@ import { HowToInput, HowToInterface } from "./HowToInterface";
 export class HowTo extends Content implements HowToInterface {
   private _description?: any;
   private _pages?: string;
+  private _howToType?: string;
+  private _slug?: string;
+  private _order?: number;
+  private _summary?: string;
+  private _tags?: string[];
+  private _contextualKeys?: string[];
+  private _draft?: boolean;
 
   /**
    * Parse pages from backend JSON string (handles legacy single string + JSON array)
@@ -36,13 +43,60 @@ export class HowTo extends Content implements HowToInterface {
     return this._pages;
   }
 
+  get howToType(): string | undefined {
+    return this._howToType;
+  }
+
+  get slug(): string | undefined {
+    return this._slug;
+  }
+
+  get order(): number | undefined {
+    return this._order;
+  }
+
+  get summary(): string | undefined {
+    return this._summary;
+  }
+
+  get tags(): string[] {
+    return this._tags ?? [];
+  }
+
+  get contextualKeys(): string[] {
+    return this._contextualKeys ?? [];
+  }
+
+  get draft(): boolean {
+    return this._draft ?? false;
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
 
-    this._description = data.jsonApi.attributes.description
-      ? JSON.parse(data.jsonApi.attributes.description)
-      : undefined;
+    const rawDescription = data.jsonApi.attributes.description;
+    if (rawDescription === undefined || rawDescription === null || rawDescription === "") {
+      this._description = undefined;
+    } else if (typeof rawDescription === "string") {
+      try {
+        this._description = JSON.parse(rawDescription);
+      } catch {
+        // Help-content HowTos store plain-text summaries; admin-created HowTos
+        // store JSON-stringified BlockNote docs. Fall back to the raw string
+        // rather than crashing rehydration for the plain-text case.
+        this._description = rawDescription;
+      }
+    } else {
+      this._description = rawDescription;
+    }
     this._pages = data.jsonApi.attributes.pages;
+    this._howToType = data.jsonApi.attributes.howToType;
+    this._slug = data.jsonApi.attributes.slug;
+    this._order = data.jsonApi.attributes.order;
+    this._summary = data.jsonApi.attributes.summary;
+    this._tags = data.jsonApi.attributes.tags ?? [];
+    this._contextualKeys = data.jsonApi.attributes.contextualKeys ?? [];
+    this._draft = data.jsonApi.attributes.draft ?? false;
 
     return this;
   }
@@ -63,6 +117,13 @@ export class HowTo extends Content implements HowToInterface {
 
     if (data.description !== undefined) response.data.attributes.description = JSON.stringify(data.description);
     if (data.pages !== undefined) response.data.attributes.pages = data.pages;
+    if (data.howToType !== undefined) response.data.attributes.howToType = data.howToType;
+    if (data.slug !== undefined) response.data.attributes.slug = data.slug;
+    if (data.order !== undefined) response.data.attributes.order = data.order;
+    if (data.summary !== undefined) response.data.attributes.summary = data.summary;
+    if (data.tags !== undefined) response.data.attributes.tags = data.tags;
+    if (data.contextualKeys !== undefined) response.data.attributes.contextualKeys = data.contextualKeys;
+    if (data.draft !== undefined) response.data.attributes.draft = data.draft;
 
     return response;
   }

package/src/features/how-to/data/HowToInterface.ts

@@ -3,9 +3,23 @@ import { ContentInput, ContentInterface } from "../../content/data/content.inter
 export type HowToInput = ContentInput & {
   description?: any;
   pages?: string | undefined | null;
+  howToType?: string;
+  slug?: string;
+  order?: number;
+  summary?: string;
+  tags?: string[];
+  contextualKeys?: string[];
+  draft?: boolean;
 };
 
 export interface HowToInterface extends ContentInterface {
   get description(): any;
   get pages(): string | undefined;
+  get howToType(): string | undefined;
+  get slug(): string | undefined;
+  get order(): number | undefined;
+  get summary(): string | undefined;
+  get tags(): string[];
+  get contextualKeys(): string[];
+  get draft(): boolean;
 }

package/src/features/how-to/data/HowToService.ts

@@ -58,4 +58,65 @@ export class HowToService extends AbstractService {
       endpoint: new EndpointCreator({ endpoint: Modules.HowTo, id: params.howToId }).generate(),
     });
   }
+
+  static async findPublished(params: { howToType?: string } = {}): Promise<HowToInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: `public/${Modules.HowTo.name}` });
+    if (params.howToType) endpoint.addAdditionalParam("type", params.howToType);
+    return this.callApi({
+      type: Modules.HowTo,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  static async findPublishedArticle(params: { howToType: string; slug: string }): Promise<HowToInterface> {
+    return this.callApi<HowToInterface>({
+      type: Modules.HowTo,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({
+        endpoint: `public/${Modules.HowTo.name}`,
+        id: params.howToType,
+        childEndpoint: params.slug,
+      }).generate(),
+    });
+  }
+
+  static async findRelated(params: { howToType: string; slug: string }): Promise<HowToInterface[]> {
+    return this.callApi({
+      type: Modules.HowTo,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({
+        endpoint: `public/${Modules.HowTo.name}`,
+        id: params.howToType,
+        childEndpoint: params.slug,
+        childId: "related",
+      }).generate(),
+    });
+  }
+
+  static async addRelated(params: { howToId: string; relatedId: string }): Promise<HowToInterface> {
+    return this.callApi<HowToInterface>({
+      type: Modules.HowTo,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.HowTo,
+        id: params.howToId,
+        childEndpoint: "related",
+        childId: params.relatedId,
+      }).generate(),
+    });
+  }
+
+  static async removeRelated(params: { howToId: string; relatedId: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.HowTo,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.HowTo,
+        id: params.howToId,
+        childEndpoint: "related",
+        childId: params.relatedId,
+      }).generate(),
+    });
+  }
 }

package/src/index.ts

@@ -57,3 +57,7 @@ export * from "./features/rbac/rbac.module";
 // Assistant + AssistantMessage feature data
 export * from "./features/assistant/data";
 export * from "./features/assistant-message/data";
+
+// Help feature: NOT re-exported from the main barrel. Consumers must import from
+// the dedicated `@carlonicora/nextjs-jsonapi/help` subpath to keep the help-feature
+// surface (client contexts + server-only utilities) out of the main client bundle.