@carlonicora/nextjs-jsonapi 1.73.0 → 1.75.0

package/src/core/abstracts/__tests__/identifier.spec.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import { AbstractApiData } from "../AbstractApiData";
+import { JsonApiHydratedDataInterface } from "../../interfaces/JsonApiHydratedDataInterface";
+
+// Concrete test subclass — uses default identifierFields ["name"]
+class DefaultModel extends AbstractApiData {
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    return this;
+  }
+}
+
+// Subclass with custom identifierFields
+class PersonModel extends AbstractApiData {
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    return this;
+  }
+}
+// Simulate what ModuleFactory does at registration time
+(PersonModel as any).identifierFields = ["first_name", "last_name"];
+
+// Subclass with single non-name field
+class OrderModel extends AbstractApiData {
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    return this;
+  }
+}
+(OrderModel as any).identifierFields = ["number"];
+
+function makeHydratedData(attributes: Record<string, any>): JsonApiHydratedDataInterface {
+  return {
+    jsonApi: {
+      type: "test",
+      id: "1",
+      attributes,
+    },
+    included: [],
+  };
+}
+
+describe("AbstractApiData.identifier", () => {
+  it("returns name attribute by default", () => {
+    const model = new DefaultModel();
+    model.rehydrate(makeHydratedData({ name: "Acme Corp" }));
+    expect(model.identifier).toBe("Acme Corp");
+  });
+
+  it("joins multiple fields with a space", () => {
+    const model = new PersonModel();
+    model.rehydrate(makeHydratedData({ first_name: "John", last_name: "Doe" }));
+    expect(model.identifier).toBe("John Doe");
+  });
+
+  it("filters out null fields", () => {
+    const model = new PersonModel();
+    model.rehydrate(makeHydratedData({ first_name: null, last_name: "Doe" }));
+    expect(model.identifier).toBe("Doe");
+  });
+
+  it("filters out undefined fields", () => {
+    const model = new PersonModel();
+    model.rehydrate(makeHydratedData({ last_name: "Doe" }));
+    expect(model.identifier).toBe("Doe");
+  });
+
+  it("filters out empty string fields", () => {
+    const model = new PersonModel();
+    model.rehydrate(makeHydratedData({ first_name: "", last_name: "Doe" }));
+    expect(model.identifier).toBe("Doe");
+  });
+
+  it("preserves numeric zero values", () => {
+    class ZeroModel extends AbstractApiData {
+      rehydrate(data: JsonApiHydratedDataInterface): this {
+        super.rehydrate(data);
+        return this;
+      }
+    }
+    (ZeroModel as any).identifierFields = ["quantity"];
+    const model = new ZeroModel();
+    model.rehydrate(makeHydratedData({ quantity: 0 }));
+    expect(model.identifier).toBe("0");
+  });
+
+  it("returns single non-name field", () => {
+    const model = new OrderModel();
+    model.rehydrate(makeHydratedData({ number: "ORD-001" }));
+    expect(model.identifier).toBe("ORD-001");
+  });
+
+  it("returns empty string when not rehydrated", () => {
+    const model = new DefaultModel();
+    expect(model.identifier).toBe("");
+  });
+
+  it("returns empty string when attribute is missing", () => {
+    const model = new DefaultModel();
+    model.rehydrate(makeHydratedData({}));
+    expect(model.identifier).toBe("");
+  });
+
+  it("does not share identifierFields between subclasses", () => {
+    const defaultModel = new DefaultModel();
+    const personModel = new PersonModel();
+    const orderModel = new OrderModel();
+
+    defaultModel.rehydrate(makeHydratedData({ name: "Test" }));
+    personModel.rehydrate(makeHydratedData({ first_name: "John", last_name: "Doe" }));
+    orderModel.rehydrate(makeHydratedData({ number: "ORD-001" }));
+
+    expect(defaultModel.identifier).toBe("Test");
+    expect(personModel.identifier).toBe("John Doe");
+    expect(orderModel.identifier).toBe("ORD-001");
+  });
+});

package/src/core/factories/__tests__/JsonApiDataFactory.test.ts

@@ -37,6 +37,9 @@ class MockDataClass implements Partial<ApiDataInterface> {
   rehydrate(data: any) {
     return this;
   }
+  get identifier() {
+    return "MockDataClass";
+  }
 }
 
 describe("JsonApiDataFactory", () => {

package/src/core/factories/__tests__/RehydrationFactory.test.ts

@@ -39,6 +39,9 @@ class MockDataClass implements Partial<ApiDataInterface> {
   createJsonApi(data: any) {
     return { type: this.type, attributes: data };
   }
+  get identifier() {
+    return "MockDataClass";
+  }
 }
 
 describe("RehydrationFactory", () => {

package/src/core/interfaces/ApiDataInterface.ts

@@ -8,6 +8,7 @@ export interface ApiDataInterface {
   get updatedAt(): Date;
   get self(): string | undefined;
   get jsonApi(): any;
+  get identifier(): string;
   generateApiUrl(params?: any): string;
   dehydrate(): JsonApiHydratedDataInterface;
   rehydrate(data: JsonApiHydratedDataInterface): this;

package/src/core/registry/__tests__/DataClassRegistry.getByJsonApiType.spec.ts

@@ -40,6 +40,9 @@ class MockTaxonomy implements ApiDataInterface {
   dehydrate(): any {
     return {};
   }
+  get identifier(): string {
+    return "MockTaxonomy";
+  }
 }
 
 class MockLeafTaxonomy implements ApiDataInterface {
@@ -79,6 +82,9 @@ class MockLeafTaxonomy implements ApiDataInterface {
   dehydrate(): any {
     return {};
   }
+  get identifier(): string {
+    return "MockLeafTaxonomy";
+  }
 }
 
 describe("DataClassRegistry.getByJsonApiType", () => {

package/src/core/registry/__tests__/DataClassRegistry.test.ts

@@ -34,6 +34,9 @@ class MockArticle implements Partial<ApiDataInterface> {
   createJsonApi(data: any) {
     return { type: this.type, attributes: data };
   }
+  get identifier() {
+    return "MockArticle";
+  }
 }
 
 describe("DataClassRegistry", () => {

package/src/core/registry/__tests__/ModuleRegistrar.test.ts

@@ -34,6 +34,9 @@ class MockUser implements Partial<ApiDataInterface> {
   createJsonApi(data: any) {
     return { type: this.type, attributes: data };
   }
+  get identifier() {
+    return "MockUser";
+  }
 }
 
 class MockArticle implements Partial<ApiDataInterface> {
@@ -66,6 +69,9 @@ class MockArticle implements Partial<ApiDataInterface> {
   createJsonApi(data: any) {
     return { type: this.type, attributes: data };
   }
+  get identifier() {
+    return "MockArticle";
+  }
 }
 
 // Mock Modules class with static getters

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

@@ -1,20 +1,11 @@
 "use client";
 
 import { useTranslations } from "next-intl";
-import { useCallback, useEffect, useMemo, useState } from "react";
-import { useWatch } from "react-hook-form";
-
-import { FormFieldWrapper, MultipleSelector, Option } from "../../../../components";
+import { EntityMultiSelector } from "../../../../components/forms/EntityMultiSelector";
 import { Modules } from "../../../../core";
-import { DataListRetriever, useDataListRetriever, useDebounce } from "../../../../hooks";
 import { HowToInterface } from "../../data/HowToInterface";
 import { HowToService } from "../../data/HowToService";
 
-type HowToMultiSelectType = {
-  id: string;
-  name: string;
-};
-
 type HowToMultiSelectorProps = {
   id: string;
   form: any;
@@ -26,10 +17,6 @@ type HowToMultiSelectorProps = {
   isRequired?: boolean;
 };
 
-type HowToOption = Option & {
-  howToData?: HowToInterface;
-};
-
 export default function HowToMultiSelector({
   id,
   form,
@@ -37,116 +24,23 @@ export default function HowToMultiSelector({
   label,
   placeholder,
   onChange,
-  maxCount = 3,
   isRequired = false,
 }: HowToMultiSelectorProps) {
   const t = useTranslations();
-  const [howToOptions, setHowToOptions] = useState<HowToOption[]>([]);
-  const [searchTerm, setSearchTerm] = useState<string>("");
-
-  const selectedHowTos: HowToMultiSelectType[] = useWatch({ control: form.control, name: id }) || [];
-
-  const data: DataListRetriever<HowToInterface> = useDataListRetriever({
-    retriever: (params) => HowToService.findMany(params),
-    retrieverParams: {},
-    ready: true,
-    module: Modules.HowTo,
-  });
-
-  const updateSearch = useCallback(
-    (searchedTerm: string) => {
-      if (searchedTerm.trim()) {
-        data.addAdditionalParameter("search", searchedTerm.trim());
-      } else {
-        data.removeAdditionalParameter("search");
-      }
-    },
-    [data],
-  );
-
-  const debouncedUpdateSearch = useDebounce(updateSearch, 500);
-
-  useEffect(() => {
-    debouncedUpdateSearch(searchTerm);
-  }, [debouncedUpdateSearch, searchTerm]);
-
-  useEffect(() => {
-    if (data.data && data.data.length > 0) {
-      const howTos = data.data as HowToInterface[];
-      const filteredHowTos = howTos.filter((howTo) => howTo.id !== currentHowTo?.id);
-
-      const options: HowToOption[] = filteredHowTos.map((howTo) => ({
-        label: howTo.name,
-        value: howTo.id,
-        howToData: howTo,
-      }));
-
-      // Add options for any already selected that aren't in search results
-      const existingOptionIds = new Set(options.map((option) => option.value));
-      const missingOptions: HowToOption[] = selectedHowTos
-        .filter((howTo) => !existingOptionIds.has(howTo.id))
-        .map((howTo) => ({
-          label: howTo.name,
-          value: howTo.id,
-          howToData: howTo as unknown as HowToInterface,
-        }));
-
-      setHowToOptions([...options, ...missingOptions]);
-    }
-  }, [data.data, currentHowTo, selectedHowTos]);
-
-  // Convert selected to Option[] format
-  const selectedOptions = useMemo(() => {
-    return selectedHowTos.map((howTo) => ({
-      value: howTo.id,
-      label: howTo.name,
-    }));
-  }, [selectedHowTos]);
-
-  const handleChange = (options: Option[]) => {
-    // Convert to form format
-    const formValues = options.map((option) => ({
-      id: option.value,
-      name: option.label,
-    }));
-
-    form.setValue(id, formValues, { shouldDirty: true, shouldTouch: true });
-
-    if (onChange) {
-      // Get full data for onChange callback
-      const fullData = options
-        .map((option) => {
-          const howToOption = howToOptions.find((opt) => opt.value === option.value);
-          return howToOption?.howToData;
-        })
-        .filter(Boolean) as HowToInterface[];
-      onChange(fullData);
-    }
-  };
-
-  // Search handler
-  const handleSearchSync = (search: string): Option[] => {
-    setSearchTerm(search);
-    return howToOptions;
-  };
 
   return (
-    <div className="flex w-full flex-col">
-      <FormFieldWrapper form={form} name={id} label={label} isRequired={isRequired}>
-        {() => (
-          <MultipleSelector
-            value={selectedOptions}
-            onChange={handleChange}
-            options={howToOptions}
-            placeholder={placeholder}
-            maxDisplayCount={maxCount}
-            hideClearAllButton
-            onSearchSync={handleSearchSync}
-            delay={0}
-            emptyIndicator={<span className="text-muted-foreground">{t("ui.search.no_results_generic")}</span>}
-          />
-        )}
-      </FormFieldWrapper>
-    </div>
+    <EntityMultiSelector<HowToInterface>
+      id={id}
+      form={form}
+      label={label}
+      placeholder={placeholder || t("ui.search.button")}
+      emptyText={t("ui.search.no_results_generic")}
+      isRequired={isRequired}
+      retriever={(params) => HowToService.findMany(params)}
+      module={Modules.HowTo}
+      getLabel={(howTo) => howTo.name}
+      excludeId={currentHowTo?.id}
+      onChange={onChange}
+    />
   );
 }

package/src/features/rbac/hooks/useRbacState.test.ts

@@ -13,6 +13,7 @@ const mockModule: ModuleInterface = {
   included: [],
   createdAt: new Date(),
   updatedAt: new Date(),
+  identifier: "pipelines",
   name: "pipelines",
   permissions: { create: true, read: true, update: true, delete: false },
 } as ModuleInterface;
@@ -24,6 +25,7 @@ const mockFeatures: FeatureInterface[] = [
     included: [],
     createdAt: new Date(),
     updatedAt: new Date(),
+    identifier: "CRM",
     name: "CRM",
     isCore: false,
     modules: [mockModule],

package/src/features/user/components/forms/UserMultiSelect.tsx

@@ -1,41 +1,13 @@
 "use client";
 
-import { Loader2 } from "lucide-react";
 import { useTranslations } from "next-intl";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useWatch } from "react-hook-form";
-import { FormFieldWrapper } from "../../../../components/forms";
+import { EntityMultiSelector } from "../../../../components/forms/EntityMultiSelector";
 import { Modules } from "../../../../core";
-import { DataListRetriever, useDataListRetriever, useDebounce } from "../../../../hooks";
-import { Avatar, AvatarFallback, AvatarImage, MultipleSelector } from "../../../../shadcnui";
-import { Option } from "../../../../shadcnui";
+import { Avatar, AvatarFallback, AvatarImage } from "../../../../shadcnui";
 import { useCurrentUserContext } from "../../contexts";
 import { UserInterface } from "../../data";
 import { UserService } from "../../data/user.service";
 
-// Type for user objects in the form
-type UserSelectType = {
-  id: string;
-  name: string;
-  avatar?: string;
-};
-
-type UserMultiSelectProps = {
-  id: string;
-  form: any;
-  currentUser?: UserInterface;
-  label?: string;
-  placeholder?: string;
-  onChange?: (users?: UserInterface[]) => void;
-  maxCount?: number;
-  isRequired?: boolean;
-};
-
-type UserOption = Option & {
-  userData?: UserInterface;
-  avatar?: string;
-};
-
 function UserAvatarIcon({ className, url, name }: { className?: string; url?: string; name?: string }) {
   return (
     <Avatar className={`${className || "h-4 w-4"}`}>
@@ -52,6 +24,17 @@ function UserAvatarIcon({ className, url, name }: { className?: string; url?: st
   );
 }
 
+type UserMultiSelectProps = {
+  id: string;
+  form: any;
+  currentUser?: UserInterface;
+  label?: string;
+  placeholder?: string;
+  onChange?: (users?: UserInterface[]) => void;
+  maxCount?: number;
+  isRequired?: boolean;
+};
+
 export function UserMultiSelect({
   id,
   form,
@@ -59,162 +42,32 @@ export function UserMultiSelect({
   label,
   placeholder,
   onChange,
-  maxCount = 3,
   isRequired = false,
 }: UserMultiSelectProps) {
   const t = useTranslations();
   const { company } = useCurrentUserContext<UserInterface>();
 
-  const searchTermRef = useRef<string>("");
-  const [searchTerm, _setSearchTerm] = useState<string>("");
-  const [isSearching, setIsSearching] = useState<boolean>(false);
-  const [userOptions, setUserOptions] = useState<UserOption[]>([]);
-
-  // Get the current selected users from the form
-  const selectedUsers: UserSelectType[] = useWatch({ control: form.control, name: id }) || [];
-
-  const data: DataListRetriever<UserInterface> = useDataListRetriever({
-    ready: !!company,
-    retriever: (params) => {
-      return UserService.findAllUsers(params);
-    },
-    retrieverParams: { companyId: company?.id },
-    module: Modules.User,
-  }) as DataListRetriever<UserInterface>;
-
-  useEffect(() => {
-    if (company) data.setReady(true);
-  }, [company]);
-
-  const search = useCallback(
-    async (searchedTerm: string) => {
-      try {
-        if (searchedTerm === searchTermRef.current) return;
-        setIsSearching(true);
-        searchTermRef.current = searchedTerm;
-        await data.search(searchedTerm);
-      } finally {
-        setIsSearching(false);
-      }
-    },
-    [searchTermRef, data],
-  );
-
-  const updateSearchTerm = useDebounce(search, 500);
-
-  useEffect(() => {
-    setIsSearching(true);
-    updateSearchTerm(searchTerm);
-  }, [updateSearchTerm, searchTerm]);
-
-  // Update userOptions when data changes or when initial selected users are available
-  useEffect(() => {
-    if (data.data && data.data.length > 0) {
-      const users = data.data as UserInterface[];
-      const filteredUsers = users.filter((user) => user.id !== currentUser?.id);
-
-      const options: UserOption[] = filteredUsers.map((user) => ({
-        label: user.name,
-        value: user.id,
-        userData: user,
-        avatar: user.avatar,
-      }));
-
-      // Add options for any already selected users that aren't in search results
-      const existingOptionIds = new Set(options.map((option) => option.value));
-      const missingOptions: UserOption[] = selectedUsers
-        .filter((user) => !existingOptionIds.has(user.id))
-        .map((user) => ({
-          label: user.name,
-          value: user.id,
-          userData: user as unknown as UserInterface,
-          avatar: user.avatar,
-        }));
-
-      setUserOptions([...options, ...missingOptions]);
-    }
-  }, [data.data, currentUser, selectedUsers]);
-
-  // Convert selected users to Option[] format
-  const selectedOptions = useMemo(() => {
-    return selectedUsers.map((user) => ({
-      value: user.id,
-      label: user.name,
-    }));
-  }, [selectedUsers]);
-
-  const handleChange = (options: Option[]) => {
-    // Convert to form format
-    const formValues = options.map((option) => {
-      const userOption = userOptions.find((opt) => opt.value === option.value);
-      return {
-        id: option.value,
-        name: option.label,
-        avatar: userOption?.avatar,
-      };
-    });
-
-    form.setValue(id, formValues, { shouldDirty: true, shouldTouch: true });
-
-    if (onChange) {
-      // Get full user data for onChange callback
-      const fullUsers = options
-        .map((option) => {
-          const userOption = userOptions.find((opt) => opt.value === option.value);
-          return userOption?.userData;
-        })
-        .filter(Boolean) as UserInterface[];
-      onChange(fullUsers);
-    }
-  };
-
-  // Custom render function for dropdown options (with avatar)
-  const renderOption = (option: Option) => {
-    const userOption = option as UserOption;
-    return (
-      <span className="flex items-center gap-2">
-        <UserAvatarIcon url={userOption.avatar} name={option.label} />
-        {option.label}
-      </span>
-    );
-  };
-
-  // Search handler
-  const handleSearchSync = (search: string): Option[] => {
-    _setSearchTerm(search);
-    return userOptions;
-  };
-
   return (
-    <div className="flex w-full flex-col">
-      <FormFieldWrapper form={form} name={id} label={label} isRequired={isRequired}>
-        {() => (
-          <MultipleSelector
-            value={selectedOptions}
-            onChange={handleChange}
-            options={userOptions}
-            placeholder={placeholder}
-            maxDisplayCount={maxCount}
-            hideClearAllButton
-            onSearchSync={handleSearchSync}
-            delay={0}
-            renderOption={renderOption}
-            loadingIndicator={
-              isSearching ? (
-                <div className="flex items-center justify-center py-2">
-                  <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
-                  <span className="ml-2 text-sm text-muted-foreground">{t("ui.search.button")}</span>
-                </div>
-              ) : undefined
-            }
-            emptyIndicator={
-              <span className="text-muted-foreground">
-                {t("ui.search.no_results", { type: t("entities.users", { count: 2 }) })}
-              </span>
-            }
-          />
-        )}
-      </FormFieldWrapper>
-    </div>
+    <EntityMultiSelector<UserInterface>
+      id={id}
+      form={form}
+      label={label}
+      placeholder={placeholder || t("ui.search.button")}
+      emptyText={t("ui.search.no_results", { type: t("entities.users", { count: 2 }) })}
+      isRequired={isRequired}
+      retriever={(params) => UserService.findAllUsers(params)}
+      retrieverParams={{ companyId: company?.id }}
+      module={Modules.User}
+      getLabel={(user) => user.name}
+      toFormValue={(user) => ({ id: user.id, name: user.name, avatar: user.avatar })}
+      excludeId={currentUser?.id}
+      onChange={onChange}
+      renderOption={(user) => (
+        <span className="flex items-center gap-2">
+          <UserAvatarIcon url={user.avatar} name={user.name} />
+          {user.name}
+        </span>
+      )}
+    />
   );
 }

package/src/permissions/types.ts

@@ -103,6 +103,7 @@ export type ModuleFactory = (params: {
   feature?: string;
   moduleId?: string;
   icon?: LucideIcon;
+  identifier?: string[];
   inclusions?: Record<
     string,
     {

package/src/testing/factories/createMockApiData.ts

@@ -103,6 +103,13 @@ export function createMockApiData(options: CreateMockApiDataOptions): ApiDataInt
       id,
       attributes: data,
     }),
+    get identifier() {
+      const identifierFields = ["name"];
+      return identifierFields
+        .map((field) => attributes[field])
+        .filter((v) => v != null && v !== "")
+        .join(" ");
+    },
   };
 
   // Add attribute accessors to the mock object