@carlonicora/nextjs-jsonapi 1.74.0 → 1.75.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.74.0",
+  "version": "1.75.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

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

@@ -22,18 +22,9 @@ export function generateMultiSelectorTemplate(data: FrontendTemplateData): strin
 
 import { ${names.pascalCase}Interface } from "@/features/${data.importTargetDir}/${names.kebabCase}/data/${names.pascalCase}Interface";
 import { ${names.pascalCase}Service } from "@/features/${data.importTargetDir}/${names.kebabCase}/data/${names.pascalCase}Service";
-import { DataListRetriever, useDataListRetriever, useDebounce } from "@carlonicora/nextjs-jsonapi/client";
-import { FormFieldWrapper, MultipleSelector } from "@carlonicora/nextjs-jsonapi/components";
-import { Option } from "@carlonicora/nextjs-jsonapi/components";
+import { EntityMultiSelector } from "@carlonicora/nextjs-jsonapi/components";
 import { Modules } from "@carlonicora/nextjs-jsonapi/core";
-import { useCallback, useEffect, useMemo, useState } from "react";
 import { useTranslations } from "next-intl";
-import { useWatch } from "react-hook-form";
-
-type ${names.pascalCase}MultiSelectType = {
-  id: string;
-  ${displayProp}: string;
-};
 
 type ${names.pascalCase}MultiSelectorProps = {
   id: string;
@@ -46,10 +37,6 @@ type ${names.pascalCase}MultiSelectorProps = {
   isRequired?: boolean;
 };
 
-type ${names.pascalCase}Option = Option & {
-  ${names.camelCase}Data?: ${names.pascalCase}Interface;
-};
-
 export default function ${names.pascalCase}MultiSelector({
   id,
   form,
@@ -57,117 +44,24 @@ export default function ${names.pascalCase}MultiSelector({
   label,
   placeholder,
   onChange,
-  maxCount = 3,
   isRequired = false,
 }: ${names.pascalCase}MultiSelectorProps) {
   const t = useTranslations();
-  const [${names.camelCase}Options, set${names.pascalCase}Options] = useState<${names.pascalCase}Option[]>([]);
-  const [searchTerm, setSearchTerm] = useState<string>("");
-
-  const selected${names.pluralPascal}: ${names.pascalCase}MultiSelectType[] = useWatch({ control: form.control, name: id }) || [];
-
-  const data: DataListRetriever<${names.pascalCase}Interface> = useDataListRetriever({
-    retriever: (params) => ${names.pascalCase}Service.findMany(params),
-    retrieverParams: {},
-    ready: true,
-    module: Modules.${names.pascalCase},
-  });
-
-  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 ${names.pluralCamel} = data.data as ${names.pascalCase}Interface[];
-      const filtered${names.pluralPascal} = ${names.pluralCamel}.filter((${names.camelCase}) => ${names.camelCase}.id !== current${names.pascalCase}?.id);
-
-      const options: ${names.pascalCase}Option[] = filtered${names.pluralPascal}.map((${names.camelCase}) => ({
-        label: ${names.camelCase}.${displayProp},
-        value: ${names.camelCase}.id,
-        ${names.camelCase}Data: ${names.camelCase},
-      }));
-
-      // Add options for any already selected that aren't in search results
-      const existingOptionIds = new Set(options.map((option) => option.value));
-      const missingOptions: ${names.pascalCase}Option[] = selected${names.pluralPascal}
-        .filter((${names.camelCase}) => !existingOptionIds.has(${names.camelCase}.id))
-        .map((${names.camelCase}) => ({
-          label: ${names.camelCase}.${displayProp},
-          value: ${names.camelCase}.id,
-          ${names.camelCase}Data: ${names.camelCase} as unknown as ${names.pascalCase}Interface,
-        }));
-
-      set${names.pascalCase}Options([...options, ...missingOptions]);
-    }
-  }, [data.data, current${names.pascalCase}, selected${names.pluralPascal}]);
-
-  // Convert selected to Option[] format
-  const selectedOptions = useMemo(() => {
-    return selected${names.pluralPascal}.map((${names.camelCase}) => ({
-      value: ${names.camelCase}.id,
-      label: ${names.camelCase}.${displayProp},
-    }));
-  }, [selected${names.pluralPascal}]);
-
-  const handleChange = (options: Option[]) => {
-    // Convert to form format
-    const formValues = options.map((option) => ({
-      id: option.value,
-      ${displayProp}: option.label,
-    }));
-
-    form.setValue(id, formValues, { shouldDirty: true, shouldTouch: true });
-
-    if (onChange) {
-      // Get full data for onChange callback
-      const fullData = options
-        .map((option) => {
-          const ${names.camelCase}Option = ${names.camelCase}Options.find((opt) => opt.value === option.value);
-          return ${names.camelCase}Option?.${names.camelCase}Data;
-        })
-        .filter(Boolean) as ${names.pascalCase}Interface[];
-      onChange(fullData);
-    }
-  };
-
-  // Search handler
-  const handleSearchSync = (search: string): Option[] => {
-    setSearchTerm(search);
-    return ${names.camelCase}Options;
-  };
 
   return (
-    <div className="flex w-full flex-col">
-      <FormFieldWrapper form={form} name={id} label={label} isRequired={isRequired}>
-        {() => (
-          <MultipleSelector
-            value={selectedOptions}
-            onChange={handleChange}
-            options={${names.camelCase}Options}
-            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<${names.pascalCase}Interface>
+      id={id}
+      form={form}
+      label={label}
+      placeholder={placeholder || t("ui.search.button")}
+      emptyText={t("ui.search.no_results_generic")}
+      isRequired={isRequired}
+      retriever={(params) => ${names.pascalCase}Service.findMany(params)}
+      module={Modules.${names.pascalCase}}
+      getLabel={(${names.camelCase}) => ${displayProp === "id" ? `${names.camelCase}.id` : `${names.camelCase}.${displayProp}`}}
+      excludeId={current${names.pascalCase}?.id}
+      onChange={onChange}
+    />
   );
 }
 `;

package/src/components/forms/EntityMultiSelector.tsx

@@ -0,0 +1,325 @@
+"use client";
+
+import { ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useWatch } from "react-hook-form";
+import { CheckIcon, ChevronDownIcon, SearchIcon, XIcon } from "lucide-react";
+import { Badge } from "../../shadcnui/ui/badge";
+import { Input } from "../../shadcnui/ui/input";
+import { Popover, PopoverContent, PopoverTrigger } from "../../shadcnui/ui/popover";
+import { FormFieldWrapper } from "./FormFieldWrapper";
+import { type DataListRetriever, useDataListRetriever } from "../../hooks/useDataListRetriever";
+import { useDebounce } from "../../hooks/useDebounce";
+
+type EntityMultiSelectorProps<T extends { id: string }> = {
+  id: string;
+  form: any;
+  label?: string;
+  placeholder?: string;
+  emptyText?: string;
+  isRequired?: boolean;
+  retriever: (params: any) => Promise<T[]>;
+  retrieverParams?: Record<string, any>;
+  module: any;
+  getLabel: (entity: T) => string;
+  toFormValue?: (entity: T) => { id: string; [key: string]: any };
+  getFormValueLabel?: (formValue: any) => string;
+  excludeId?: string;
+  onChange?: (entities?: T[]) => void;
+  renderOption?: (entity: T, isSelected: boolean) => ReactNode;
+};
+
+type OptionData<T> = {
+  id: string;
+  label: string;
+  entityData?: T;
+};
+
+const defaultFormValueLabel = (v: any) => v.name ?? v.id;
+
+export function EntityMultiSelector<T extends { id: string }>({
+  id,
+  form,
+  label,
+  placeholder = "Search...",
+  emptyText = "No results found.",
+  isRequired = false,
+  retriever,
+  retrieverParams = {},
+  module,
+  getLabel,
+  toFormValue,
+  getFormValueLabel,
+  excludeId,
+  onChange,
+  renderOption,
+}: EntityMultiSelectorProps<T>) {
+  const [open, setOpen] = useState(false);
+  const [searchTerm, setSearchTerm] = useState("");
+  const [options, setOptions] = useState<OptionData<T>[]>([]);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+
+  // Stabilize callback props in refs to prevent infinite re-render loops.
+  // These functions are passed inline by consumers (e.g. getLabel={(w) => w.name})
+  // which creates new references every render. Using refs keeps effects stable.
+  const getLabelRef = useRef(getLabel);
+  const toFormValueRef = useRef(toFormValue);
+  const getFormValueLabelRef = useRef(getFormValueLabel);
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    getLabelRef.current = getLabel;
+  }, [getLabel]);
+  useEffect(() => {
+    toFormValueRef.current = toFormValue;
+  }, [toFormValue]);
+  useEffect(() => {
+    getFormValueLabelRef.current = getFormValueLabel;
+  }, [getFormValueLabel]);
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+
+  const stableGetFormValueLabel = useCallback((v: any) => {
+    const fn = getFormValueLabelRef.current;
+    return fn ? fn(v) : defaultFormValueLabel(v);
+  }, []);
+
+  const stableToFormValue = useCallback((entity: T) => {
+    const fn = toFormValueRef.current;
+    return fn ? fn(entity) : { id: entity.id, name: getLabelRef.current(entity) };
+  }, []);
+
+  const selectedValues: { id: string; [key: string]: any }[] = useWatch({ control: form.control, name: id }) || [];
+  const selectedIds = useMemo(() => new Set(selectedValues.map((v) => v.id)), [selectedValues]);
+
+  const data: DataListRetriever<T> = useDataListRetriever({
+    retriever: (params) => retriever(params),
+    retrieverParams,
+    ready: true,
+    module,
+  });
+
+  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) {
+      const entities = data.data as T[];
+      const filtered = excludeId ? entities.filter((e) => e.id !== excludeId) : entities;
+
+      const entityOptions: OptionData<T>[] = filtered.map((entity) => ({
+        id: entity.id,
+        label: getLabelRef.current(entity),
+        entityData: entity,
+      }));
+
+      const existingIds = new Set(entityOptions.map((o) => o.id));
+      const missingOptions: OptionData<T>[] = selectedValues
+        .filter((v) => !existingIds.has(v.id))
+        .map((v) => ({
+          id: v.id,
+          label: stableGetFormValueLabel(v),
+          entityData: v as unknown as T,
+        }));
+
+      setOptions([...entityOptions, ...missingOptions]);
+    }
+  }, [data.data, excludeId, selectedValues, stableGetFormValueLabel]);
+
+  useEffect(() => {
+    if (open) {
+      setSearchTerm("");
+      requestAnimationFrame(() => {
+        searchInputRef.current?.focus();
+      });
+    }
+  }, [open]);
+
+  const toggleEntity = useCallback(
+    (option: OptionData<T>) => {
+      const current: any[] = form.getValues(id) ?? [];
+      let next: any[];
+
+      if (selectedIds.has(option.id)) {
+        next = current.filter((v: any) => v.id !== option.id);
+      } else {
+        const formValue = option.entityData
+          ? stableToFormValue(option.entityData)
+          : { id: option.id, name: option.label };
+        next = [...current, formValue];
+      }
+
+      form.setValue(id, next, { shouldDirty: true, shouldTouch: true });
+
+      const cb = onChangeRef.current;
+      if (cb) {
+        const fullData = next
+          .map((v: any) => options.find((opt) => opt.id === v.id)?.entityData)
+          .filter(Boolean) as T[];
+        cb(fullData);
+      }
+    },
+    [form, id, selectedIds, options, stableToFormValue],
+  );
+
+  const removeEntity = useCallback(
+    (entityId: string) => {
+      const current: any[] = form.getValues(id) ?? [];
+      const next = current.filter((v: any) => v.id !== entityId);
+      form.setValue(id, next, { shouldDirty: true, shouldTouch: true });
+
+      const cb = onChangeRef.current;
+      if (cb) {
+        const fullData = next
+          .map((v: any) => options.find((opt) => opt.id === v.id)?.entityData)
+          .filter(Boolean) as T[];
+        cb(fullData);
+      }
+    },
+    [form, id, options],
+  );
+
+  const sortedOptions = useMemo(() => {
+    const filtered = searchTerm.trim()
+      ? options.filter((o) => o.label.toLowerCase().includes(searchTerm.trim().toLowerCase()))
+      : options;
+
+    return [...filtered].sort((a, b) => {
+      const aSelected = selectedIds.has(a.id) ? 0 : 1;
+      const bSelected = selectedIds.has(b.id) ? 0 : 1;
+      return aSelected - bSelected;
+    });
+  }, [options, selectedIds, searchTerm]);
+
+  const triggerSummary = useMemo(() => {
+    if (selectedValues.length === 0) return null;
+    return selectedValues.map((v) => stableGetFormValueLabel(v)).join(", ");
+  }, [selectedValues, stableGetFormValueLabel]);
+
+  return (
+    <div className="flex w-full flex-col">
+      <FormFieldWrapper form={form} name={id} label={label} isRequired={isRequired}>
+        {() => (
+          <div className="flex flex-col gap-2">
+            <Popover open={open} onOpenChange={setOpen} modal>
+              <PopoverTrigger className="w-full">
+                <div className="bg-input/20 dark:bg-input/30 border-input flex min-h-7 w-full items-center gap-2 rounded-md border px-2 text-sm md:text-xs/relaxed">
+                  {selectedValues.length > 0 ? (
+                    <>
+                      <span className="text-foreground min-w-0 flex-1 truncate text-left">{triggerSummary}</span>
+                      <span className="bg-primary/10 text-primary shrink-0 rounded-full px-1.5 py-0.5 text-[0.625rem] font-medium">
+                        {selectedValues.length}
+                      </span>
+                    </>
+                  ) : (
+                    <span className="text-muted-foreground flex-1 text-left">{placeholder}</span>
+                  )}
+                  <ChevronDownIcon className="text-muted-foreground size-3.5 shrink-0" />
+                </div>
+              </PopoverTrigger>
+              <PopoverContent className="w-(--anchor-width) flex flex-col gap-0 p-0" align="start">
+                <div className="relative p-1.5">
+                  <SearchIcon className="text-muted-foreground pointer-events-none absolute top-1/2 left-3.5 size-3.5 -translate-y-1/2" />
+                  <Input
+                    ref={searchInputRef}
+                    placeholder={placeholder}
+                    type="text"
+                    className="h-8 w-full pr-7 pl-7 text-xs"
+                    value={searchTerm}
+                    onChange={(e) => setSearchTerm(e.target.value)}
+                  />
+                  {searchTerm && (
+                    <button
+                      type="button"
+                      className="text-muted-foreground hover:text-foreground absolute top-1/2 right-3.5 -translate-y-1/2"
+                      onClick={() => setSearchTerm("")}
+                    >
+                      <XIcon className="size-3.5" />
+                    </button>
+                  )}
+                </div>
+                <div className="max-h-52 overflow-y-auto p-1">
+                  {sortedOptions.length === 0 ? (
+                    <div className="text-muted-foreground py-4 text-center text-xs">{emptyText}</div>
+                  ) : (
+                    sortedOptions.map((option) => {
+                      const isSelected = selectedIds.has(option.id);
+                      return (
+                        <button
+                          key={option.id}
+                          type="button"
+                          className="hover:bg-muted flex w-full items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left text-xs/relaxed"
+                          onClick={() => toggleEntity(option)}
+                        >
+                          {renderOption && option.entityData ? (
+                            <>
+                              <div
+                                className={`border-primary flex size-4 shrink-0 items-center justify-center rounded-sm border transition-colors ${
+                                  isSelected ? "bg-primary text-primary-foreground" : "opacity-50"
+                                }`}
+                              >
+                                {isSelected && <CheckIcon className="size-3" />}
+                              </div>
+                              {renderOption(option.entityData, isSelected)}
+                            </>
+                          ) : (
+                            <>
+                              <div
+                                className={`border-primary flex size-4 shrink-0 items-center justify-center rounded-sm border transition-colors ${
+                                  isSelected ? "bg-primary text-primary-foreground" : "opacity-50"
+                                }`}
+                              >
+                                {isSelected && <CheckIcon className="size-3" />}
+                              </div>
+                              <span className={isSelected ? "text-foreground" : "text-muted-foreground"}>
+                                {option.label}
+                              </span>
+                            </>
+                          )}
+                        </button>
+                      );
+                    })
+                  )}
+                </div>
+              </PopoverContent>
+            </Popover>
+
+            {selectedValues.length > 0 && (
+              <div className="flex flex-wrap gap-1.5">
+                {selectedValues.map((value) => (
+                  <Badge
+                    key={value.id}
+                    variant="outline"
+                    className="h-auto gap-1.5 rounded-md px-2.5 py-1 pr-1.5 text-xs"
+                  >
+                    {stableGetFormValueLabel(value)}
+                    <button
+                      type="button"
+                      className="text-muted-foreground hover:text-foreground rounded-sm p-0.5 transition-colors"
+                      onClick={() => removeEntity(value.id)}
+                    >
+                      <XIcon className="size-3" />
+                    </button>
+                  </Badge>
+                ))}
+              </div>
+            )}
+          </div>
+        )}
+      </FormFieldWrapper>
+    </div>
+  );
+}

package/src/components/forms/index.ts

@@ -1,4 +1,5 @@
 export * from "./CommonAssociationForm";
+export * from "./EntityMultiSelector";
 export * from "./CommonDeleter";
 export * from "./CommonEditorButtons";
 export * from "./CommonEditorHeader";

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}
+    />
   );
 }