From 279b0ee1674205cb5de2cff18ea40d1db880707f Mon Sep 17 00:00:00 2001
From: Christopher Schwarz <christopher@neugebauerschwarz.com>
Date: Mon, 1 Jun 2026 09:55:44 +0200
Subject: [PATCH 1/4] feat: add Many-to-Any (M2A) field support (#60)

Render and query M2A relations in the table. M2A fields previously showed
the raw display template (or an empty cell) and a column-display override
on them blanked the whole table with a 403.

- expandTokensThroughRelation now handles M2A: emits the collection
  discriminator plus per-collection `item:<collection>.<field>` paths,
  dropping bare/disallowed tokens so the items request can't 403.
- New resolveM2ARelation helper centralises the junction-shape lookup
  (discriminator, item field, allowed collections) with a permission
  fallback: when the polymorphic relation is filtered out, it reconstructs
  the shape from junction_field + the field's allowedCollections so a
  restricted user still sees what they can read.
- New renderM2ATemplate util resolves `{{collection}}` and
  `{{item:col.field}}` tokens against each junction row, sharing
  parseM2AToken with the query side so the two can't drift.
- Rows whose target collection is not readable show a block icon (only
  on genuine permission denial, not on a dangling FK).
- Add an in-body error state so a failed items request no longer leaves a
  blank body under a live pagination bar.
- isM2A helper plus M2A_TOKEN_RE/parseM2AToken/buildM2AFieldPath in
  displayHeuristics.
---
 src/components/EditableCellRelational.vue     |  98 ++++++++++++-
 src/super-table.vue                           |  33 +++--
 src/utils/adjustFieldsForDisplays.ts          |  71 ++++++++-
 src/utils/displayHeuristics.ts                |  39 +++++
 src/utils/renderM2ATemplate.ts                |  58 ++++++++
 src/utils/resolveM2ARelation.ts               | 118 +++++++++++++++
 tests/setup.ts                                |   5 +
 .../utils/adjustFieldsForDisplays.test.ts     |  85 +++++++++++
 tests/unit/utils/displayHeuristics.test.ts    | 112 +++++++++++++++
 .../utils/expandTokensThroughRelation.test.ts | 135 ++++++++++++++++++
 tests/unit/utils/fieldSupport.test.ts         |  12 ++
 tests/unit/utils/renderM2ATemplate.test.ts    |  63 ++++++++
 tests/unit/utils/resolveM2ARelation.test.ts   | 119 +++++++++++++++
 13 files changed, 928 insertions(+), 20 deletions(-)
 create mode 100644 src/utils/renderM2ATemplate.ts
 create mode 100644 src/utils/resolveM2ARelation.ts
 create mode 100644 tests/unit/utils/renderM2ATemplate.test.ts
 create mode 100644 tests/unit/utils/resolveM2ARelation.test.ts

diff --git a/src/components/EditableCellRelational.vue b/src/components/EditableCellRelational.vue
index 21fb5de..eaf87c3 100644
--- a/src/components/EditableCellRelational.vue
+++ b/src/components/EditableCellRelational.vue
@@ -137,6 +137,29 @@
     </template>
   </InlineEditPopover>
 
+  <!-- M2A: render each junction row, with a block icon for rows whose target
+       collection the current user cannot read -->
+  <div
+    v-else-if="isM2AField"
+    class="editable-cell relational"
+    :style="{ textAlign: props.align || 'left' }"
+  >
+    <span v-if="m2aSegments.length === 0" class="template-display">—</span>
+    <span v-else class="template-display">
+      <template v-for="(seg, i) in m2aSegments" :key="i">
+        <span v-if="i > 0">, </span>
+        <v-icon
+          v-if="isBlockedSegment(seg)"
+          v-tooltip="`No permission to read ${seg.collection}`"
+          name="block"
+          x-small
+          class="m2a-blocked-icon"
+        />
+        <span v-else>{{ seg.text }}</span>
+      </template>
+    </span>
+  </div>
+
   <!-- ABSOLUTE PRIORITY: Display templates for relational fields -->
   <div
     v-else-if="resolvedDisplay.display !== null"
@@ -167,7 +190,9 @@ import RelationalCell from './CellRenderers/RelationalCell.vue';
 import ColorCell from './CellRenderers/ColorCell.vue';
 import TagCell from './TagCell.vue';
 import { isFieldEditable, getFieldEditWarning, getFieldSupportLevel } from '../utils/fieldSupport';
-import { pickHeuristic } from '../utils/displayHeuristics';
+import { pickHeuristic, isM2A } from '../utils/displayHeuristics';
+import { resolveM2ARelation } from '../utils/resolveM2ARelation';
+import { renderM2ATemplate } from '../utils/renderM2ATemplate';
 import { resolveTranslationValue } from '../utils/resolveTranslationValue';
 import { usePermissions } from '../composables/usePermissions';
 
@@ -251,6 +276,11 @@ const actualFieldKey = computed(() => {
   return props.fieldKey;
 });
 
+// columnDisplays is keyed by the root field (no language suffix).
+const storageKey = computed(() =>
+  props.fieldKey.includes(':') ? props.fieldKey.split(':')[0] : props.fieldKey
+);
+
 const displayValue = computed(() => {
   // For edited values
   if (props.edits !== undefined) {
@@ -271,8 +301,7 @@ const displayValue = computed(() => {
 
   // Display-template resolution priority: column-display override →
   // field's own display template → relational heuristic → none.
-  const storageKey = props.fieldKey.includes(':') ? props.fieldKey.split(':')[0] : props.fieldKey;
-  const override = props.columnDisplays?.[storageKey];
+  const override = props.columnDisplays?.[storageKey.value];
   const fieldTemplate =
     props.field?.displayOptions?.template || props.field?.meta?.display_options?.template;
 
@@ -299,6 +328,13 @@ const displayValue = computed(() => {
     void isOverridePath;
     void isHeuristicPath;
     let valueForTemplate = relationalValue;
+
+    // M2A is rendered structurally (see m2aSegments) so blocked rows can show
+    // an icon; the string path below only covers non-M2A relations.
+    if (isM2AField.value) {
+      return '';
+    }
+
     // M2M: unwrap junction items through junction_field so the template
     // resolves against the target row, not the pivot row.
     const needsM2MUnwrap =
@@ -363,6 +399,53 @@ const displayValue = computed(() => {
   return props.item[props.fieldKey];
 });
 
+const isM2AField = computed(() => isM2A(props.field));
+
+// M2A cells render structurally so each junction row can show either its
+// resolved template value or a `block` icon when its target collection is not
+// readable by the current user.
+type M2ASegment = { text: string } | { blocked: true; collection: string };
+
+const m2aSegments = computed<M2ASegment[]>(() => {
+  if (!isM2AField.value) return [];
+  const relationalValue = props.item[props.fieldKey];
+  if (!Array.isArray(relationalValue) || relationalValue.length === 0) return [];
+
+  const collection = props.field?.collection;
+  const fieldName = props.field?.field;
+  const m2a =
+    collection && fieldName
+      ? resolveM2ARelation(collection, fieldName, relationsStore, fieldsStore)
+      : null;
+  if (!m2a) return [];
+
+  const template =
+    props.columnDisplays?.[storageKey.value]?.template ||
+    props.field?.displayOptions?.template ||
+    props.field?.meta?.display_options?.template ||
+    `{{${m2a.discriminator}}}`;
+
+  const segments: M2ASegment[] = [];
+  for (const row of relationalValue) {
+    if (!row || typeof row !== 'object') continue;
+    const rowCollection = row[m2a.discriminator];
+    // Missing item: only a permission denial (not a dangling FK) earns the icon.
+    if (rowCollection && row[m2a.itemField] == null) {
+      if (!permissions.canRead(String(rowCollection))) {
+        segments.push({ blocked: true, collection: String(rowCollection) });
+      }
+      continue;
+    }
+    const text = renderM2ATemplate(row, template, m2a.itemField, m2a.discriminator).trim();
+    if (text && text !== '—') segments.push({ text });
+  }
+  return segments;
+});
+
+function isBlockedSegment(seg: M2ASegment): seg is { blocked: true; collection: string } {
+  return 'blocked' in seg;
+}
+
 type ResolvedDisplay = {
   display: string | null;
   options: Record<string, unknown>;
@@ -370,12 +453,9 @@ type ResolvedDisplay = {
 };
 
 const resolvedDisplay = computed<ResolvedDisplay>(() => {
-  // Storage key for translations is the root (no language suffix)
-  const storageKey = props.fieldKey.includes(':') ? props.fieldKey.split(':')[0] : props.fieldKey;
-
   // 1. Layout-level override (renders via related-values unless the user
   //    explicitly stored a different display id alongside the template)
-  const override = props.columnDisplays?.[storageKey];
+  const override = props.columnDisplays?.[storageKey.value];
   if (override?.template) {
     return {
       display: override.display ?? 'related-values',
@@ -700,6 +780,10 @@ function navigateToPrevCell() {
 </script>
 
 <style scoped>
+.m2a-blocked-icon {
+  --v-icon-color: var(--foreground-subdued);
+  vertical-align: middle;
+}
 .editable-cell.relational,
 .editable-cell.non-editable {
   position: relative;
diff --git a/src/super-table.vue b/src/super-table.vue
index 28eea03..5d64c7e 100644
--- a/src/super-table.vue
+++ b/src/super-table.vue
@@ -45,7 +45,7 @@
     </div>
     <!-- Main Table -->
     <v-table
-      v-if="loading || ((itemCount > 0 || items.length > 0) && !error)"
+      v-if="loading || hasRenderableData"
       ref="tableRef"
       v-model="selectionWritable"
       v-model:headers="tableHeadersWritable"
@@ -218,6 +218,14 @@
       </template>
     </v-table>
 
+    <!-- Error State when the items request failed -->
+    <div v-else-if="!loading && error" class="no-data">
+      <div class="padding-box">
+        <v-icon name="error_outline" large />
+        <p>{{ t('unexpected_error') }}</p>
+      </div>
+    </div>
+
     <!-- Empty State when no items and not loading -->
     <div v-else-if="!loading && !error" class="no-data">
       <div class="padding-box">
@@ -231,7 +239,7 @@
     </div>
 
     <!-- Pagination Footer -->
-    <div class="footer" v-if="itemCount > 0 || items.length > 0">
+    <div class="footer" v-if="hasRenderableData">
       <div class="pagination">
         <v-pagination
           v-if="totalPages > 1"
@@ -796,16 +804,17 @@ const deep = computed(() => {
       // Check if this field is relational by looking at field metadata
       const fieldMeta = fieldsStore.getField(collection.value, actualField);
 
+      const special = fieldMeta?.meta?.special ?? [];
       if (
-        fieldMeta?.meta?.special?.includes('m2o') ||
-        fieldMeta?.meta?.special?.includes('o2m') ||
-        fieldMeta?.meta?.special?.includes('m2m') ||
-        fieldMeta?.meta?.special?.includes('m2a')
+        special.includes('m2o') ||
+        special.includes('o2m') ||
+        special.includes('m2m') ||
+        special.includes('m2a')
       ) {
         if (!deepFields[actualField]) {
-          deepFields[actualField] = {
-            _fields: ['*'],
-          };
+          deepFields[actualField] = special.includes('m2a')
+            ? { _fields: ['*'], _limit: -1 } // fetch every polymorphic row, not just the first page
+            : { _fields: ['*'] };
         }
       }
     }
@@ -958,6 +967,12 @@ const totalPages = computed(() => {
   return Math.ceil(itemCount.value / limit.value);
 });
 
+// A failed items fetch leaves the count populated (separate request), so gate
+// table + footer on this to avoid a blank body under a live pagination bar.
+const hasRenderableData = computed(
+  () => (itemCount.value > 0 || items.value.length > 0) && !error.value
+);
+
 // Items + count are fetched as two separate requests so users without read
 // permission on the PK still see a populated table — `meta=filter_count`
 // resolves via `countDistinct(pk)` server-side and would 403, while
diff --git a/src/utils/adjustFieldsForDisplays.ts b/src/utils/adjustFieldsForDisplays.ts
index 11d5f77..54353fd 100644
--- a/src/utils/adjustFieldsForDisplays.ts
+++ b/src/utils/adjustFieldsForDisplays.ts
@@ -1,7 +1,15 @@
 // CORE CHANGES - Following original Directus approach
 import { useStores, useCollection } from '@directus/extensions-sdk';
 import type { ColumnDisplay } from '../composables/useColumnDisplays';
-import { parseTemplateTokens, isRelational, pickHeuristic } from './displayHeuristics';
+import {
+  parseTemplateTokens,
+  isRelational,
+  isM2A,
+  pickHeuristic,
+  parseM2AToken,
+  buildM2AFieldPath,
+} from './displayHeuristics';
+import { resolveM2ARelation } from './resolveM2ARelation';
 
 /**
  * Helper function to get the related collection for a field
@@ -98,6 +106,12 @@ function getDisplayFieldsForRelation(
     return null; // Let deep parameter with _fields: ['*'] handle it
   }
 
+  // M2A target is polymorphic; the bare deep parameter supplies the data and
+  // requesting a fixed PK against the junction would 403.
+  if (isM2A(field)) {
+    return null;
+  }
+
   const fieldName = (field.field || field.key)?.split('.')[0];
   const relatedCollection = getRelatedCollection(parentCollection, fieldName, relationsStore);
 
@@ -136,12 +150,40 @@ export function expandTokensThroughRelation(
 ): string[] {
   if (!tokens.length) return [];
   const isM2M = field?.meta?.special?.includes('m2m') === true;
+  const isM2A = field?.meta?.special?.includes('m2a') === true;
   const isTranslations = field?.meta?.special?.includes('translations') === true;
 
   if (isTranslations) {
     return tokens.map((tok) => `${fieldKey}.${tok}`);
   }
 
+  if (isM2A) {
+    const m2a = resolveM2ARelation(parentCollection, fieldKey, relationsStore, fieldsStore);
+    if (!m2a) return [];
+    const { itemField, discriminator, allowedCollections } = m2a;
+
+    // The discriminator is always needed so the renderer knows which target
+    // collection each row points at before resolving per-collection tokens.
+    const expanded: string[] = [`${fieldKey}.${discriminator}`];
+    for (const tok of tokens) {
+      if (tok === discriminator) continue;
+      // Per-collection M2A token: "item:collection.path". Bare tokens are dropped
+      // on purpose — they would resolve against the wrong collection and 403.
+      const parsed = parseM2AToken(tok);
+      if (!parsed) continue;
+      const { prefix, collection: col, path } = parsed;
+      if (prefix !== itemField && prefix !== 'item') continue;
+      if (allowedCollections.length > 0 && !allowedCollections.includes(col)) continue;
+      // Only the first path segment is validated against the target — deep
+      // leaves are unvalidated, matching the M2M/M2O branches below.
+      const firstSegment = (path.split('.')[0] ?? '') as string;
+      if (!fieldsStore.getField(col, firstSegment)) continue;
+      const expandedPath = buildM2AFieldPath(fieldKey, itemField, col, path);
+      if (!expanded.includes(expandedPath)) expanded.push(expandedPath);
+    }
+    return expanded;
+  }
+
   if (isM2M) {
     const relations = relationsStore.getRelationsForField(parentCollection, fieldKey);
     const rel = relations?.[0];
@@ -175,7 +217,8 @@ export function expandTokensThroughRelation(
     (rel?.related_collection as string | undefined) ?? (rel?.collection as string | undefined);
   if (!target) {
     // Best-effort: return as-is when we have no target info to validate against.
-    return tokens.map((tok) => `${fieldKey}.${tok}`);
+    // M2A is handled above; never reach the wrong-collection emit for it.
+    return isM2A ? [] : tokens.map((tok) => `${fieldKey}.${tok}`);
   }
 
   const expanded: string[] = [];
@@ -303,8 +346,14 @@ export function adjustFieldsForDisplays(
         switch (displayId) {
           case 'related-values': {
             const template = field.meta?.display_options?.template;
+            const isM2A = field.meta?.special?.includes('m2a') === true;
             if (template) {
-              const templateTokens = extractFieldsFromTemplate(template);
+              // M2A tokens use the "item:collection.field" form whose colon/dot
+              // structure must stay intact, so use the prefix-preserving parser;
+              // other relation types keep the last-segment flattener.
+              const templateTokens = isM2A
+                ? parseTemplateTokens(template)
+                : extractFieldsFromTemplate(template);
               const expanded = expandTokensThroughRelation(
                 field,
                 fieldKey,
@@ -315,9 +364,13 @@ export function adjustFieldsForDisplays(
               );
 
               // PK path so the row can be keyed; M2M needs the junction prefix.
+              // M2A already carries its discriminator from the expander, and its
+              // per-collection PKs differ per target, so it needs no extra PK here.
               const isM2M = field.meta?.special?.includes('m2m') === true;
               let pkPath: string | null = null;
-              if (isM2M) {
+              if (isM2A) {
+                pkPath = null;
+              } else if (isM2M) {
                 const relations = relationsStore.getRelationsForField(parentCollection, fieldKey);
                 const rel = relations?.[0];
                 const junctionField = rel?.meta?.junction_field as string | undefined;
@@ -348,6 +401,16 @@ export function adjustFieldsForDisplays(
               displayFields =
                 pkPath && !expanded.includes(pkPath) ? [...expanded, pkPath] : expanded;
               if (displayFields.length === 0) displayFields = [fieldKey];
+            } else if (isM2A) {
+              // No template: the junction discriminator alone is servable; the
+              // bare alias would request invalid columns on the junction.
+              const discriminator = resolveM2ARelation(
+                parentCollection,
+                fieldKey,
+                relationsStore,
+                fieldsStore
+              )?.discriminator;
+              displayFields = discriminator ? [`${fieldKey}.${discriminator}`] : [fieldKey];
             } else {
               const rootField = (fieldKey.split('.')[0] ?? fieldKey) as string;
               const relatedCollection = getRelatedCollection(
diff --git a/src/utils/displayHeuristics.ts b/src/utils/displayHeuristics.ts
index 5ea4fc8..53b90ba 100644
--- a/src/utils/displayHeuristics.ts
+++ b/src/utils/displayHeuristics.ts
@@ -11,6 +11,12 @@ export function isRelational(field: { meta?: { special?: string[] } } | null | u
   return field.meta.special.some((s) => (RELATIONAL_SPECIALS as readonly string[]).includes(s));
 }
 
+export function isM2A(
+  field: { meta?: { special?: string[] | null } | null } | null | undefined
+): boolean {
+  return field?.meta?.special?.includes('m2a') === true;
+}
+
 /**
  * Pull the field tokens out of a display template. Whitespace is stripped,
  * duplicates are removed, dotted paths are kept intact (callers decide whether
@@ -26,6 +32,39 @@ export function parseTemplateTokens(template: string): string[] {
   return [...new Set(fields)];
 }
 
+/**
+ * Grammar for a per-collection M2A template token: `item:collection.path`
+ * (e.g. `item:articles.title`). Captures [, prefix, collection, path].
+ */
+export const M2A_TOKEN_RE = /^([^:.]+):([^.]+)\.(.+)$/;
+
+/**
+ * Parse a per-collection M2A token. Returns `null` for tokens that aren't in
+ * the `prefix:collection.path` form (e.g. plain `{{collection}}` or bare keys).
+ */
+export function parseM2AToken(
+  token: string
+): { prefix: string; collection: string; path: string } | null {
+  const match = token.match(M2A_TOKEN_RE);
+  if (!match) return null;
+  const [, prefix, collection, path] = match;
+  return { prefix: prefix!, collection: collection!, path: path! };
+}
+
+/**
+ * Build the API field path for an M2A per-collection token, e.g.
+ * `treatment.item:partners_catalog.name`. Single source of the emit shape so
+ * the query side and the render side cannot drift.
+ */
+export function buildM2AFieldPath(
+  fieldKey: string,
+  itemField: string,
+  collection: string,
+  path: string
+): string {
+  return `${fieldKey}.${itemField}:${collection}.${path}`;
+}
+
 interface RelationsStoreLike {
   getRelationsForField: (
     collection: string,
diff --git a/src/utils/renderM2ATemplate.ts b/src/utils/renderM2ATemplate.ts
new file mode 100644
index 0000000..a828180
--- /dev/null
+++ b/src/utils/renderM2ATemplate.ts
@@ -0,0 +1,58 @@
+import { get } from '@directus/utils';
+import { parseM2AToken } from './displayHeuristics';
+
+/** Conventional M2A token aliases accepted alongside the resolved field names. */
+export const M2A_COLLECTION_TOKEN = 'collection';
+export const M2A_ITEM_TOKEN = 'item';
+
+/**
+ * Render one M2A junction row against a related-values template.
+ *
+ * `{{collection}}` resolves from the discriminator; `{{item:col.path}}` resolves
+ * only when the row points at `col`. Shares `parseM2AToken` with the query-side
+ * expander so the two cannot drift.
+ */
+export function renderM2ATemplate(
+  row: Record<string, any> | null | undefined,
+  template: string,
+  itemField: string,
+  discriminator: string
+): string {
+  if (!row || typeof row !== 'object') return '—';
+  const rowCollection = row[discriminator];
+  const item = row[itemField];
+
+  return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, rawToken: string) => {
+    const token = String(rawToken).trim();
+    if (token === discriminator || token === M2A_COLLECTION_TOKEN) {
+      return rowCollection != null ? String(rowCollection) : '';
+    }
+
+    const parsed = parseM2AToken(token);
+    if (parsed) {
+      if (parsed.prefix !== itemField && parsed.prefix !== M2A_ITEM_TOKEN) return '';
+      // Only the branch matching this row's collection contributes a value.
+      if (parsed.collection !== rowCollection) return '';
+      return scalarOrEmpty(getNestedValue(item, parsed.path));
+    }
+
+    return scalarOrEmpty(getNestedValue(item, token));
+  });
+}
+
+/**
+ * Resolve a dotted path, skipping Directus `$`-prefixed virtual segments
+ * (e.g. `$thumbnail`) before delegating to the shared `get` helper.
+ */
+function getNestedValue(source: any, path: string): any {
+  const cleaned = path
+    .split('.')
+    .filter((segment) => !segment.startsWith('$'))
+    .join('.');
+  return get(source, cleaned);
+}
+
+/** Tokens render scalars only; objects/arrays collapse to '' to avoid "[object Object]". */
+function scalarOrEmpty(value: any): string {
+  return value != null && typeof value !== 'object' ? String(value) : '';
+}
diff --git a/src/utils/resolveM2ARelation.ts b/src/utils/resolveM2ARelation.ts
new file mode 100644
index 0000000..0c0a000
--- /dev/null
+++ b/src/utils/resolveM2ARelation.ts
@@ -0,0 +1,118 @@
+/**
+ * Minimal subset of the Directus relations store needed by this helper.
+ * Mirrors the pattern used in `src/utils/resolveTranslationsCollection.ts` so
+ * consumers can be unit-tested without pulling in the full Pinia store.
+ */
+interface RelationsStoreLike {
+  getRelationsForField: (
+    collection: string,
+    field: string
+  ) =>
+    | Array<{
+        field?: string;
+        meta?: {
+          one_field?: string | null;
+          one_collection_field?: string | null;
+          one_allowed_collections?: string[] | null;
+          junction_field?: string | null;
+        } | null;
+      }>
+    | null
+    | undefined;
+}
+
+interface FieldsStoreLike {
+  getField: (
+    collection: string,
+    field: string
+  ) =>
+    | { meta?: { options?: { allowedCollections?: string[] | null } | null } | null }
+    | null
+    | undefined;
+}
+
+export interface M2ARelation {
+  /** Junction FK column holding the polymorphic target (e.g. `item`). */
+  itemField: string;
+  /** Column naming each row's target collection (e.g. `collection`). */
+  discriminator: string;
+  /** Collections the relation may point at; empty when unconstrained. */
+  allowedCollections: string[];
+}
+
+/** Default discriminator column name used by Directus M2A junctions. */
+const DEFAULT_DISCRIMINATOR = 'collection';
+
+/**
+ * Resolve the M2A junction shape for a parent collection's M2A alias field.
+ *
+ * An M2A relation is stored on the junction with a `collection` discriminator
+ * column and a type-erased `item` FK. The relation carrying
+ * `meta.one_collection_field` is the polymorphic side; the sibling relation
+ * (pointing back at the parent) carries `meta.junction_field` naming that same
+ * FK column.
+ *
+ * When the user lacks read permission on a target collection, Directus drops
+ * the polymorphic relation from the store, leaving only the parent relation.
+ * In that case we reconstruct the shape from the parent relation's
+ * `junction_field` plus the field's own `options.allowedCollections`, so a
+ * restricted user still sees the collections they *can* read instead of an
+ * empty column. `fieldsStore` is optional to preserve the original signature.
+ *
+ * @returns the junction shape, or `null` if it cannot be resolved
+ */
+export function resolveM2ARelation(
+  parentCollection: string,
+  fieldKey: string,
+  relationsStore: RelationsStoreLike,
+  fieldsStore?: FieldsStoreLike
+): M2ARelation | null {
+  let relations: ReturnType<RelationsStoreLike['getRelationsForField']>;
+  try {
+    relations = relationsStore.getRelationsForField(parentCollection, fieldKey);
+  } catch {
+    // The store can throw during unloaded states (e.g. early app boot).
+    return null;
+  }
+
+  if (!relations || relations.length === 0) return null;
+
+  // Preferred: the polymorphic relation carries the discriminator directly.
+  const itemRel = relations.find((r) => r?.meta?.one_collection_field);
+  if (itemRel?.field && itemRel.meta?.one_collection_field) {
+    return {
+      itemField: itemRel.field,
+      discriminator: itemRel.meta.one_collection_field,
+      allowedCollections: itemRel.meta.one_allowed_collections ?? [],
+    };
+  }
+
+  // Fallback: the polymorphic relation was permission-filtered out. The parent
+  // relation still names the junction FK column via `junction_field`; the
+  // allowed collections come from the field's interface options.
+  const parentRel = relations.find((r) => r?.meta?.junction_field);
+  const itemField = parentRel?.meta?.junction_field;
+  if (!itemField) return null;
+
+  const allowedCollections = readAllowedCollections(parentCollection, fieldKey, fieldsStore);
+  return {
+    itemField,
+    discriminator: DEFAULT_DISCRIMINATOR,
+    allowedCollections,
+  };
+}
+
+function readAllowedCollections(
+  parentCollection: string,
+  fieldKey: string,
+  fieldsStore?: FieldsStoreLike
+): string[] {
+  if (!fieldsStore) return [];
+  try {
+    const rootField = fieldKey.includes('.') ? (fieldKey.split('.')[0] as string) : fieldKey;
+    const field = fieldsStore.getField(parentCollection, rootField);
+    return field?.meta?.options?.allowedCollections ?? [];
+  } catch {
+    return [];
+  }
+}
diff --git a/tests/setup.ts b/tests/setup.ts
index 83953ac..49fa4e6 100644
--- a/tests/setup.ts
+++ b/tests/setup.ts
@@ -7,6 +7,11 @@ import { config } from '@vue/test-utils';
 vi.mock('@directus/utils', () => ({
   formatTitle: (str: string) => str.replace(/_/g, ' ').replace(/\b\w/g, (l) => l.toUpperCase()),
   isDirectusError: vi.fn(() => false),
+  // Minimal dotted-path getter mirroring @directus/utils `get`.
+  get: (obj: any, path: string) => {
+    if (!path) return undefined;
+    return path.split('.').reduce((acc: any, key: string) => acc?.[key], obj);
+  },
 }));
 
 vi.mock('@directus/format-title', () => ({
diff --git a/tests/unit/utils/adjustFieldsForDisplays.test.ts b/tests/unit/utils/adjustFieldsForDisplays.test.ts
index e0ebebe..556f869 100644
--- a/tests/unit/utils/adjustFieldsForDisplays.test.ts
+++ b/tests/unit/utils/adjustFieldsForDisplays.test.ts
@@ -235,3 +235,88 @@ describe('adjustFieldsForDisplays — override branch M2M validation (issue #55)
     expect(result).toContain('tags.tag_id.label');
   });
 });
+
+describe('adjustFieldsForDisplays — M2A (issue #60)', () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  // Mirrors the live orders.treatment M2A: junction orders_treatment with a
+  // `collection` discriminator and a polymorphic `item` FK to two collections.
+  const mockM2A = (displayTemplate?: string) =>
+    vi.doMock('@directus/extensions-sdk', () => ({
+      useStores: () => ({
+        useFieldsStore: () => ({
+          getField: (col: string, f: string) => {
+            if (col === 'orders' && f === 'treatment')
+              return {
+                field: 'treatment',
+                collection: 'orders',
+                meta: {
+                  special: ['m2a'],
+                  ...(displayTemplate
+                    ? { display: 'related-values', display_options: { template: displayTemplate } }
+                    : {}),
+                },
+              };
+            if (col === 'partners_catalog' && (f === 'name' || f === 'catalog_id'))
+              return { field: f };
+            if (col === 'service' && f === 'name') return { field: 'name' };
+            return null;
+          },
+          getFieldsForCollection: () => [],
+        }),
+        useRelationsStore: () => ({
+          getRelationsForField: (col: string, f: string) =>
+            col === 'orders' && f === 'treatment'
+              ? [
+                  {
+                    collection: 'orders_treatment',
+                    field: 'orders_id',
+                    related_collection: 'orders',
+                    meta: { junction_field: 'item' },
+                  },
+                  {
+                    collection: 'orders_treatment',
+                    field: 'item',
+                    related_collection: null,
+                    meta: {
+                      one_collection_field: 'collection',
+                      one_allowed_collections: ['partners_catalog', 'service'],
+                      junction_field: 'orders_id',
+                    },
+                  },
+                ]
+              : [],
+        }),
+      }),
+      useCollection: () => ({ primaryKeyField: { value: { field: 'id' } } }),
+      useExtensions: () => ({ displays: { value: [] } }),
+    }));
+
+  it('expands a related-values M2A template into per-collection item paths', async () => {
+    mockM2A('{{collection}}: {{item:partners_catalog.catalog_id.title}} {{item:service.name}}');
+    const { adjustFieldsForDisplays } = await import('@/utils/adjustFieldsForDisplays');
+    const result = adjustFieldsForDisplays(['treatment'], 'orders');
+    expect(result).toEqual(
+      expect.arrayContaining([
+        'treatment.collection',
+        'treatment.item:partners_catalog.catalog_id.title',
+        'treatment.item:service.name',
+      ])
+    );
+  });
+
+  it('never emits an invalid bare M2A path from a column-display override', async () => {
+    mockM2A();
+    const { adjustFieldsForDisplays } = await import('@/utils/adjustFieldsForDisplays');
+    const result = adjustFieldsForDisplays(['code', 'treatment'], 'orders', {
+      treatment: { template: '{{code}}' },
+    });
+    // The bare token must be dropped — these paths would 403 against the junction.
+    expect(result).not.toContain('treatment.code');
+    expect(result).not.toContain('treatment.item');
+    expect(result).not.toContain('treatment.id');
+    expect(result).toContain('treatment.collection');
+  });
+});
diff --git a/tests/unit/utils/displayHeuristics.test.ts b/tests/unit/utils/displayHeuristics.test.ts
index 60a7685..cffa01d 100644
--- a/tests/unit/utils/displayHeuristics.test.ts
+++ b/tests/unit/utils/displayHeuristics.test.ts
@@ -1,9 +1,12 @@
 import { describe, it, expect } from 'vitest';
 import {
   isRelational,
+  isM2A,
   parseTemplateTokens,
   resolveTargetCollection,
   pickHeuristic,
+  parseM2AToken,
+  buildM2AFieldPath,
 } from '@/utils/displayHeuristics';
 
 describe('isRelational', () => {
@@ -24,6 +27,22 @@ describe('isRelational', () => {
   });
 });
 
+describe('isM2A', () => {
+  it('returns true only for m2a special', () => {
+    expect(isM2A({ meta: { special: ['m2a'] } } as any)).toBe(true);
+    expect(isM2A({ meta: { special: ['m2o'] } } as any)).toBe(false);
+    expect(isM2A({ meta: { special: ['m2m'] } } as any)).toBe(false);
+  });
+
+  it('returns false for missing/empty/null meta', () => {
+    expect(isM2A({ meta: { special: [] } } as any)).toBe(false);
+    expect(isM2A({ meta: { special: null } } as any)).toBe(false);
+    expect(isM2A({ meta: null } as any)).toBe(false);
+    expect(isM2A(null as any)).toBe(false);
+    expect(isM2A(undefined as any)).toBe(false);
+  });
+});
+
 describe('parseTemplateTokens', () => {
   it('extracts simple field tokens', () => {
     expect(parseTemplateTokens('{{name}}')).toEqual(['name']);
@@ -112,6 +131,30 @@ describe('resolveTargetCollection', () => {
     expect(resolveTargetCollection(field, relations as any, fields as any)).toBe(null);
   });
 
+  it('returns null for M2A (polymorphic target has no single related collection)', () => {
+    // The junction `item` FK is type-erased (foreign_key_table null), so there
+    // is no single target to resolve — heuristics must stay out of M2A.
+    const relations = makeRelationsStore({
+      'orders.treatment': [
+        {
+          collection: 'orders_treatment',
+          field: 'orders_id',
+          related_collection: 'orders',
+          meta: { junction_field: 'item' },
+        },
+      ],
+    });
+    const fields = makeFieldsStore({
+      'orders_treatment.item': { schema: { foreign_key_table: null } },
+    });
+    const field = {
+      collection: 'orders',
+      field: 'treatment',
+      meta: { special: ['m2a'] },
+    } as any;
+    expect(resolveTargetCollection(field, relations as any, fields as any)).toBe(null);
+  });
+
   it('does NOT junction-traverse for translation fields (special=translations)', () => {
     // Translation relations also carry meta.junction_field (languages_code), but the
     // intended target is the translations collection itself — not the languages table.
@@ -230,6 +273,29 @@ describe('pickHeuristic', () => {
     expect(pickHeuristic(field, relations as any, fields as any)).toBe(null);
   });
 
+  it('returns null for M2A fields (polymorphic, no single heuristic target)', () => {
+    const relations = {
+      getRelationsForField: () => [
+        {
+          collection: 'orders_treatment',
+          field: 'orders_id',
+          related_collection: 'orders',
+          meta: { junction_field: 'item' },
+        },
+      ],
+    };
+    const fields = {
+      getField: (_col: string, f: string) =>
+        f === 'item' ? { schema: { foreign_key_table: null } } : null,
+    };
+    const field = {
+      collection: 'orders',
+      field: 'treatment',
+      meta: { special: ['m2a'] },
+    } as any;
+    expect(pickHeuristic(field, relations as any, fields as any)).toBe(null);
+  });
+
   it('returns null for translation fields (existing render path handles them)', () => {
     const relations = {
       getRelationsForField: () => [
@@ -250,3 +316,49 @@ describe('pickHeuristic', () => {
     expect(pickHeuristic(field, relations as any, fields as any)).toBe(null);
   });
 });
+
+describe('parseM2AToken', () => {
+  it('parses a per-collection token into prefix/collection/path', () => {
+    expect(parseM2AToken('item:partners_catalog.name')).toEqual({
+      prefix: 'item',
+      collection: 'partners_catalog',
+      path: 'name',
+    });
+  });
+
+  it('keeps a nested path intact (M2A -> M2O -> scalar)', () => {
+    expect(parseM2AToken('item:partners_catalog.catalog_id.title')).toEqual({
+      prefix: 'item',
+      collection: 'partners_catalog',
+      path: 'catalog_id.title',
+    });
+  });
+
+  it('returns null for a token without a path (no dot after collection)', () => {
+    expect(parseM2AToken('item:partners_catalog')).toBeNull();
+  });
+
+  it('returns null for a plain token', () => {
+    expect(parseM2AToken('collection')).toBeNull();
+    expect(parseM2AToken('name')).toBeNull();
+  });
+});
+
+describe('buildM2AFieldPath', () => {
+  it('builds the API field path for an M2A per-collection token', () => {
+    expect(buildM2AFieldPath('treatment', 'item', 'partners_catalog', 'name')).toBe(
+      'treatment.item:partners_catalog.name'
+    );
+  });
+
+  it('round-trips with parseM2AToken on the item-relative portion', () => {
+    const built = buildM2AFieldPath('treatment', 'item', 'service', 'name');
+    // strip the "<fieldKey>." prefix to get back the item-relative token
+    const token = built.slice('treatment.'.length);
+    expect(parseM2AToken(token)).toEqual({
+      prefix: 'item',
+      collection: 'service',
+      path: 'name',
+    });
+  });
+});
diff --git a/tests/unit/utils/expandTokensThroughRelation.test.ts b/tests/unit/utils/expandTokensThroughRelation.test.ts
index 2cc7c9d..5b693df 100644
--- a/tests/unit/utils/expandTokensThroughRelation.test.ts
+++ b/tests/unit/utils/expandTokensThroughRelation.test.ts
@@ -261,4 +261,139 @@ describe('expandTokensThroughRelation', () => {
     );
     expect(result).toEqual([]);
   });
+
+  describe('M2A', () => {
+    // Mirrors the live `orders.treatment` shape: a junction with a `collection`
+    // discriminator and a polymorphic `item` FK to two allowed collections.
+    const m2aStores = () =>
+      makeStores(
+        {
+          'partners_catalog.name': { field: 'name' },
+          'partners_catalog.catalog_id': { field: 'catalog_id' },
+          'service.name': { field: 'name' },
+        },
+        {
+          'orders.treatment': [
+            {
+              collection: 'orders_treatment',
+              field: 'orders_id',
+              related_collection: 'orders',
+              meta: { junction_field: 'item' },
+            },
+            {
+              collection: 'orders_treatment',
+              field: 'item',
+              related_collection: null,
+              meta: {
+                one_collection_field: 'collection',
+                one_allowed_collections: ['partners_catalog', 'service'],
+                junction_field: 'orders_id',
+              },
+            },
+          ],
+        }
+      );
+    const m2aField = {
+      collection: 'orders',
+      field: 'treatment',
+      meta: { special: ['m2a'] },
+    } as any;
+
+    it('expands per-collection item tokens and always emits the discriminator', () => {
+      const { fieldsStore, relationsStore } = m2aStores();
+      const result = expandTokensThroughRelation(
+        m2aField,
+        'treatment',
+        'orders',
+        ['item:partners_catalog.name', 'item:service.name'],
+        fieldsStore as any,
+        relationsStore as any
+      );
+      expect(result).toEqual([
+        'treatment.collection',
+        'treatment.item:partners_catalog.name',
+        'treatment.item:service.name',
+      ]);
+    });
+
+    it('keeps nested item paths intact (M2A -> M2O -> scalar)', () => {
+      const { fieldsStore, relationsStore } = m2aStores();
+      const result = expandTokensThroughRelation(
+        m2aField,
+        'treatment',
+        'orders',
+        ['item:partners_catalog.catalog_id.title'],
+        fieldsStore as any,
+        relationsStore as any
+      );
+      expect(result).toEqual([
+        'treatment.collection',
+        'treatment.item:partners_catalog.catalog_id.title',
+      ]);
+    });
+
+    it('drops bare tokens so they never 403 against the junction', () => {
+      const { fieldsStore, relationsStore } = m2aStores();
+      const result = expandTokensThroughRelation(
+        m2aField,
+        'treatment',
+        'orders',
+        ['code', 'time'],
+        fieldsStore as any,
+        relationsStore as any
+      );
+      expect(result).toEqual(['treatment.collection']);
+    });
+
+    it('drops tokens for collections outside one_allowed_collections', () => {
+      const { fieldsStore, relationsStore } = m2aStores();
+      const result = expandTokensThroughRelation(
+        m2aField,
+        'treatment',
+        'orders',
+        ['item:other_collection.name'],
+        fieldsStore as any,
+        relationsStore as any
+      );
+      expect(result).toEqual(['treatment.collection']);
+    });
+
+    it('drops tokens whose field is missing on the target collection', () => {
+      const { fieldsStore, relationsStore } = m2aStores();
+      const result = expandTokensThroughRelation(
+        m2aField,
+        'treatment',
+        'orders',
+        ['item:service.nonexistent'],
+        fieldsStore as any,
+        relationsStore as any
+      );
+      expect(result).toEqual(['treatment.collection']);
+    });
+
+    it('returns [] when the M2A item relation is missing (defensive)', () => {
+      const { fieldsStore, relationsStore } = makeStores(
+        {},
+        {
+          'orders.treatment': [
+            {
+              collection: 'orders_treatment',
+              field: 'orders_id',
+              related_collection: 'orders',
+              // NOTE: no one_collection_field relation present
+            },
+          ],
+        }
+      );
+      const result = expandTokensThroughRelation(
+        m2aField,
+        'treatment',
+        'orders',
+        ['item:partners_catalog.name'],
+        fieldsStore as any,
+        relationsStore as any
+      );
+      expect(result).toEqual([]);
+    });
+  });
 });
diff --git a/tests/unit/utils/fieldSupport.test.ts b/tests/unit/utils/fieldSupport.test.ts
index 753bced..ec14987 100644
--- a/tests/unit/utils/fieldSupport.test.ts
+++ b/tests/unit/utils/fieldSupport.test.ts
@@ -52,6 +52,18 @@ describe('fieldSupport', () => {
       expect(isFieldEditable(undefined as any)).toBe(false);
     });
 
+    it('should keep M2A (alias) fields read-only', () => {
+      // M2A is display-only; inline editing must stay disabled.
+      const m2aVariants = [
+        { type: 'alias', meta: { interface: 'list-m2a', special: ['m2a'] } },
+        { type: 'alias', meta: { interface: 'many-to-any', special: ['m2a'] } },
+      ];
+      m2aVariants.forEach((field) => {
+        expect(isFieldEditable(field as any)).toBe(false);
+        expect(getFieldSupportLevel(field as any)).toBe('none');
+      });
+    });
+
     it('should respect readonly fields', () => {
       expect(isFieldEditable({ 
         type: 'string',
diff --git a/tests/unit/utils/renderM2ATemplate.test.ts b/tests/unit/utils/renderM2ATemplate.test.ts
new file mode 100644
index 0000000..e11936a
--- /dev/null
+++ b/tests/unit/utils/renderM2ATemplate.test.ts
@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { renderM2ATemplate } from '@/utils/renderM2ATemplate';
+
+// Junction rows mirror the live orders.treatment shape: a `collection`
+// discriminator + a polymorphic `item` payload.
+const itemField = 'item';
+const discriminator = 'collection';
+
+describe('renderM2ATemplate', () => {
+  it('resolves {{collection}} from the discriminator', () => {
+    const row = { collection: 'service', item: { name: 'Installation' } };
+    expect(renderM2ATemplate(row, '{{collection}}', itemField, discriminator)).toBe('service');
+  });
+
+  it('resolves {{item:col.field}} only for the matching collection', () => {
+    const row = { collection: 'service', item: { name: 'Installation' } };
+    const tpl = '{{item:partners_catalog.name}} {{item:service.name}}';
+    // partners_catalog branch is skipped (row is a service), service branch wins
+    expect(renderM2ATemplate(row, tpl, itemField, discriminator).trim()).toBe('Installation');
+  });
+
+  it('walks a nested path (M2A -> M2O -> scalar)', () => {
+    const row = { collection: 'partners_catalog', item: { catalog_id: { title: 'Premium' } } };
+    expect(
+      renderM2ATemplate(row, '{{item:partners_catalog.catalog_id.title}}', itemField, discriminator)
+    ).toBe('Premium');
+  });
+
+  it('combines discriminator and item tokens', () => {
+    const row = { collection: 'service', item: { name: 'Repair' } };
+    expect(renderM2ATemplate(row, '{{collection}}: {{item:service.name}}', itemField, discriminator)).toBe(
+      'service: Repair'
+    );
+  });
+
+  it('returns "—" for a null/non-object row', () => {
+    expect(renderM2ATemplate(null, '{{collection}}', itemField, discriminator)).toBe('—');
+  });
+
+  it('renders empty for an item token whose collection does not match the row', () => {
+    const row = { collection: 'service', item: { name: 'X' } };
+    expect(renderM2ATemplate(row, '{{item:partners_catalog.name}}', itemField, discriminator).trim()).toBe(
+      ''
+    );
+  });
+
+  it('collapses object/array leaves to empty (no "[object Object]")', () => {
+    const row = { collection: 'service', item: { nested: { a: 1 }, list: [1, 2] } };
+    expect(renderM2ATemplate(row, '{{item:service.nested}}', itemField, discriminator).trim()).toBe('');
+    expect(renderM2ATemplate(row, '{{item:service.list}}', itemField, discriminator).trim()).toBe('');
+  });
+
+  it('renders empty when the item payload is null (blocked / dangling)', () => {
+    const row = { collection: 'service', item: null };
+    expect(renderM2ATemplate(row, '{{item:service.name}}', itemField, discriminator).trim()).toBe('');
+  });
+
+  it('honors a custom discriminator name via {{collection}} alias', () => {
+    const row = { kind: 'service', item: { name: 'Installation' } };
+    // discriminator is 'kind', but the literal {{collection}} alias still resolves it
+    expect(renderM2ATemplate(row, '{{collection}}', itemField, 'kind')).toBe('service');
+  });
+});
diff --git a/tests/unit/utils/resolveM2ARelation.test.ts b/tests/unit/utils/resolveM2ARelation.test.ts
new file mode 100644
index 0000000..b0215ea
--- /dev/null
+++ b/tests/unit/utils/resolveM2ARelation.test.ts
@@ -0,0 +1,119 @@
+import { describe, it, expect, vi } from 'vitest';
+import { resolveM2ARelation } from '@/utils/resolveM2ARelation';
+
+// Mirrors the live orders.treatment shape: the junction's polymorphic `item`
+// relation carries the collection discriminator and the allowed collections.
+const itemRelation = {
+  field: 'item',
+  meta: {
+    one_collection_field: 'collection',
+    one_allowed_collections: ['partners_catalog', 'service'],
+  },
+};
+const parentRelation = {
+  field: 'orders_id',
+  meta: { one_collection_field: null },
+};
+
+describe('resolveM2ARelation', () => {
+  it('resolves itemField, discriminator and allowedCollections from the item relation', () => {
+    const relationsStore = {
+      getRelationsForField: vi.fn().mockReturnValue([parentRelation, itemRelation]),
+    };
+    expect(resolveM2ARelation('orders', 'treatment', relationsStore)).toEqual({
+      itemField: 'item',
+      discriminator: 'collection',
+      allowedCollections: ['partners_catalog', 'service'],
+    });
+  });
+
+  it('picks the discriminator-carrying relation regardless of order', () => {
+    const relationsStore = {
+      getRelationsForField: vi.fn().mockReturnValue([itemRelation, parentRelation]),
+    };
+    expect(resolveM2ARelation('orders', 'treatment', relationsStore)?.itemField).toBe('item');
+  });
+
+  it('defaults allowedCollections to [] when not constrained', () => {
+    const relationsStore = {
+      getRelationsForField: vi.fn().mockReturnValue([
+        { field: 'item', meta: { one_collection_field: 'collection' } },
+      ]),
+    };
+    expect(resolveM2ARelation('orders', 'treatment', relationsStore)?.allowedCollections).toEqual(
+      []
+    );
+  });
+
+  it('returns null when no relation carries one_collection_field', () => {
+    const relationsStore = {
+      getRelationsForField: vi.fn().mockReturnValue([parentRelation]),
+    };
+    expect(resolveM2ARelation('orders', 'treatment', relationsStore)).toBeNull();
+  });
+
+  it('returns null when the item relation lacks a field name', () => {
+    const relationsStore = {
+      getRelationsForField: vi
+        .fn()
+        .mockReturnValue([{ meta: { one_collection_field: 'collection' } }]),
+    };
+    expect(resolveM2ARelation('orders', 'treatment', relationsStore)).toBeNull();
+  });
+
+  it('returns null when no relations exist for the field', () => {
+    const relationsStore = { getRelationsForField: vi.fn().mockReturnValue([]) };
+    expect(resolveM2ARelation('orders', 'treatment', relationsStore)).toBeNull();
+  });
+
+  it('returns null (no throw) when the store throws during early boot', () => {
+    const relationsStore = {
+      getRelationsForField: vi.fn().mockImplementation(() => {
+        throw new Error('store not ready');
+      }),
+    };
+    expect(resolveM2ARelation('orders', 'treatment', relationsStore)).toBeNull();
+  });
+});
+
+describe('resolveM2ARelation — permission fallback', () => {
+  // When the user cannot read a target collection, Directus filters the
+  // polymorphic relation out of the store, leaving only the parent relation
+  // (which still carries junction_field). The field options stay readable.
+  const parentOnly = {
+    getRelationsForField: vi.fn().mockReturnValue([
+      {
+        field: 'orders_id',
+        meta: { one_field: 'treatment', junction_field: 'item', one_collection_field: null },
+      },
+    ]),
+  };
+
+  it('reconstructs the shape from junction_field + field options when the item relation is hidden', () => {
+    const fieldsStore = {
+      getField: vi.fn().mockReturnValue({
+        meta: { options: { allowedCollections: ['partners_catalog', 'service'] } },
+      }),
+    };
+    expect(resolveM2ARelation('orders', 'treatment', parentOnly, fieldsStore)).toEqual({
+      itemField: 'item',
+      discriminator: 'collection',
+      allowedCollections: ['partners_catalog', 'service'],
+    });
+  });
+
+  it('falls back to empty allowedCollections when no fieldsStore is given', () => {
+    expect(resolveM2ARelation('orders', 'treatment', parentOnly)).toEqual({
+      itemField: 'item',
+      discriminator: 'collection',
+      allowedCollections: [],
+    });
+  });
+
+  it('returns null when neither the item relation nor a junction_field is available', () => {
+    const relationsStore = {
+      getRelationsForField: vi.fn().mockReturnValue([{ field: 'orders_id', meta: {} }]),
+    };
+    expect(resolveM2ARelation('orders', 'treatment', relationsStore)).toBeNull();
+  });
+});

From 94acdc3e0340daa607ac22c1d1b1e724895c8e4c Mon Sep 17 00:00:00 2001
From: Christopher Schwarz <christopher@neugebauerschwarz.com>
Date: Mon, 1 Jun 2026 09:56:24 +0200
Subject: [PATCH 2/4] feat: guide M2A template syntax in the column-display
 editor

The system display-template picker can't introspect a polymorphic M2A
target, so adding a column display for an M2A field gave no hint about the
`item:<collection>.<field>` token syntax. Show a help icon and a short hint
(with the field's allowed collections) only for M2A fields.
---
 src/components/ColumnDisplayEditor.vue | 58 ++++++++++++++++++++++++--
 1 file changed, 55 insertions(+), 3 deletions(-)

diff --git a/src/components/ColumnDisplayEditor.vue b/src/components/ColumnDisplayEditor.vue
index 8ac9305..b39fa91 100644
--- a/src/components/ColumnDisplayEditor.vue
+++ b/src/components/ColumnDisplayEditor.vue
@@ -12,7 +12,10 @@
     </div>
 
     <div class="field">
-      <div class="label">Display Template</div>
+      <div class="label">
+        Display Template
+        <v-icon v-if="m2aHelp" v-tooltip="m2aHelp.tooltip" name="help" small class="help-icon" />
+      </div>
       <interface-system-display-template
         :collection-name="targetCollection"
         :value="form.template"
@@ -20,6 +23,10 @@
         :include-relations="true"
         @input="form.template = $event ?? ''"
       />
+      <div v-if="m2aHelp" class="hint">
+        Many-to-Any field — use <code>{{ itemToken }}</code> (no
+        <code>{{ m2aHelp.fieldKey }}.</code> prefix).
+      </div>
     </div>
 
     <div class="actions">
@@ -33,7 +40,8 @@
 import { computed, ref, watch } from 'vue';
 import { useStores } from '@directus/extensions-sdk';
 import type { ColumnDisplay } from '../composables/useColumnDisplays';
-import { isRelational, resolveTargetCollection } from '../utils/displayHeuristics';
+import { isRelational, isM2A, resolveTargetCollection } from '../utils/displayHeuristics';
+import { resolveM2ARelation } from '../utils/resolveM2ARelation';
 
 const props = defineProps<{
   mode: 'add' | 'edit';
@@ -72,6 +80,35 @@ const targetCollection = computed(() => {
   return target ?? props.collection;
 });
 
+// Literal token examples for the M2A help notice (kept out of the template so
+// the mustache braces aren't parsed as Vue interpolation).
+const collectionToken = '{{collection}}';
+const itemToken = '{{item:<collection>.<field>}}';
+
+// The system display-template picker can't introspect the polymorphic M2A
+// target, so guide the user to the `item:collection.field` token syntax.
+const m2aHelp = computed(() => {
+  if (!form.value.fieldKey) return null;
+  const rootKey = form.value.fieldKey.includes(':')
+    ? form.value.fieldKey.split(':')[0]
+    : form.value.fieldKey;
+  const rootField = rootKey.split('.')[0];
+  const fieldDef = fieldsStore.getField(props.collection, rootField);
+  if (!isM2A(fieldDef)) return null;
+
+  const m2a = resolveM2ARelation(props.collection, rootField, relationsStore, fieldsStore);
+  const collections = m2a?.allowedCollections ?? [];
+  const example = collections.length
+    ? `{{collection}}: {{item:${collections[0]}.name}}`
+    : '{{collection}}: {{item:<collection>.name}}';
+  const allowed = collections.length ? `Allowed collections: ${collections.join(', ')}. ` : '';
+  const tooltip =
+    `Many-to-Any field. Write tokens relative to the field (no "${rootField}." prefix). ` +
+    `Use ${collectionToken} for the target collection and ${itemToken} for its values. ` +
+    `${allowed}Example: ${example}`;
+  return { fieldKey: rootField, collections, example, tooltip };
+});
+
 const canSave = computed(() => {
   if (!form.value.fieldKey) return false;
   // Save is disabled in both modes when the template is empty. To delete an
@@ -111,15 +148,30 @@ watch(
   margin-bottom: 12px;
 }
 .label {
-  display: block;
+  display: flex;
+  align-items: center;
+  gap: 4px;
   margin-bottom: 4px;
   color: var(--foreground-normal);
   font-weight: 600;
   font-size: 13px;
 }
+.help-icon {
+  --v-icon-color: var(--foreground-subdued);
+  cursor: help;
+}
 .actions {
   display: flex;
   gap: 8px;
   justify-content: flex-end;
 }
+.hint {
+  margin-top: 4px;
+  color: var(--foreground-subdued);
+  font-size: 12px;
+  line-height: 1.4;
+}
+.hint code {
+  font-size: 11px;
+}
 </style>

From f74152100d493060a748f1adb9909196a6300cdf Mon Sep 17 00:00:00 2001
From: Christopher Schwarz <christopher@neugebauerschwarz.com>
Date: Mon, 1 Jun 2026 09:56:40 +0200
Subject: [PATCH 3/4] docs: document M2A support and correct outdated README
 sections

- Add the Many-to-Any feature and a "Column Displays" usage section
  covering the `item:<collection>.<field>` template syntax.
- Fix factual drift verified against the code: layout name ("Super Table"),
  emitted events, layout-options block, composable names, project-structure
  tree, default page size, workflow list, repo URL and Node version.
---
 README.md | 192 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 109 insertions(+), 83 deletions(-)

diff --git a/README.md b/README.md
index 26c5e88..f4198b0 100644
--- a/README.md
+++ b/README.md
@@ -31,26 +31,28 @@ Powerful search functionality across all table fields, including nested relation
 Switch seamlessly between read-only view mode and interactive edit mode. Control when and how users can modify data.
 
 ### 🖼️ Advanced Image Display & Selection
-Smart image handling with hover preview, proper aspect ratios, and built-in file browser for selecting media files directly from table cells.
+Smart image handling with an enlarged hover preview, proper aspect ratios, and a built-in file browser for selecting media files directly from table cells.
 
 ### 🔄 Deep Duplication
 Duplicate items with all their relationships and translations. Perfect for creating variations of complex data structures.
 
+### 🧩 Many-to-Any (M2A) Display
+Render polymorphic Many-to-Any relationships directly in the table. Use the `related-values` display or a per-column template with the `{{item:collection.field}}` syntax — including nested chains like `{{item:partners_catalog.catalog_id.title}}`. Each junction row resolves against its own target collection.
+
 
 
 ### Display Features
 - **Custom Cell Rendering** - Specialized display for different field types
 - **Relationship Support** - Handle M2O, O2M, M2M, M2A relationships with deep data access
-- **Image Preview** - Inline image display with lightbox support and file browser
+- **Image Preview** - Inline image display with an enlarged hover preview and file browser
 - **Tag Support** - Automatic detection and display of tag fields as visual chips with inline popover editor for adding/removing tags
 - **Status Indicators** - Visual representation of boolean and select fields
 - **Translation Support** - Display multiple language translations as separate columns
 - **Column Alignment** - Configurable text alignment per column (left, center, right)
 
 ### Performance
-- **Optimized Loading** - Default 1000 rows with efficient pagination
-- **Smart Caching** - Intelligent data caching for better performance
-- **Lazy Loading** - Load data as needed for large datasets
+- **Native Pagination** - Server-side pagination with selectable page sizes (25, 50, 100, 250, 500, 1000; default 25)
+- **Separate Count Query** - Item count is fetched independently so the table still renders when the count query is restricted by permissions
 
 
 ## Installation
@@ -87,12 +89,12 @@ npx directus start
 1. Clone or download the extension to your Directus extensions folder:
    ```bash
    cd /path/to/directus/extensions
-   git clone https://github.com/yourusername/super-layout-table.git
+   git clone https://github.com/smartlabsAT/directus-super-table.git
    ```
 
 2. Install dependencies:
    ```bash
-   cd super-layout-table
+   cd directus-super-table
    pnpm install  # or npm install
    ```
 
@@ -105,11 +107,10 @@ npx directus start
 
 ### Configuration
 
-1. Navigate to your collection settings in Directus Admin Panel
-2. Click on "Layout Options" in the collection settings
-3. Select "Super Layout Table" from the layout dropdown
-4. Configure the layout options according to your needs
-5. Save your changes
+1. Open a collection in the Directus Content module
+2. Open the layout dropdown in the sidebar
+3. Select **"Super Table"** as the layout
+4. Configure the layout options in the **Layout Options** sidebar panel
 
 ## Usage Guide
 
@@ -127,21 +128,24 @@ Quick Filters provide fast access to frequently used filter combinations:
 ### Inline Editing
 Edit data directly in the table without opening a separate form:
 
-1. **Entering Edit Mode**: Click on any editable cell
+1. **Entering Edit Mode**: Enable "Edit Mode" in the **Layout Options** sidebar (or the edit toggle in the table header), then click an editable cell
 2. **Editor Types**:
    - Text fields: Simple input or WYSIWYG editor
    - Boolean: Checkbox toggle
    - Select: Dropdown menu
    - Date/Time: Full date picker with calendar
    - Color: Color picker with alignment support
-   - Image/File: Enhanced file browser with larger previews (✨ IMPROVED in v0.2.6)
-3. **Unified Header Actions** (✨ NEW in v0.2.3):
-   - Save/Cancel buttons now in popover header for all field types
+   - Image/File: File browser with larger previews
+3. **Unified Header Actions**:
+   - Save/Cancel buttons in the popover header for all field types
    - Consistent UI across all editors
    - Icon-only buttons matching native Directus style
 4. **Saving**: Click save button (✓) or press Enter
 5. **Canceling**: Click cancel button (✗) or press Escape
 
+> **Note:** Relational fields (M2O, O2M, M2M, M2A) are display-only and are not
+> editable inline — open the item detail view to edit them.
+
 ### Column Management
 Customize which columns are displayed and how:
 
@@ -151,6 +155,34 @@ Customize which columns are displayed and how:
 4. **Reorder Columns**: Drag column headers to reorder
 5. **Resize Columns**: Drag column borders to resize
 
+### Column Displays
+Override how a column renders by attaching a display template, configured in the
+sidebar under **Layout Options → Column Displays**:
+
+1. **Add a display**: Click "Add Column Display", pick a column, and enter a template
+2. **Edit / Remove**: Click an existing entry to edit it, or the ✗ icon to remove it
+3. **Templates** use the `{{ field }}` mustache syntax and may reference related fields
+
+#### Many-to-Any (M2A) templates
+M2A fields are polymorphic — each row points at one of several target collections —
+so their templates use a dedicated `item:` syntax. Tokens are written **relative to
+the field** (do not prefix the field name):
+
+- `{{collection}}` — the name of the row's target collection
+- `{{item:<collection>.<field>}}` — a field on a specific target collection
+- Nested paths are supported, e.g. `{{item:partners_catalog.catalog_id.title}}`
+  (M2A → M2O → value)
+
+Each junction row only resolves the token whose `<collection>` matches its own
+target, so a template can cover every allowed collection at once:
+
+```
+{{collection}}: {{item:partners_catalog.name}} {{item:service.name}}
+```
+
+The editor shows the allowed collections and an example for the selected field. A
+bare token (e.g. `{{name}}`) is intentionally dropped for M2A — use the `item:` form.
+
 ### Bookmarks
 Save table configurations for quick access:
 
@@ -163,35 +195,38 @@ Save table configurations for quick access:
 
 ```
 super-layout-table/
+├── index.ts                          # Extension entry point (defineLayout)
 ├── src/
-│   ├── index.ts                    # Extension entry point
-│   ├── super-layout-table.vue      # Main component
-│   ├── actions.vue                 # Row/bulk actions component
-│   ├── types.ts                    # TypeScript definitions
-│   ├── constants.ts                # Constants and defaults
-│   └── components/
-│       ├── InlineEditPopover.vue   # Inline editor popover
-│       ├── QuickFilters.vue        # Quick filter management
-│       └── CellRenderers/          # Custom cell renderers
-│           ├── ImageCell.vue       # Image display
-│           ├── SelectCell.vue      # Select/status display
-│           └── BooleanCell.vue     # Boolean checkbox
-├── composables/
-│   ├── api.ts                      # API operations
-│   ├── useAliasFields.ts           # Field aliasing logic
-│   └── useLanguageSelector.ts     # Translation language selection
-├── utils/
-│   ├── adjustFieldsForDisplays.ts  # Display field adjustments
-│   └── getDefaultDisplayForType.ts # Default display mapping
-├── package.json                     # Package configuration
-├── tsconfig.json                   # TypeScript configuration
-└── README.md                       # This file
+│   ├── super-table.vue               # Main layout component
+│   ├── options.vue                   # Sidebar layout options
+│   ├── actions.vue                   # Row/bulk actions component
+│   ├── components/
+│   │   ├── InlineEditPopover.vue     # Inline editor popover
+│   │   ├── QuickFilters.vue          # Quick filter management
+│   │   ├── ColumnDisplaysSection.vue # Column-display list + editor
+│   │   ├── ColumnDisplayEditor.vue   # Single column-display form
+│   │   ├── EditableCellRelational.vue# Relational/M2A cell rendering
+│   │   └── CellRenderers/            # Custom cell renderers (image, select, …)
+│   ├── composables/
+│   │   ├── api.ts                    # API operations (useTableApi)
+│   │   ├── useAliasFields.ts         # Field aliasing logic
+│   │   ├── useColumnDisplays.ts      # Column-display override CRUD
+│   │   └── …                         # pagination, sort, permissions, translations
+│   └── utils/
+│       ├── adjustFieldsForDisplays.ts# Display field expansion (incl. M2A)
+│       ├── displayHeuristics.ts      # Template tokenising + relation helpers
+│       ├── resolveM2ARelation.ts     # M2A junction-shape resolver
+│       └── getDefaultDisplayForType.ts# Default display mapping
+├── tests/                            # Vitest unit tests
+├── package.json                      # Package configuration
+├── tsconfig.json                     # TypeScript configuration
+└── README.md                         # This file
 ```
 
 ## Development
 
 ### Prerequisites
-- Node.js 18+
+- Node.js 20+ (CI runs on 20.x and 22.x)
 - pnpm package manager
 - Directus 11.0.0+
 
@@ -238,10 +273,12 @@ Every push and pull request triggers automated quality validation:
 
 ```
 .github/workflows/
-├── quality-checks.yml  # Main quality validation (runs on push/PR)
-├── pr-checks.yml      # PR-specific checks with auto-comments
-├── release.yml        # Automated release creation on tags
-└── badges.yml         # Status badge updates
+├── ci.yml              # CI/CD pipeline (build, test, quality on Node 20.x & 22.x)
+├── quality-checks.yml  # Type-check, lint, format, build (push/PR)
+├── test.yml            # Vitest unit tests
+├── pr-checks.yml       # PR-specific checks with auto-comments
+├── release.yml         # Automated release creation on version tags
+└── badges.yml          # Status badge updates
 ```
 
 ### Running Locally
@@ -266,56 +303,45 @@ pnpm run build         # Build test
 5. GitHub Actions will automatically validate your code
 6. PR will receive an automated quality report comment
 
-### Extension Configuration
-The extension can be configured through the Directus interface with these options:
+### Layout Options
+The layout persists these options (those marked *(sidebar)* have a control in the
+**Layout Options** panel; the rest are set through table interactions):
 
 ```typescript
 {
-  // Number of items to load initially
-  defaultRowCount: 1000,
-  
-  // Row height: 'compact' | 'cozy' | 'comfortable'
-  rowHeight: 'comfortable',
-  
-  // Selection mode: 'none' | 'single' | 'multiple'
-  showSelect: 'multiple',
-  
-  // Enable fixed header
-  fixedHeader: true,
-  
-  // Allow column resizing
-  showResize: true,
-  
-  // Enable inline editing
-  allowInlineEdit: true,
-  
-  // Enable bookmark system
-  allowBookmarks: true,
-  
-  // Enable quick filters
-  allowQuickFilters: true
+  showToolbar?: boolean;          // (sidebar) show the toolbar with actions
+  editMode?: boolean;             // (sidebar) enable inline editing
+  directBooleanToggle?: boolean;  // (sidebar, requires editMode) single-click boolean toggle
+  languageCodeField?: string;     // (sidebar) language-code field for translations (default 'languages_code')
+  customFieldNames?: Record<string, string>;                 // per-column header label overrides
+  columnDisplays?: Record<string, { template: string; display?: string }>; // per-column display templates
+  showSelect?: boolean;           // show row-selection checkboxes
+  spacing?: 'compact' | 'cozy' | 'comfortable';              // row height
+  align?: Record<string, 'left' | 'center' | 'right'>;       // per-column text alignment
+  widths?: Record<string, number>;                           // per-column widths
+  quickFilters?: QuickFilter[];   // saved quick filters
 }
 ```
 
 ## API Reference
 
 ### Events
-The extension emits the following events:
+As a Directus layout, the component emits the standard layout sync events:
 
 - `update:selection` - When item selection changes
-- `update:filters` - When filters are modified
-- `update:search` - When search query changes
-- `update:limit` - When page size changes
-- `update:page` - When current page changes
-- `update:sort` - When sort order changes
-- `update:fields` - When visible fields change
+- `update:layoutOptions` - When a layout option changes (column displays, edit mode, alignment, widths, …)
+- `update:layoutQuery` - When the query changes (fields, sort, page, limit)
+- `update:search` - When the search query changes
+
+The `filter` prop is consumed read-only (filtering is driven by Directus), so no
+`update:filter` event is emitted.
 
 ### Composables
 Available composables for extension development:
 
-- `useApi()` - API operations wrapper
+- `useTableApi()` - API operations wrapper (fetch, count, update, delete, export)
 - `useAliasFields()` - Field aliasing for complex queries
-- `useLanguageSelector()` - Translation language management
+- `useColumnDisplays()` - Per-column display-template overrides
 
 ## Browser Support
 
@@ -349,14 +375,14 @@ Contributions are welcome! Please follow these guidelines:
 - Try clearing browser cache
 
 ### Inline editing not working
-- Check field permissions in Directus
-- Ensure fields are not read-only
-- Verify field types are supported
+- Make sure "Edit Mode" is enabled in the Layout Options sidebar
+- Check field permissions in Directus (no update permission = read-only)
+- Ensure fields are not configured as read-only
+- Note: relational fields (M2O, O2M, M2M, M2A) are display-only by design
 
 ### Performance issues
-- Reduce default row count
-- Enable pagination for large datasets
-- Check browser console for errors
+- Choose a smaller page size (the per-page selector defaults to 25)
+- Check the browser console for errors
 
 ## Changelog
 

From e773b2163f678c5fb981d91a95835f9ec20df680 Mon Sep 17 00:00:00 2001
From: Christopher Schwarz <christopher@neugebauerschwarz.com>
Date: Mon, 1 Jun 2026 09:56:54 +0200
Subject: [PATCH 4/4] chore: bump version to 0.5.0 for M2A support

---
 CHANGELOG.md | 34 ++++++++++++++++++++++++++++++++++
 package.json |  2 +-
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9f56eea..4db30e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,40 @@ All notable changes to the Super Layout Table Extension will be documented in th
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.5.0 — Many-to-Any support (Issue #60)
+
+### Added
+- **Many-to-Any (M2A) fields are now supported** as display columns. The
+  `related-values` display and per-column overrides resolve the polymorphic
+  `item:collection.field` template syntax, including nested chains such as
+  `{{item:partners_catalog.catalog_id.title}}` (M2A → M2O → scalar). Each
+  junction row renders against its own collection discriminator. Reported by
+  @Abdallah-Awwad in #60.
+- **In-body error state:** when the items request fails, the layout now shows
+  an explicit error notice instead of a blank body under a live pagination bar.
+
+### Fixed
+- **M2A raw template / empty cell:** M2A columns previously rendered the literal
+  display template (or an empty cell) because the query never expanded the
+  per-collection `item:` paths and the renderer never unwrapped the junction
+  rows. Both paths now handle M2A.
+- **M2A column display → 0 results:** adding a column-display template on an M2A
+  field expanded into an invalid junction field path, 403'd the items request,
+  and blanked the table while pagination stayed visible. Invalid/bare tokens are
+  now dropped before the request, and the footer is gated on the same
+  renderable-data condition as the table.
+
+### Refactor
+- New `resolveM2ARelation` helper centralises the M2A junction-shape lookup
+  (discriminator, item field, allowed collections) in one place, mirroring the
+  `resolveTranslationsCollection` pattern — replacing three hand-written copies
+  across the query and render layers.
+- M2A template grammar (`M2A_TOKEN_RE`, `parseM2AToken`, `buildM2AFieldPath`)
+  now lives in `displayHeuristics`, so the field-path emit and the render-side
+  read share a single source and cannot drift.
+- Cell rendering reuses `get` from `@directus/utils` for nested-path access
+  instead of a bespoke walker.
+
 ## v0.4.2 — Marketplace metadata
 
 ### Changed
diff --git a/package.json b/package.json
index 3c55cad..ca63e5c 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "directus-extension-super-table",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "A powerful and feature-rich table layout extension for Directus 11+ with inline editing, quick filters, and manual sorting",
   "icon": "table_rows",
   "keywords": [