From df544047332a9ea5f71e744b12b33bbbb393721b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Va=CC=81clav=20Volhejn?= <vaclav.volhejn@gmail.com>
Date: Wed, 1 Oct 2025 22:21:03 +0200
Subject: [PATCH] Group by category

---
 jsdoc/jsdoc-synonyms.js                       |  8 +++
 packages/motion/motion.mjs                    | 15 +++++
 .../src/repl/components/panel/Reference.jsx   | 60 ++++++++++++-------
 3 files changed, 63 insertions(+), 20 deletions(-)

diff --git a/jsdoc/jsdoc-synonyms.js b/jsdoc/jsdoc-synonyms.js
index d59c8dac4..aed0dcc06 100644
--- a/jsdoc/jsdoc-synonyms.js
+++ b/jsdoc/jsdoc-synonyms.js
@@ -12,6 +12,14 @@ function defineTags(dictionary) {
       doclet.synonyms = doclet.synonyms_text.split(/[ ,]+/);
     },
   });
+
+  dictionary.defineTag('group', {
+    mustHaveValue: true,
+    onTagged: function (doclet, tag) {
+      doclet.group = tag.value;
+      console.log('TAGGED GROUP:', doclet.group);
+    },
+  });
 }
 
 module.exports = { defineTags: defineTags };
diff --git a/packages/motion/motion.mjs b/packages/motion/motion.mjs
index 875704eae..cba814a84 100644
--- a/packages/motion/motion.mjs
+++ b/packages/motion/motion.mjs
@@ -7,6 +7,7 @@ import { signal } from '../core/signal.mjs';
  * @name accelerationX
  * @return {Pattern}
  * @synonyms accX
+ * @group external_io
  * @example
  * n(accelerationX.segment(4).range(0,7)).scale("C:minor")
  *
@@ -17,6 +18,7 @@ import { signal } from '../core/signal.mjs';
  * @name accelerationY
  * @return {Pattern}
  * @synonyms accY
+ * @group external_io
  * @example
  * n(accelerationY.segment(4).range(0,7)).scale("C:minor")
  *
@@ -27,6 +29,7 @@ import { signal } from '../core/signal.mjs';
  * @name accelerationZ
  * @return {Pattern}
  * @synonyms accZ
+ * @group external_io
  * @example
  * n(accelerationZ.segment(4).range(0,7)).scale("C:minor")
  *
@@ -37,6 +40,7 @@ import { signal } from '../core/signal.mjs';
  * @name gravityX
  * @return {Pattern}
  * @synonyms gravX
+ * @group external_io
  * @example
  * n(gravityX.segment(4).range(0,7)).scale("C:minor")
  *
@@ -47,6 +51,7 @@ import { signal } from '../core/signal.mjs';
  * @name gravityY
  * @return {Pattern}
  * @synonyms gravY
+ * @group external_io
  * @example
  * n(gravityY.segment(4).range(0,7)).scale("C:minor")
  *
@@ -57,6 +62,7 @@ import { signal } from '../core/signal.mjs';
  * @name gravityZ
  * @return {Pattern}
  * @synonyms gravZ
+ * @group external_io
  * @example
  * n(gravityZ.segment(4).range(0,7)).scale("C:minor")
  *
@@ -67,6 +73,7 @@ import { signal } from '../core/signal.mjs';
  * @name rotationAlpha
  * @return {Pattern}
  * @synonyms rotA, rotZ, rotationZ
+ * @group external_io
  * @example
  * n(rotationAlpha.segment(4).range(0,7)).scale("C:minor")
  *
@@ -77,6 +84,7 @@ import { signal } from '../core/signal.mjs';
  * @name rotationBeta
  * @return {Pattern}
  * @synonyms rotB, rotX, rotationX
+ * @group external_io
  * @example
  * n(rotationBeta.segment(4).range(0,7)).scale("C:minor")
  *
@@ -87,6 +95,7 @@ import { signal } from '../core/signal.mjs';
  * @name rotationGamma
  * @return {Pattern}
  * @synonyms rotG, rotY, rotationY
+ * @group external_io
  * @example
  * n(rotationGamma.segment(4).range(0,7)).scale("C:minor")
  *
@@ -97,6 +106,7 @@ import { signal } from '../core/signal.mjs';
  * @name orientationAlpha
  * @return {Pattern}
  * @synonyms oriA, oriZ, orientationZ
+ * @group external_io
  * @example
  * n(orientationAlpha.segment(4).range(0,7)).scale("C:minor")
  *
@@ -107,6 +117,7 @@ import { signal } from '../core/signal.mjs';
  * @name orientationBeta
  * @return {Pattern}
  * @synonyms oriB, oriX, orientationX
+ * @group external_io
  * @example
  * n(orientationBeta.segment(4).range(0,7)).scale("C:minor")
  *
@@ -117,6 +128,7 @@ import { signal } from '../core/signal.mjs';
  * @name orientationGamma
  * @return {Pattern}
  * @synonyms oriG, oriY, orientationY
+ * @group external_io
  * @example
  * n(orientationGamma.segment(4).range(0,7)).scale("C:minor")
  *
@@ -127,6 +139,7 @@ import { signal } from '../core/signal.mjs';
  * @name absoluteOrientationAlpha
  * @return {Pattern}
  * @synonyms absOriA, absOriZ, absoluteOrientationZ
+ * @group external_io
  * @example
  * n(absoluteOrientationAlpha.segment(4).range(0,7)).scale("C:minor")
  *
@@ -137,6 +150,7 @@ import { signal } from '../core/signal.mjs';
  * @name absoluteOrientationBeta
  * @return {Pattern}
  * @synonyms absOriB, absOriX, absoluteOrientationX
+ * @group external_io
  * @example
  * n(absoluteOrientationBeta.segment(4).range(0,7)).scale("C:minor")
  *
@@ -147,6 +161,7 @@ import { signal } from '../core/signal.mjs';
  * @name absoluteOrientationGamma
  * @return {Pattern}
  * @synonyms absOriG, absOriY, absoluteOrientationY
+ * @group external_io
  * @example
  * n(absoluteOrientationGamma.segment(4).range(0,7)).scale("C:minor")
  *
diff --git a/website/src/repl/components/panel/Reference.jsx b/website/src/repl/components/panel/Reference.jsx
index 6007667fa..a7b4702c4 100644
--- a/website/src/repl/components/panel/Reference.jsx
+++ b/website/src/repl/components/panel/Reference.jsx
@@ -17,13 +17,13 @@ const availableFunctions = (() => {
       seen.add(s);
       // Swap `doc.name` in for `s` in the list of synonyms
       const synonymsWithDoc = [doc.name, ...synonyms].filter((x) => x && x !== s);
-      functions.push({
-        ...doc,
-        name: s, // update names for the synonym
-        longname: s,
-        synonyms: synonymsWithDoc,
-        synonyms_text: synonymsWithDoc.join(', '),
-      });
+      // functions.push({
+      //   ...doc,
+      //   name: s, // update names for the synonym
+      //   longname: s,
+      //   synonyms: synonymsWithDoc,
+      //   synonyms_text: synonymsWithDoc.join(', '),
+      // });
     }
   }
   return functions.sort((a, b) => /* a.meta.filename.localeCompare(b.meta.filename) +  */ a.name.localeCompare(b.name));
@@ -52,6 +52,19 @@ export function Reference() {
     });
   }, [search]);
 
+  const visibleFunctionsByGroup = (() => {
+    const groups = {};
+    for (const doc of visibleFunctions) {
+      const group = doc.group || 'Ungrouped';
+      if (!groups[group]) {
+        groups[group] = [];
+      }
+      groups[group].push(doc);
+    }
+    return groups;
+  })();
+  console.log(visibleFunctionsByGroup);
+
   return (
     <div className="flex h-full w-full p-2 overflow-hidden">
       <div className="h-full  flex flex-col gap-2 w-1/3 max-w-72 ">
@@ -59,18 +72,25 @@ export function Reference() {
           <Textbox className="w-full" placeholder="Search" value={search} onChange={setSearch} />
         </div>
         <div className="flex flex-col h-full overflow-y-auto  gap-1.5 bg-background bg-opacity-50  rounded-md">
-          {visibleFunctions.map((entry, i) => (
-            <a
-              key={i}
-              className="cursor-pointer text-foreground flex-none hover:bg-lineHighlight overflow-x-hidden  px-1 text-ellipsis"
-              onClick={() => {
-                const el = document.getElementById(`doc-${i}`);
-                const container = document.getElementById('reference-container');
-                container.scrollTo(0, el.offsetTop);
-              }}
-            >
-              {entry.name} {/* <span className="text-gray-600">{entry.meta.filename}</span> */}
-            </a>
+          {Object.entries(visibleFunctionsByGroup).map(([groupName, groupEntries]) => (
+            <>
+              <h4 key={`group-${groupName}`} className="font-semibold text-foreground">
+                {groupName}
+              </h4>
+              {groupEntries.map((entry, i) => (
+                <a
+                  key={`group-${groupName}-entry-${i}`}
+                  className="cursor-pointer text-foreground flex-none hover:bg-lineHighlight overflow-x-hidden  px-1 text-ellipsis"
+                  onClick={() => {
+                    const el = document.getElementById(`doc-${entry.name}`);
+                    const container = document.getElementById('reference-container');
+                    container.scrollTo(0, el.offsetTop);
+                  }}
+                >
+                  {entry.name} {/* <span className="text-gray-600">{entry.meta.filename}</span> */}
+                </a>
+              ))}
+            </>
           ))}
         </div>
       </div>
@@ -86,7 +106,7 @@ export function Reference() {
           </p>
           {visibleFunctions.map((entry, i) => (
             <section key={i}>
-              <h3 id={`doc-${i}`}>{entry.name}</h3>
+              <h3 id={`doc-${entry.name}`}>{entry.name}</h3>
               {!!entry.synonyms_text && (
                 <p>
                   Synonyms: <code>{entry.synonyms_text}</code>