Improvements

Author: h-mayorquin

apps/probe-viewer/src/grouping/README.md

@@ -1,16 +1,12 @@
 # Sidebar grouping
 
 The probe sidebar turns a manufacturer's flat probe list into a hierarchy from
-an explicit, hand-curated config. There are no rules and no inference: every
+an explicit, hand-curated config. The goal is a more human-friendly menu: users
+may not know the probes' SKUs and instead recognize the marketing names and
+categories. There are no rules and no inference: every
 probe is placed by model id under a path of named nodes. A manufacturer with no
 config (everything except IMEC today) renders as a flat list.
 
-This replaced an earlier rule-based engine that derived the grouping by regex on
-the part number and substring-matching the free-text description. Those rules
-were fragile because the probe metadata does not carry the facts we group on
-(generation, family, length), so we were reconstructing editorial decisions from
-strings. The explicit file states those decisions directly instead.
-
 ## Format
 
 JSON (`imec_neuropixels.json`), because Vite imports it with no extra
@@ -21,7 +17,9 @@ order) at the leaves.
 `collapsible` is a per-node property that **defaults to `true`**, so only the
 exceptions need stating: the length bands set `collapsible: false`, while every
 other node omits it. `true` is a foldable header with a caret; `false` is a
-static, always-open divider.
+static, always-open divider. This is useful for divisions worth mentioning but
+not worth occluding, usually the finer levels, like the length bands of the
+non-human-primate (NHP) probes in Neuropixels.
 
 The walker (`groupEntries.ts`) attaches each manifest entry to the node listing
 its model, prunes empty branches, and collects anything not placed into a
@@ -32,5 +30,11 @@ manifest needs a home in the config.
 
 Edit the relevant `probes` list. To add a new manufacturer, add its JSON file
 and one line in `index.ts`. No engine changes. JSON has no comments, so if a
-placement is non-obvious, record the rationale here or in a `note` field on the
-node.
+placement is non-obvious, record the rationale in a `note` field on the node
+(documentation only, not rendered). For example, the Neuropixels NXT node:
+
+```json
+{ "label": "Neuropixels NXT",
+  "note": "NP3023/NP3024 describe themselves as 'Neuropixels 3.0' but belong to the NXT generation.",
+  "children": [ ... ] }
+```

apps/probe-viewer/src/grouping/groupEntries.ts

@@ -1,5 +1,5 @@
 import type { ManifestEntry } from "../types/probe";
-import type { GroupNode, HierarchyConfig, HierarchyNode } from "./types";
+import type { GroupNode, HierarchyConfig, DisplayCategory } from "./types";
 
 // Label for the trailing bucket that catches any probe present in the manifest
 // but not placed anywhere in the hierarchy. It is the visible signal that a new
@@ -18,7 +18,7 @@ export function groupEntries(
   for (const entry of entries) byModel.set(entry.model, entry);
   const placed = new Set<string>();
 
-  const walk = (node: HierarchyNode): GroupNode | null => {
+  const walk = (node: DisplayCategory): GroupNode | null => {
     const collapsible = node.collapsible ?? true;
 
     if (node.children) {

apps/probe-viewer/src/grouping/imec_neuropixels.json

@@ -25,6 +25,7 @@
         { "label": "Legacy", "probes": ["PRB2_1_2_0640_0", "PRB2_4_2_0640_0"] }
       ] },
     { "label": "Neuropixels NXT",
+      "note": "NP3023/NP3024 describe themselves as 'Neuropixels 3.0' but I am gruping them here as the NXT generation.",
       "children": [
         { "label": "Single-shank", "probes": ["NP3010", "NP3011"] },
         { "label": "Multi-shank", "probes": ["NP3020", "NP3021", "NP3022", "NP3023", "NP3024"] },

apps/probe-viewer/src/grouping/types.ts

@@ -9,17 +9,20 @@ import type { ManifestEntry } from "../types/probe";
 // need stating: the length bands set `collapsible: false` to render as static
 // dividers, and every other node omits it and stays a foldable header.
 
-export interface HierarchyNode {
+export interface DisplayCategory {
   label: string;
   // true (default) => a collapsible group header; false => a static, always-open
   // divider.
   collapsible?: boolean;
-  children?: HierarchyNode[];
+  // Free-text rationale for a non-obvious placement. Documentation only, since
+  // JSON has no comments; not rendered.
+  note?: string;
+  children?: DisplayCategory[];
   probes?: string[]; // model ids, in display order
 }
 
 export interface HierarchyConfig {
-  hierarchy: HierarchyNode[];
+  hierarchy: DisplayCategory[];
 }
 
 // One node of the resolved tree the walker returns, with manifest entries