feat(config): add flexible layout configuration

Add support for configuring view layouts via runtime config JSON with
two approaches:

1. Simple grid layouts using 2D string arrays:
   { "layout": [["axial", "sagittal"], ["coronal", "volume"]] }

2. Nested hierarchical layouts with full control:
   {
     "layout": {
       "direction": "V",
       "items": [
         "axial",
         { "direction": "H", "items": ["volume", "coronal"] }
       ]
     }
   }

Features:
- String shortcuts for common views (axial, coronal, sagittal, volume, oblique)
- Full view objects with custom options (viewDirection, viewUp, orientation)
- Mix strings and full specs in nested layouts
- Backwards compatible with existing gridSize format

Implementation:
- Add Zod schemas for layout config validation
- Add parseGridLayout() and parseNestedLayout() parsers
- Add setLayoutWithViews() method to view store
- Add comprehensive e2e tests (4/4 new tests passing)

Related directories created in volview-backend/files:
- prostate-simple-grid/ - Example 2x2 grid layout
- prostate-custom-layout/ - Example asymmetric nested layout

Author: PaulHax

src/io/import/configJson.ts

@@ -11,15 +11,70 @@ import { actionToKey } from '@/src/composables/useKeyboardShortcuts';
 import { useSegmentGroupStore } from '@/src/store/segmentGroups';
 import { AnnotationToolStore } from '@/src/store/tools/useAnnotationTool';
 import useLoadDataStore from '@/src/store/load-data';
+import type { Layout, LayoutItem } from '@/src/types/layout';
+import type { ViewInfoInit } from '@/src/types/views';
 
 // --------------------------------------------------------------------------
-// Interface
+// View Specifications
 
-const layout = z
-  .object({
-    gridSize: z.tuple([z.number(), z.number()]).optional(),
-  })
-  .optional();
+const viewString = z.enum([
+  'axial',
+  'coronal',
+  'sagittal',
+  'volume',
+  'oblique',
+]);
+
+const view2D = z.object({
+  type: z.literal('2D'),
+  name: z.string().optional(),
+  orientation: z.enum(['Axial', 'Coronal', 'Sagittal']),
+});
+
+const view3D = z.object({
+  type: z.literal('3D'),
+  name: z.string().optional(),
+  viewDirection: z.enum(['Left', 'Right', 'Posterior', 'Anterior', 'Superior', 'Inferior']).optional(),
+  viewUp: z.enum(['Left', 'Right', 'Posterior', 'Anterior', 'Superior', 'Inferior']).optional(),
+});
+
+const viewOblique = z.object({
+  type: z.literal('Oblique'),
+  name: z.string().optional(),
+});
+
+const viewSpec = z.union([viewString, view2D, view3D, viewOblique]);
+
+// --------------------------------------------------------------------------
+// Layout Specifications
+
+type LayoutConfigItem = z.infer<typeof viewSpec> | {
+  direction: 'H' | 'V';
+  items: LayoutConfigItem[];
+};
+
+const layoutConfigItem: z.ZodType<LayoutConfigItem> = z.lazy(() =>
+  z.union([
+    viewSpec,
+    z.object({
+      direction: z.enum(['H', 'V']),
+      items: z.array(layoutConfigItem),
+    }),
+  ])
+);
+
+const layoutConfig = z.union([
+  z.array(z.array(viewString)),
+  z.object({
+    direction: z.enum(['H', 'V']),
+    items: z.array(layoutConfigItem),
+  }),
+  z.object({
+    gridSize: z.tuple([z.number(), z.number()]),
+  }),
+]);
+
+const layout = layoutConfig.optional();
 
 const shortcuts = z.record(zodEnumFromObjKeys(ACTIONS), z.string()).optional();
 
@@ -89,6 +144,138 @@ export const readConfigFile = async (configFile: File) => {
   return config.parse(JSON.parse(text));
 };
 
+// --------------------------------------------------------------------------
+// Layout Parsing
+
+const stringToViewInfoInit = (str: z.infer<typeof viewString>): ViewInfoInit => {
+  switch (str) {
+    case 'axial':
+      return { name: 'Axial', type: '2D', dataID: null, options: { orientation: 'Axial' } };
+    case 'coronal':
+      return { name: 'Coronal', type: '2D', dataID: null, options: { orientation: 'Coronal' } };
+    case 'sagittal':
+      return { name: 'Sagittal', type: '2D', dataID: null, options: { orientation: 'Sagittal' } };
+    case 'volume':
+      return { name: 'Volume', type: '3D', dataID: null, options: { viewDirection: 'Posterior', viewUp: 'Superior' } };
+    case 'oblique':
+      return { name: 'Oblique', type: 'Oblique', dataID: null, options: {} };
+    default:
+      throw new Error(`Unknown view string: ${str}`);
+  }
+};
+
+const viewSpecToViewInfoInit = (spec: z.infer<typeof viewSpec>): ViewInfoInit => {
+  if (typeof spec === 'string') {
+    return stringToViewInfoInit(spec);
+  }
+
+  if (spec.type === '2D') {
+    return {
+      name: spec.name ?? spec.orientation,
+      type: '2D',
+      dataID: null,
+      options: { orientation: spec.orientation },
+    };
+  }
+
+  if (spec.type === '3D') {
+    return {
+      name: spec.name ?? 'Volume',
+      type: '3D',
+      dataID: null,
+      options: {
+        viewDirection: spec.viewDirection ?? 'Posterior',
+        viewUp: spec.viewUp ?? 'Superior',
+      },
+    };
+  }
+
+  if (spec.type === 'Oblique') {
+    return {
+      name: spec.name ?? 'Oblique',
+      type: 'Oblique',
+      dataID: null,
+      options: {},
+    };
+  }
+
+  throw new Error(`Unknown view spec type`);
+};
+
+const parseGridLayout = (grid: z.infer<typeof viewString>[][]): { layout: Layout; views: ViewInfoInit[] } => {
+  const views: ViewInfoInit[] = [];
+  let slotIndex = 0;
+
+  const items: LayoutItem[] = grid.map((row) => {
+    const rowItems: LayoutItem[] = row.map(() => {
+      const currentSlot = slotIndex;
+      slotIndex += 1;
+      return { type: 'slot' as const, slotIndex: currentSlot };
+    });
+
+    return {
+      type: 'layout' as const,
+      direction: 'V' as const,
+      items: rowItems,
+    };
+  });
+
+  grid.flat().forEach((viewStr) => {
+    views.push(stringToViewInfoInit(viewStr));
+  });
+
+  return {
+    layout: {
+      direction: 'H',
+      items,
+    },
+    views,
+  };
+};
+
+const parseNestedLayout = (
+  layoutItem: LayoutConfigItem
+): { layout: Layout; views: ViewInfoInit[] } => {
+  const views: ViewInfoInit[] = [];
+  let slotIndex = 0;
+
+  const processItem = (item: LayoutConfigItem): LayoutItem => {
+    if (typeof item === 'string' || 'type' in item) {
+      const viewInfo = viewSpecToViewInfoInit(item as z.infer<typeof viewSpec>);
+      views.push(viewInfo);
+      const currentSlot = slotIndex;
+      slotIndex += 1;
+      return { type: 'slot', slotIndex: currentSlot };
+    }
+
+    return {
+      type: 'layout',
+      direction: item.direction,
+      items: item.items.map(processItem),
+    };
+  };
+
+  if (typeof layoutItem === 'string' || 'type' in layoutItem) {
+    const viewInfo = viewSpecToViewInfoInit(layoutItem as z.infer<typeof viewSpec>);
+    views.push(viewInfo);
+    return {
+      layout: {
+        direction: 'H',
+        items: [{ type: 'slot', slotIndex: 0 }],
+      },
+      views,
+    };
+  }
+
+  return {
+    layout: {
+      direction: layoutItem.direction,
+      items: layoutItem.items.map(processItem),
+    },
+    views,
+  };
+};
+
 const applyLabels = (manifest: Config) => {
   if (!manifest.labels) return;
 
@@ -115,8 +302,16 @@ const applyLabels = (manifest: Config) => {
 };
 
 const applyLayout = (manifest: Config) => {
-  if (manifest.layout?.gridSize) {
+  if (!manifest.layout) return;
+
+  if (Array.isArray(manifest.layout)) {
+    const parsedLayout = parseGridLayout(manifest.layout);
+    useViewStore().setLayoutWithViews(parsedLayout.layout, parsedLayout.views);
+  } else if ('gridSize' in manifest.layout) {
     useViewStore().setLayoutFromGrid(manifest.layout.gridSize);
+  } else {
+    const parsedLayout = parseNestedLayout(manifest.layout);
+    useViewStore().setLayoutWithViews(parsedLayout.layout, parsedLayout.views);
   }
 };
 

src/store/views.ts

@@ -168,6 +168,24 @@ export const useViewStore = defineStore('view', () => {
     setLayout(generateLayoutFromGrid(gridSize));
   }
 
+  function setLayoutWithViews(newLayout: Layout, views: ViewInfoInit[]) {
+    isActiveViewMaximized.value = false;
+
+    const newLayoutViewCount = calcLayoutViewCount(newLayout);
+    if (newLayoutViewCount !== views.length) {
+      throw new Error('Layout view count does not match views array length');
+    }
+
+    layoutSlots.value = views.map((viewInit) => addView(viewInit));
+    layout.value = newLayout;
+
+    if (!visibleViews.value.length) {
+      setActiveView(null);
+    } else {
+      setActiveView(visibleViews.value[0].id);
+    }
+  }
+
   function setDataForView(viewID: string, dataID: Maybe<string>) {
     if (!(viewID in viewByID)) return;
     viewByID[viewID].dataID = dataID;
@@ -248,6 +266,7 @@ export const useViewStore = defineStore('view', () => {
     replaceView,
     setLayout,
     setLayoutFromGrid,
+    setLayoutWithViews,
     setActiveView,
     setDataForView,
     setDataForActiveView,