fix(evaluations): add documentation

Author: NicoSerranoP

.github/copilot-instructions.md

@@ -2,12 +2,6 @@
 
 > **Note:** These guidelines primarily apply to the `gas-benchmarks/` package but can serve as general standards for TypeScript code across the repository.
 
-## Benchmarks definitions
-
-- **Shield**: Converting public assets into private ones by depositing them into a privacy pool or protocol. (e.g. shield, bridge, encrypt, etc)
-- **Unshield**: Converting private assets back into public ones by withdrawing them from a privacy pool or protocol. (e.g. unshield, bridge, decrypt, etc)
-- **Transfer**: Moving private assets from one address to another within the privacy pool or protocol. (e.g. transfer, send, etc)
-
 ## 1. Clean and Concise Code
 
 - Write clean, short code with minimal boilerplate
@@ -18,6 +12,7 @@
   - Validated by `src/__tests__/constants.test.ts`
 - Minimize inline comments - code should be self-explanatory
 - No `console.log` (prohibited by ESLint)
+- Give space around operators for readability, but avoid unnecessary blank lines
 
 ## 2. Use examples and references in comments
 
@@ -43,13 +38,32 @@
 
 ## 6. Testing Requirements
 
-- **ALWAYS** run `pnpm run test` and `pnpm run benchmark` after changes
 - Do NOT complete work without running these verification steps
 - Fix all test failures and benchmark errors before finalizing
 
+# Specific Guidelines for the gas-benchmarks directory
+
+## Rules
+
+- Follow the general guidelines above, with a focus on clarity and maintainability in benchmark code
+- **ALWAYS** run `pnpm run test` and `pnpm run benchmark` after changes in the gas-benchmarks directory
+
+## Benchmarks definitions
+
+- **Shield**: Converting public assets into private ones by depositing them into a privacy pool or protocol. (e.g. shield, bridge, encrypt, etc)
+- **Unshield**: Converting private assets back into public ones by withdrawing them from a privacy pool or protocol. (e.g. unshield, bridge, decrypt, etc)
+- **Transfer**: Moving private assets from one address to another within the privacy pool or protocol. (e.g. transfer, send, etc)
+
 ## Examples
 
 - Protocol patterns: `src/railgun/index.ts`, `src/tornado-cash/index.ts`, `src/privacy-pools/index.ts`
 - Protocol specific constants to interact with: `src/railgun/constants.ts`, `src/tornado-cash/constants.ts`, `src/privacy-pools/constants.ts`
 - Functional programming: `src/utils/utils.ts`, `src/utils/rpc.ts`, `src/index.ts`
 - Type organization: `src/utils/types.ts`, `src/__tests__/types.ts`
+
+# Specific Guidelines for the project-evaluations directory
+
+## Rules
+
+- Follow the general guidelines above, with a focus on clarity and maintainability in evaluation code
+- **ALWAYS** run `pnpm run build` after changes in the project-evaluations directory unless these are changes only to project-evaluations/data/evaluations.json

project-evaluations/src/components/AddModal.tsx

@@ -11,6 +11,7 @@ interface AddModalProps {
 export default function AddModal({ onClose }: AddModalProps) {
   const [title, setTitle] = useState("");
   const [description, setDescription] = useState("");
+  const [documentation, setDocumentation] = useState("");
   const [selectedCategories, setSelectedCategories] = useState<Category[]>([]);
 
   const { addEvaluation } = useEvaluationsData();
@@ -24,12 +25,17 @@ export default function AddModal({ onClose }: AddModalProps) {
       alert("Please enter a title.");
       return;
     }
+
     if (selectedCategories.length === 0) {
       alert("Please select at least one category.");
       return;
     }
+
     const trimmedDescription = description.trim();
-    addEvaluation(trimmedTitle, trimmedDescription, selectedCategories);
+    const trimmedDocumentation = documentation.trim();
+
+    addEvaluation(trimmedTitle, trimmedDescription, trimmedDocumentation, selectedCategories);
+
     onClose();
   };
 
@@ -67,6 +73,18 @@ export default function AddModal({ onClose }: AddModalProps) {
               className={`${fieldClass} resize-none`}
             />
           </div>
+          <div>
+            <label className="block text-xs text-gray-400 mb-1">Documentation</label>
+            <textarea
+              rows={2}
+              placeholder="Documentation URL or link"
+              value={documentation}
+              onChange={(e) => {
+                setDocumentation(e.target.value);
+              }}
+              className={`${fieldClass} resize-none`}
+            />
+          </div>
           <div>
             <label className="block text-xs text-gray-400 mb-2">Categories</label>
             <div className="space-y-2 bg-gray-800 border border-gray-700 rounded p-3">

project-evaluations/src/components/ProtocolDetail.tsx

@@ -19,9 +19,10 @@ export default function ProtocolDetail({
   setSelectedId,
 }: ProtocolDetailProps) {
   const [editingField, setEditingField] = useState<string | null>(null);
-  const [editValues, setEditValues] = useState<{ title: string; description: string }>({
+  const [editValues, setEditValues] = useState<{ title: string; description: string; documentation: string }>({
     title: "",
     description: "",
+    documentation: "",
   });
 
   const evaluation = evaluations.find((entry) => entry.id === selectedId) ?? null;
@@ -34,11 +35,13 @@ export default function ProtocolDetail({
     );
   }
 
-  const startEdit = (field: "title" | "description"): void => {
+  const startEdit = (field: "title" | "description" | "documentation"): void => {
     if (field === "title") {
       setEditValues((prev) => ({ ...prev, title: evaluation.title }));
-    } else {
+    } else if (field === "description") {
       setEditValues((prev) => ({ ...prev, description: evaluation.description }));
+    } else {
+      setEditValues((prev) => ({ ...prev, documentation: evaluation.documentation }));
     }
     setEditingField(field);
   };
@@ -50,6 +53,7 @@ export default function ProtocolDetail({
         if (entry.id !== selectedId) return entry;
         if (editingField === "title") return { ...entry, title: editValues.title };
         if (editingField === "description") return { ...entry, description: editValues.description };
+        if (editingField === "documentation") return { ...entry, documentation: editValues.documentation };
         return entry;
       }),
     );
@@ -185,6 +189,56 @@ export default function ProtocolDetail({
             )}
           </div>
 
+          <div
+            className="group cursor-pointer mt-3"
+            onDoubleClick={() => {
+              startEdit("documentation");
+            }}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") startEdit("documentation");
+            }}
+            role="button"
+            tabIndex={0}
+          >
+            {editingField === "documentation" ? (
+              <div className="flex gap-2">
+                <textarea
+                  value={editValues.documentation}
+                  onChange={(e) => {
+                    setEditValues({ ...editValues, documentation: e.target.value });
+                  }}
+                  onKeyDown={(e) => {
+                    if (e.key === "Escape") cancelEdit();
+                  }}
+                  autoFocus
+                  className="text-sm text-gray-300 bg-gray-800 border border-indigo-500 rounded px-2 py-1 flex-1 resize-none"
+                  rows={2}
+                />
+                <div className="flex flex-col gap-2">
+                  <button
+                    onClick={saveEdit}
+                    className="text-xs px-2 py-1 bg-indigo-600 text-white rounded hover:bg-indigo-700 whitespace-nowrap"
+                  >
+                    Save
+                  </button>
+                  <button
+                    onClick={cancelEdit}
+                    className="text-xs px-2 py-1 bg-gray-700 text-gray-300 rounded hover:bg-gray-600 whitespace-nowrap"
+                  >
+                    Cancel
+                  </button>
+                </div>
+              </div>
+            ) : (
+              <div>
+                <label className="block text-xs text-gray-500 mb-1">Documentation</label>
+                <p className="text-sm text-gray-400 group-hover:text-gray-300 transition-colors">
+                  {evaluation.documentation || "Double-click to add documentation"}
+                </p>
+              </div>
+            )}
+          </div>
+
           <ProtocolCategories
             categories={evaluation.categories}
             onUpdate={(categories) => {

project-evaluations/src/data/evaluations.json

@@ -4,27 +4,31 @@
       "id": "railgun",
       "title": "RAILGUN",
       "description": "A privacy system for Ethereum using zk-SNARKs to shield ERC-20 tokens and ETH inside a smart contract, enabling private transfers and shielded DeFi interactions.",
+      "documentation": "https://docs.railgun.com/",
       "categories": ["Shielded pool"],
       "properties": []
     },
     {
       "id": "tornado-cash",
       "title": "Tornado Cash",
       "description": "A non-custodial, Ethereum-based mixer that uses zk-SNARKs to break the on-chain link between deposit and withdrawal addresses for fixed-denomination ETH and ERC-20 deposits.",
+      "documentation": "https://docs.railgun.com/",
       "categories": ["Mixer"],
       "properties": []
     },
     {
       "id": "privacy-pools",
       "title": "Privacy Pools",
       "description": "A privacy protocol that extends Tornado Cash with association set providers (ASPs), allowing users to prove membership in compliant subsets without revealing their identity.",
+      "documentation": "https://docs.railgun.com/",
       "categories": ["Shielded pool"],
       "properties": []
     },
     {
       "id": "intmax",
       "title": "Intmax",
       "description": "A stateless zkRollup optimised for private payments, pushing most data off-chain so that on-chain costs are minimal while preserving user-side privacy through client-side proving.",
+      "documentation": "https://docs.railgun.com/",
       "categories": ["Shielded pool", "L2"],
       "properties": []
     }

project-evaluations/src/data/utils.ts

@@ -14,7 +14,7 @@ export const useEvaluationsData = (
   setEvaluations: Dispatch<SetStateAction<Evaluation[]>>;
   selectedId: string | null;
   setSelectedId: Dispatch<SetStateAction<string | null>>;
-  addEvaluation: (title: string, description: string, categories: Category[]) => void;
+  addEvaluation: (title: string, description: string, documentation: string, categories: Category[]) => void;
 } => {
   const fallbackData = structuredClone(defaultData as EvaluationsData);
 
@@ -37,14 +37,15 @@ export const useEvaluationsData = (
       .catch(() => undefined);
   }, [url]);
 
-  const addEvaluation = (title: string, description: string, categories: Category[]): void => {
+  const addEvaluation = (title: string, description: string, documentation: string, categories: Category[]): void => {
     const newEvaluation: Evaluation = {
       id: title
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/(^-|-$)/g, ""),
       title,
       description,
+      documentation,
       categories,
       properties: [],
     };

project-evaluations/src/types.ts

@@ -28,6 +28,7 @@ export interface Evaluation {
   id: string;
   title: string;
   description: string;
+  documentation: string;
   categories: Category[];
   properties: Property[];
 }