add untracked files

Author: h-mayorquin

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

@@ -0,0 +1,39 @@
+# 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
+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
+dependency. The config is `{ hierarchy }`, a tree of nodes. Each node has a
+`label` and either `children` (more nodes) or `probes` (model ids, in display
+order) at the leaves.
+
+`collapsible` is a per-node property that **propagates to descendants**: a node
+uses its own `collapsible` when set, otherwise it inherits the resolved value of
+its parent, and the top-level default is `true`. So each platform sets
+`collapsible: true` and that flows down to its families, while each length band
+sets `collapsible: false` (a static, always-open divider) and that flows down to
+its probes. `true` is a foldable header with a caret; `false` is a static
+divider.
+
+The walker (`groupEntries.ts`) attaches each manifest entry to the node listing
+its model, prunes empty branches, and collects anything not placed into a
+trailing `Ungrouped` group. That bucket is the signal that a probe new to the
+manifest needs a home in the config.
+
+## Adding or moving a probe
+
+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.

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

@@ -0,0 +1,64 @@
+import type { ManifestEntry } from "../types/probe";
+import type { GroupNode, HierarchyConfig, HierarchyNode } 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
+// probe needs a home in the config.
+const UNGROUPED_LABEL = "Ungrouped";
+
+// Top-level default when a node does not set `collapsible` and has no parent.
+const ROOT_COLLAPSIBLE = true;
+
+// Resolves the explicit hierarchy against the given (already search-filtered)
+// entries: attaches each entry to the node that lists its model id, prunes
+// empty branches, and gathers anything unplaced into a trailing "Ungrouped"
+// group. `collapsible` is resolved per node, inheriting the parent's value when
+// the node does not set its own.
+export function groupEntries(
+  entries: ManifestEntry[],
+  config: HierarchyConfig,
+): GroupNode[] {
+  const byModel = new Map<string, ManifestEntry>();
+  for (const entry of entries) byModel.set(entry.model, entry);
+  const placed = new Set<string>();
+
+  const walk = (node: HierarchyNode, inherited: boolean): GroupNode | null => {
+    const collapsible = node.collapsible ?? inherited;
+
+    if (node.children) {
+      const children = node.children
+        .map((child) => walk(child, collapsible))
+        .filter((child): child is GroupNode => child !== null);
+      if (children.length === 0) return null;
+      const count = children.reduce((sum, child) => sum + child.count, 0);
+      return { label: node.label, collapsible, count, children };
+    }
+
+    const found: ManifestEntry[] = [];
+    for (const model of node.probes ?? []) {
+      const entry = byModel.get(model);
+      if (entry) {
+        found.push(entry);
+        placed.add(model);
+      }
+    }
+    if (found.length === 0) return null;
+    return { label: node.label, collapsible, count: found.length, entries: found };
+  };
+
+  const groups = config.hierarchy
+    .map((node) => walk(node, ROOT_COLLAPSIBLE))
+    .filter((group): group is GroupNode => group !== null);
+
+  const leftovers = entries.filter((entry) => !placed.has(entry.model));
+  if (leftovers.length > 0) {
+    groups.push({
+      label: UNGROUPED_LABEL,
+      collapsible: true,
+      count: leftovers.length,
+      entries: leftovers,
+    });
+  }
+
+  return groups;
+}

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

@@ -0,0 +1,34 @@
+{
+  "hierarchy": [
+    { "label": "Neuropixels 1.0", "collapsible": true,
+      "children": [
+        { "label": "Standard", "probes": ["NP1000", "NP1001"] },
+        { "label": "Non-human-primate",
+          "children": [
+            { "label": "short", "collapsible": false, "probes": ["NP1010", "NP1011", "NP1012", "NP1013", "NP1014", "NP1015", "NP1016", "NP1017"] },
+            { "label": "medium", "collapsible": false, "probes": ["NP1020", "NP1021", "NP1022"] },
+            { "label": "long / max", "collapsible": false, "probes": ["NP1030", "NP1031", "NP1032", "NP1033", "NP1040", "NP1041", "NP1042", "NP1050", "NP1051"] },
+            { "label": "passive", "collapsible": false, "probes": ["NP1200", "NP1210"] }
+          ] },
+        { "label": "Ultra High Density", "probes": ["NP1100", "NP1120", "NP1121", "NP1122", "NP1123"] },
+        { "label": "Optogenetics", "probes": ["NP1300"] },
+        { "label": "Legacy", "probes": ["PRB_1_2_0480_2", "PRB_1_4_0480_1", "PRB_1_4_0480_1_C"] }
+      ] },
+    { "label": "Neuropixels 2.0", "collapsible": true,
+      "children": [
+        { "label": "Non-human-primate",
+          "children": [
+            { "label": "short", "collapsible": false, "probes": ["NP2005", "NP2006"] }
+          ] },
+        { "label": "Single-shank", "probes": ["NP2000", "NP2003", "NP2004"] },
+        { "label": "Multi-shank", "probes": ["NP2010", "NP2013", "NP2014", "NP2020", "NP2021"] },
+        { "label": "Legacy", "probes": ["PRB2_1_2_0640_0", "PRB2_4_2_0640_0"] }
+      ] },
+    { "label": "Neuropixels NXT", "collapsible": true,
+      "children": [
+        { "label": "Single-shank", "probes": ["NP3010", "NP3011"] },
+        { "label": "Multi-shank", "probes": ["NP3020", "NP3021", "NP3022", "NP3023", "NP3024"] },
+        { "label": "Passive", "probes": ["NP3000"] }
+      ] }
+  ]
+}

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

@@ -0,0 +1,17 @@
+import type { HierarchyConfig } from "./types";
+import imecHierarchy from "./imec_neuropixels.json";
+
+// Registry mapping a manufacturer key (as it appears in the manifest) to its
+// explicit sidebar hierarchy. A manufacturer absent here has no hierarchy and
+// renders as a flat list, which is the default for every manufacturer other
+// than IMEC. Adding grouping for a new manufacturer is one JSON file plus one
+// line here, with no engine changes.
+//
+// JSON is used because Vite imports it with no extra dependency.
+const REGISTRY: Record<string, HierarchyConfig> = {
+  imec: imecHierarchy as HierarchyConfig,
+};
+
+export function getGroupingConfig(manufacturer: string): HierarchyConfig | undefined {
+  return REGISTRY[manufacturer];
+}

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

@@ -0,0 +1,37 @@
+import type { ManifestEntry } from "../types/probe";
+
+// Explicit, hand-curated sidebar hierarchy for one manufacturer. There are no
+// rules: every probe is placed by model id under the tree in imec.json, with
+// model ids at the leaves. A manufacturer with no config renders as a flat list
+// (see ./index.ts).
+//
+// Collapsibility is a per-node property that propagates to descendants: a node
+// uses its own `collapsible` when set, otherwise it inherits the resolved value
+// of its parent. The top-level default is `true`. So a platform marked
+// collapsible flows that down to its families, and a length band marked
+// non-collapsible flows that down to its probes, without either having to be
+// repeated on every node.
+
+export interface HierarchyNode {
+  label: string;
+  // true => a collapsible group header; false => a static, always-open divider.
+  // Omitted => inherit the parent's resolved value (root default: true).
+  collapsible?: boolean;
+  children?: HierarchyNode[];
+  probes?: string[]; // model ids, in display order
+}
+
+export interface HierarchyConfig {
+  hierarchy: HierarchyNode[];
+}
+
+// One node of the resolved tree the walker returns, with manifest entries
+// attached and `collapsible` resolved to a concrete boolean. A node has either
+// `children` (sub-divided) or `entries` (a leaf), never both.
+export interface GroupNode {
+  label: string;
+  collapsible: boolean;
+  count: number;
+  children?: GroupNode[];
+  entries?: ManifestEntry[];
+}