@carlonicora/nextjs-jsonapi 1.77.3 → 1.79.0

package/src/features/rbac/components/RbacPermissionPicker.tsx

@@ -1,130 +1,157 @@
 "use client";
 
-import { cn } from "../../../lib/utils";
+import { Popover as PopoverPrimitive } from "@base-ui/react/popover";
 import { CheckIcon, MinusIcon, XIcon } from "lucide-react";
 import { useTranslations } from "next-intl";
-import { useCallback, useState } from "react";
-import { Button, Checkbox, Input, Popover, PopoverContent, PopoverTrigger, Separator } from "../../../shadcnui";
+import { useCallback, useEffect, useState } from "react";
+import { cn } from "../../../lib/utils";
+import { Button, Checkbox, Input, Separator } from "../../../shadcnui";
 import { PermissionValue } from "../data/RbacTypes";
-import RbacPermissionCell from "./RbacPermissionCell";
 
+/**
+ * Controlled "global" picker. Exactly ONE instance is rendered by
+ * `RbacContainer`; the container holds `activePicker` state and drives this
+ * component's `open` + `anchor` props. Cells themselves are plain clickable
+ * elements — they just open this picker at their own DOM position.
+ *
+ * This replaces the previous design that mounted one `<Popover>` per cell
+ * (~2,600 total), which was both slow AND caused unreliable click handling
+ * across overlapping outside-click listeners.
+ */
 interface RbacPermissionPickerProps {
-  value: PermissionValue | undefined | null;
-  originalValue?: PermissionValue | undefined | null;
-  isRoleColumn?: boolean;
+  /** Whether the picker is open. Driven by `activePicker !== null` in the container. */
+  open: boolean;
+  /** DOM element the popup should anchor to. Required when `open`. */
+  anchor: HTMLElement | null;
+  /** Current effective value of the active cell (true | string | false | undefined). */
+  value: PermissionValue | undefined;
+  /** True if the active cell is in a role row (enables the "inherit from defaults" button). */
+  isRoleColumn: boolean;
+  /** Relationship paths the backend reports for the active cell's module. */
   knownSegments: string[];
   onSetValue: (value: PermissionValue) => void;
+  /** Only meaningful for role rows — clears the token so the row inherits defaults. */
   onClear?: () => void;
+  /** Called when the picker should close (outside-click, ESC, etc.). */
+  onClose: () => void;
 }
 
-export default function RbacPermissionPicker({
+export function RbacPermissionPicker({
+  open,
+  anchor,
   value,
-  originalValue,
-  isRoleColumn = false,
+  isRoleColumn,
   knownSegments,
   onSetValue,
   onClear,
+  onClose,
 }: RbacPermissionPickerProps) {
   const t = useTranslations();
-  const [open, setOpen] = useState(false);
   const [customSegment, setCustomSegment] = useState("");
 
-  // Parse current segments from value if it's a string
+  // Reset the custom-segment input when the picker is reopened for a different cell.
+  useEffect(() => {
+    if (!open) setCustomSegment("");
+  }, [open]);
+
   const currentSegments: string[] = typeof value === "string" ? value.split("|").filter(Boolean) : [];
 
   const toggleSegment = useCallback(
     (segment: string) => {
-      const newSegments = currentSegments.includes(segment)
+      const next = currentSegments.includes(segment)
         ? currentSegments.filter((s) => s !== segment)
         : [...currentSegments, segment];
-
-      if (newSegments.length === 0) {
-        onSetValue(false);
-      } else {
-        onSetValue(newSegments.join("|"));
-      }
+      if (next.length === 0) onSetValue(false);
+      else onSetValue(next.join("|"));
     },
     [currentSegments, onSetValue],
   );
 
   const addCustomSegment = useCallback(() => {
-    if (!customSegment.trim()) return;
     const segment = customSegment.trim();
+    if (!segment) return;
     if (!currentSegments.includes(segment)) {
-      const newSegments = [...currentSegments, segment];
-      onSetValue(newSegments.join("|"));
+      onSetValue([...currentSegments, segment].join("|"));
     }
     setCustomSegment("");
   }, [customSegment, currentSegments, onSetValue]);
 
   return (
-    <Popover open={open} onOpenChange={setOpen}>
-      <PopoverTrigger>
-        <RbacPermissionCell value={value} originalValue={originalValue} isRoleColumn={isRoleColumn} />
-      </PopoverTrigger>
-      <PopoverContent className="w-72 p-3" align="center">
-        <div className="space-y-3">
-          {/* Quick toggles */}
-          <div>
-            <p className="text-xs font-medium text-muted-foreground mb-2">{t("rbac.quick_value")}</p>
-            <div className="flex gap-2">
-              <Button
-                size="sm"
-                variant={value === true ? "default" : "outline"}
-                className={cn("flex-1 gap-1", value === true && "bg-emerald-600 hover:bg-emerald-700")}
-                onClick={() => {
-                  onSetValue(true);
-                  setOpen(false);
-                }}
-              >
-                <CheckIcon className="h-3 w-3" />
-                <span>true</span>
-              </Button>
-              <Button
-                size="sm"
-                variant={value === false ? "destructive" : "outline"}
-                className="flex-1 gap-1"
-                onClick={() => {
-                  onSetValue(false);
-                  setOpen(false);
-                }}
-              >
-                <XIcon className="h-3 w-3" />
-                <span>false</span>
-              </Button>
+    <PopoverPrimitive.Root
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) onClose();
+      }}
+    >
+      <PopoverPrimitive.Portal>
+        <PopoverPrimitive.Positioner
+          anchor={anchor ?? undefined}
+          side="bottom"
+          align="center"
+          sideOffset={4}
+          className="isolate z-50"
+        >
+          <PopoverPrimitive.Popup className="bg-popover text-popover-foreground ring-foreground/10 z-50 flex w-96 flex-col gap-3 rounded-lg p-3 text-xs shadow-md outline-hidden ring-1 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 duration-100">
+            {/* Quick value */}
+            <div>
+              <p className="text-muted-foreground mb-2 text-xs font-medium">{t("rbac.quick_value")}</p>
+              <div className="flex gap-2">
+                <Button
+                  size="sm"
+                  variant={value === true ? "default" : "outline"}
+                  className={cn("flex-1 gap-1", value === true && "bg-emerald-600 hover:bg-emerald-700")}
+                  onClick={() => {
+                    onSetValue(true);
+                    onClose();
+                  }}
+                >
+                  <CheckIcon className="h-3 w-3" />
+                  <span>true</span>
+                </Button>
+                <Button
+                  size="sm"
+                  variant={value === false ? "destructive" : "outline"}
+                  className="flex-1 gap-1"
+                  onClick={() => {
+                    onSetValue(false);
+                    onClose();
+                  }}
+                >
+                  <XIcon className="h-3 w-3" />
+                  <span>false</span>
+                </Button>
+              </div>
             </div>
-          </div>
 
-          {/* Clear / Inherit (role columns only) */}
-          {isRoleColumn && onClear && (
-            <>
-              <Separator />
-              <Button
-                size="sm"
-                variant="ghost"
-                className="w-full gap-1 text-muted-foreground"
-                onClick={() => {
-                  onClear();
-                  setOpen(false);
-                }}
-              >
-                <MinusIcon className="h-3 w-3" />
-                {t("rbac.inherit_from_defaults")}
-              </Button>
-            </>
-          )}
+            {/* Inherit from defaults — role rows only */}
+            {isRoleColumn && onClear && (
+              <>
+                <Separator />
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  className="text-muted-foreground w-full gap-1"
+                  onClick={() => {
+                    onClear();
+                    onClose();
+                  }}
+                >
+                  <MinusIcon className="h-3 w-3" />
+                  {t("rbac.inherit_from_defaults")}
+                </Button>
+              </>
+            )}
 
-          {/* Relationship path builder */}
-          {knownSegments.length > 0 && (
-            <>
-              <Separator />
-              <div>
-                <p className="text-xs font-medium text-muted-foreground mb-2">{t("rbac.relationships")}</p>
+            {/* Relationship-path builder — always visible so users can type custom paths */}
+            <Separator />
+            <div>
+              <p className="text-muted-foreground mb-2 text-xs font-medium">{t("rbac.relationships")}</p>
+              {knownSegments.length > 0 && (
                 <div className="max-h-40 space-y-1 overflow-y-auto">
                   {knownSegments.map((segment) => (
                     <label
                       key={segment}
-                      className="flex items-center gap-2 rounded px-1 py-0.5 text-sm hover:bg-muted cursor-pointer"
+                      className="hover:bg-muted flex cursor-pointer items-center gap-2 rounded px-1 py-0.5 text-sm"
                     >
                       <Checkbox
                         checked={currentSegments.includes(segment)}
@@ -134,46 +161,42 @@ export default function RbacPermissionPicker({
                     </label>
                   ))}
                 </div>
-
-                {/* Custom segment input */}
-                <div className="mt-2 flex gap-1">
-                  <Input
-                    value={customSegment}
-                    onChange={(e) => setCustomSegment(e.target.value)}
-                    placeholder={t("rbac.custom_segment_placeholder")}
-                    className="h-7 text-xs font-mono"
-                    onKeyDown={(e) => {
-                      if (e.key === "Enter") {
-                        e.preventDefault();
-                        addCustomSegment();
-                      }
-                    }}
-                  />
-                  <Button
-                    size="sm"
-                    variant="outline"
-                    className="h-7 px-2 text-xs"
-                    onClick={addCustomSegment}
-                    disabled={!customSegment.trim()}
-                  >
-                    +
-                  </Button>
-                </div>
-
-                {/* Preview */}
-                {currentSegments.length > 0 && (
-                  <div className="mt-2 rounded bg-muted p-2">
-                    <p className="text-xs text-muted-foreground mb-1">{t("rbac.preview")}</p>
-                    <p className="text-xs font-mono break-all">{currentSegments.join("|")}</p>
-                  </div>
-                )}
+              )}
+              <div className="mt-2 flex gap-1">
+                <Input
+                  value={customSegment}
+                  onChange={(e) => setCustomSegment(e.target.value)}
+                  placeholder={t("rbac.custom_segment_placeholder")}
+                  className="h-7 font-mono text-xs"
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter") {
+                      e.preventDefault();
+                      addCustomSegment();
+                    }
+                  }}
+                />
+                <Button
+                  size="sm"
+                  variant="outline"
+                  className="h-7 px-2 text-xs"
+                  onClick={addCustomSegment}
+                  disabled={!customSegment.trim()}
+                >
+                  +
+                </Button>
               </div>
-            </>
-          )}
-        </div>
-      </PopoverContent>
-    </Popover>
+              {currentSegments.length > 0 && (
+                <div className="bg-muted mt-2 rounded p-2">
+                  <p className="text-muted-foreground mb-1 text-xs">{t("rbac.preview")}</p>
+                  <p className="font-mono text-xs break-all">{currentSegments.join("|")}</p>
+                </div>
+              )}
+            </div>
+          </PopoverPrimitive.Popup>
+        </PopoverPrimitive.Positioner>
+      </PopoverPrimitive.Portal>
+    </PopoverPrimitive.Root>
   );
 }
 
-export { RbacPermissionPicker };
+export default RbacPermissionPicker;

package/src/features/rbac/contexts/RbacContext.tsx

@@ -0,0 +1,209 @@
+"use client";
+
+import { DownloadIcon, Loader2Icon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { SharedProvider } from "../../../contexts";
+import { Modules } from "../../../core";
+import { usePageUrlGenerator } from "../../../hooks";
+import { BreadcrumbItemData } from "../../../interfaces";
+import { Button } from "../../../shadcnui";
+import { showError, showToast } from "../../../utils/toast";
+import { RbacService } from "../data/RbacService";
+import type { ActionType, PermissionValue, PermToken, RbacMatrix, RbacModuleBlock } from "../data/RbacTypes";
+
+const DEFAULT_OUTPUT_PATH = "apps/api/src/rbac/permissions.ts";
+
+function upsertToken(tokens: PermToken[] | undefined, action: ActionType, scope: PermissionValue): PermToken[] {
+  const next = (tokens ?? []).filter((t) => t.action !== action);
+  // `scope === false` has no representation in the matrix — absence of a
+  // token for an action IS the "deny" semantics. See RbacContainer helpers.
+  if (scope === false) return next;
+  next.push({ action, scope });
+  return next;
+}
+
+function removeToken(tokens: PermToken[] | undefined, action: ActionType): PermToken[] {
+  return (tokens ?? []).filter((t) => t.action !== action);
+}
+
+interface RbacContextType {
+  matrix: RbacMatrix | null;
+  modulePaths: Record<string, readonly string[]>;
+  loading: boolean;
+  error: string | null;
+  saving: boolean;
+  roleNames?: Record<string, string>;
+  moduleNames?: Record<string, string>;
+  updateCell: (moduleId: string, rowKey: "default" | string, action: ActionType, value: PermissionValue) => void;
+  clearCell: (moduleId: string, roleId: string, action: ActionType) => void;
+}
+
+const RbacContext = createContext<RbacContextType | undefined>(undefined);
+
+type RbacProviderProps = {
+  children: ReactNode;
+  /** UUID → PascalCase map for roles (e.g. from `@neural-erp/shared`'s `RoleId`). */
+  roleNames?: Record<string, string>;
+  /** UUID → PascalCase map for modules (e.g. from `@neural-erp/shared`'s `ModuleId`). */
+  moduleNames?: Record<string, string>;
+  /**
+   * Output path for the serialized `permissions.ts` file. Absolute, or
+   * relative to the API's repo root. Defaults to
+   * `"apps/api/src/rbac/permissions.ts"`.
+   */
+  outputPath?: string;
+};
+
+/**
+ * RbacProvider — owns the matrix state, the save handler, and the breadcrumb +
+ * title wiring. Renders the "Save to permissions.ts" button into
+ * `title.functions` so it appears in the page header, following the same
+ * convention as CompanyContext / other context providers in this codebase.
+ *
+ * The child `RbacContainer` is stateless — it consumes state via
+ * `useRbacContext()`.
+ */
+export const RbacProvider = ({
+  children,
+  roleNames,
+  moduleNames,
+  outputPath = DEFAULT_OUTPUT_PATH,
+}: RbacProviderProps) => {
+  const generateUrl = usePageUrlGenerator();
+  const t = useTranslations();
+
+  const [matrix, setMatrix] = useState<RbacMatrix | null>(null);
+  const [modulePaths, setModulePaths] = useState<Record<string, readonly string[]>>({});
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    RbacService.fetchMatrix()
+      .then((result) => {
+        if (cancelled) return;
+        setMatrix(result.matrix);
+        setModulePaths(result.modulePaths);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        console.error("Failed to load RBAC matrix:", err);
+        setError(t("rbac.loading_error"));
+      })
+      .finally(() => {
+        if (cancelled) return;
+        setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [t]);
+
+  const updateCell = useCallback<RbacContextType["updateCell"]>((moduleId, rowKey, action, value) => {
+    setMatrix((prev) => {
+      if (!prev) return prev;
+      const prevBlock: RbacModuleBlock = prev[moduleId] ?? { default: [] };
+      const prevTokens: PermToken[] | undefined =
+        rowKey === "default" ? prevBlock.default : (prevBlock as Record<string, PermToken[]>)[rowKey];
+      const nextTokens = upsertToken(prevTokens, action, value);
+      const nextBlock: RbacModuleBlock = { ...prevBlock, [rowKey]: nextTokens } as RbacModuleBlock;
+      return { ...prev, [moduleId]: nextBlock };
+    });
+  }, []);
+
+  const clearCell = useCallback<RbacContextType["clearCell"]>((moduleId, roleId, action) => {
+    setMatrix((prev) => {
+      if (!prev) return prev;
+      const prevBlock: RbacModuleBlock = prev[moduleId] ?? { default: [] };
+      const prevTokens: PermToken[] | undefined = (prevBlock as Record<string, PermToken[]>)[roleId];
+      if (!prevTokens || prevTokens.length === 0) return prev;
+      const nextTokens = removeToken(prevTokens, action);
+      const nextBlock: RbacModuleBlock = { ...prevBlock } as RbacModuleBlock;
+      if (nextTokens.length === 0) {
+        delete (nextBlock as Record<string, PermToken[]>)[roleId];
+      } else {
+        (nextBlock as Record<string, PermToken[]>)[roleId] = nextTokens;
+      }
+      return { ...prev, [moduleId]: nextBlock };
+    });
+  }, []);
+
+  const canSave = Boolean(roleNames && moduleNames && matrix && !saving);
+
+  const handleSave = useCallback(async () => {
+    if (!matrix || !roleNames || !moduleNames) return;
+    setSaving(true);
+    try {
+      await RbacService.saveMatrix({ matrix, roleNames, moduleNames, outputPath });
+      showToast(`Saved to ${outputPath}`);
+    } catch (err) {
+      console.error("Failed to save RBAC matrix:", err);
+      showError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setSaving(false);
+    }
+  }, [matrix, roleNames, moduleNames, outputPath]);
+
+  const breadcrumb = (): BreadcrumbItemData[] => {
+    const response: BreadcrumbItemData[] = [];
+    response.push({
+      name: t(`entities.rbac`, { count: 2 }),
+      href: generateUrl({ page: Modules.RbacMatrix }),
+    });
+    return response;
+  };
+
+  const title = () => {
+    const response: {
+      type: string;
+      functions?: ReactNode;
+    } = {
+      type: t(`entities.rbac`, { count: 2 }),
+    };
+
+    const functions: ReactNode[] = [];
+    functions.push(
+      <Button key="rbacSave" size="sm" onClick={handleSave} disabled={!canSave} className="gap-1">
+        {saving ? <Loader2Icon className="h-3.5 w-3.5 animate-spin" /> : <DownloadIcon className="h-3.5 w-3.5" />}
+        Save to permissions.ts
+      </Button>,
+    );
+    if (functions.length > 0) response.functions = functions;
+
+    return response;
+  };
+
+  // Memoize the context value so stable-identity child consumers don't
+  // re-render when only title/breadcrumbs change.
+  const contextValue = useMemo<RbacContextType>(
+    () => ({
+      matrix,
+      modulePaths,
+      loading,
+      error,
+      saving,
+      roleNames,
+      moduleNames,
+      updateCell,
+      clearCell,
+    }),
+    [matrix, modulePaths, loading, error, saving, roleNames, moduleNames, updateCell, clearCell],
+  );
+
+  return (
+    <SharedProvider value={{ breadcrumbs: breadcrumb(), title: title() }}>
+      <RbacContext.Provider value={contextValue}>{children}</RbacContext.Provider>
+    </SharedProvider>
+  );
+};
+
+export const useRbacContext = (): RbacContextType => {
+  const ctx = useContext(RbacContext);
+  if (!ctx) {
+    throw new Error("useRbacContext must be used within an RbacProvider");
+  }
+  return ctx;
+};

package/src/features/rbac/contexts/index.ts

@@ -0,0 +1 @@
+export * from "./RbacContext";

package/src/features/rbac/data/RbacMatrixModel.ts

@@ -0,0 +1,84 @@
+import { AbstractApiData, JsonApiHydratedDataInterface } from "../../../core";
+import type { RbacMatrix } from "./RbacTypes";
+
+/**
+ * Input shape accepted by `RbacMatrixModel.createJsonApi()` for a PUT request
+ * to the dev matrix endpoint.
+ */
+export interface RbacMatrixInput {
+  matrix: RbacMatrix;
+  roleNames: Record<string, string>;
+  moduleNames: Record<string, string>;
+  outputPath: string;
+}
+
+/**
+ * Frontend model for the dev-only `rbac-matrix` JSON:API resource.
+ *
+ * Backend contract (see `rbac-dev.controller.ts`):
+ *  - `GET /_dev/rbac/matrix` → `{ data: { type: "rbac-matrix", id: "singleton",
+ *      attributes: { matrix } } }`
+ *  - `PUT /_dev/rbac/matrix` body: `{ data: { type: "rbac-matrix", attributes:
+ *      { matrix, roleNames, moduleNames, outputPath } } }`
+ *    → `{ data: { type: "rbac-matrix", id: "singleton", attributes: { bytesWritten, path } } }`
+ *
+ * The resource is a singleton (`id: "singleton"`) so there is no collection
+ * listing; the "read" and "write" shapes share a single model with optional
+ * fields populated depending on which endpoint produced the response.
+ */
+export class RbacMatrixModel extends AbstractApiData {
+  private _matrix?: RbacMatrix;
+  private _modulePaths?: Record<string, readonly string[]>;
+  private _bytesWritten?: number;
+  private _path?: string;
+
+  /** The RBAC matrix object (populated after a GET). */
+  get matrix(): RbacMatrix | undefined {
+    return this._matrix;
+  }
+
+  /**
+   * UUID-keyed map of each module's known BFS relationship paths (populated
+   * after a GET). Fed to the permission picker as scope suggestions.
+   */
+  get modulePaths(): Record<string, readonly string[]> | undefined {
+    return this._modulePaths;
+  }
+
+  /** Bytes written to the permissions.ts file (populated after a PUT). */
+  get bytesWritten(): number | undefined {
+    return this._bytesWritten;
+  }
+
+  /** Resolved absolute output path (populated after a PUT). */
+  get path(): string | undefined {
+    return this._path;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes ?? {};
+    this._matrix = attrs.matrix;
+    this._modulePaths = attrs.modulePaths;
+    this._bytesWritten = attrs.bytesWritten;
+    this._path = attrs.path;
+
+    return this;
+  }
+
+  createJsonApi(data: RbacMatrixInput): any {
+    return {
+      data: {
+        type: "rbac-matrix",
+        id: "singleton",
+        attributes: {
+          matrix: data.matrix,
+          roleNames: data.roleNames,
+          moduleNames: data.moduleNames,
+          outputPath: data.outputPath,
+        },
+      },
+    };
+  }
+}