[DX-720] Enable nested tables to contain multiple types

src/components/Layout/mdx/NestedTable/NestedTableContext.tsx

@@ -5,7 +5,8 @@ export interface TableProperty {
   required?: 'required' | 'optional'; // Optional - not present in 2 or 3 column tables
   description: ReactNode; // ReactNode to preserve markdown elements (links, lists, etc.)
   type?: ReactNode; // ReactNode to preserve markdown elements (links, etc.) - not present in 2 column tables
-  typeReference?: string; // ID of referenced table, if type is a table reference
+  typeReferences: string[]; // IDs of all referenced tables (empty array if none)
+  typeDisplay?: ReactNode; // Cleaned-up display for the type cell (Table elements replaced with their ID text)
 }
 
 export interface TableData {
@@ -61,7 +62,8 @@ export const NestedTableProvider: React.FC<NestedTableProviderProps> = ({ childr
         (prop, i) =>
           prop.name !== data.properties[i]?.name ||
           prop.required !== data.properties[i]?.required ||
-          prop.typeReference !== data.properties[i]?.typeReference,
+          prop.typeReferences.length !== data.properties[i]?.typeReferences.length ||
+          prop.typeReferences.some((ref, j) => ref !== data.properties[i]?.typeReferences[j]),
       );
     if (hasChanged) {
       registryRef.current.set(id, data);

src/components/Layout/mdx/NestedTable/NestedTablePropertyRow.tsx

@@ -1,6 +1,6 @@
 import React, { useMemo } from 'react';
 import cn from '@ably/ui/core/utils/cn';
-import { TableProperty, useNestedTable } from './NestedTableContext';
+import { TableData, TableProperty, useNestedTable } from './NestedTableContext';
 import { NestedTableExpandButton } from './NestedTableExpandButton';
 
 interface NestedTablePropertyRowProps {
@@ -12,12 +12,14 @@ interface NestedTablePropertyRowProps {
 export const NestedTablePropertyRow: React.FC<NestedTablePropertyRowProps> = ({ property, path, depth = 0 }) => {
   const { lookup, isExpanded, toggleExpanded, registryVersion } = useNestedTable();
   const expandPath = `${path}.${property.name}`;
-  const expanded = isExpanded(expandPath);
 
-  // Look up the referenced table, re-computing when registry changes
-  const referencedTable = useMemo(
-    () => (property.typeReference ? lookup(property.typeReference) : undefined),
-    [property.typeReference, lookup, registryVersion],
+  // Look up all referenced tables, re-computing when registry changes
+  const referencedTables = useMemo(
+    () =>
+      property.typeReferences
+        .map((ref) => ({ id: ref, table: lookup(ref) }))
+        .filter((entry): entry is { id: string; table: TableData } => entry.table !== undefined),
+    [property.typeReferences, lookup, registryVersion],
   );
 
   return (
@@ -42,10 +44,10 @@ export const NestedTablePropertyRow: React.FC<NestedTablePropertyRowProps> = ({
             </span>
           )}
 
-          {/* Type name - only shown for 3 or 4-column tables. Use typeReference if available for cleaner display. */}
-          {(property.typeReference || property.type) && (
+          {/* Type name - use typeDisplay for cleaned-up rendering, fall back to raw type */}
+          {(property.typeReferences.length > 0 || property.type) && (
             <span className="text-sm text-neutral-600 font-semibold dark:text-neutral-500">
-              {property.typeReference ?? property.type}
+              {property.typeDisplay ?? property.type}
             </span>
           )}
         </div>
@@ -55,39 +57,40 @@ export const NestedTablePropertyRow: React.FC<NestedTablePropertyRowProps> = ({
           {property.description}
         </div>
 
-        {/* Expand/collapse button and nested content */}
-        {referencedTable && property.typeReference && (
-          <>
-            {/* Collapsed: standalone button */}
-            {!expanded && (
-              <NestedTableExpandButton
-                typeName={property.typeReference}
-                expanded={false}
-                onClick={() => toggleExpanded(expandPath)}
-              />
-            )}
+        {/* Expand/collapse buttons and nested content - one per resolved table reference */}
+        {referencedTables.map(({ id, table }) => {
+          const refExpandPath = `${expandPath}.${id}`;
+          const refExpanded = isExpanded(refExpandPath);
 
-            {/* Expanded: button attached to nested container */}
-            {expanded && (
-              <div className="mt-3 border border-neutral-400 dark:border-neutral-900 rounded-lg overflow-hidden">
-                {/* Hide button as header of the container */}
-                <NestedTableExpandButton
-                  typeName={property.typeReference}
-                  expanded={true}
-                  onClick={() => toggleExpanded(expandPath)}
-                />
-                {/* Nested properties */}
-                <div className="divide-y divide-neutral-400 dark:divide-neutral-900">
-                  {referencedTable.properties.map((nestedProperty) => (
-                    <div key={nestedProperty.name} className="px-3 sm:px-5">
-                      <NestedTablePropertyRow property={nestedProperty} path={expandPath} depth={depth + 1} />
-                    </div>
-                  ))}
+          return (
+            <React.Fragment key={id}>
+              {/* Collapsed: standalone button */}
+              {!refExpanded && (
+                <NestedTableExpandButton typeName={id} expanded={false} onClick={() => toggleExpanded(refExpandPath)} />
+              )}
+
+              {/* Expanded: button attached to nested container */}
+              {refExpanded && (
+                <div className="mt-3 border border-neutral-400 dark:border-neutral-900 rounded-lg overflow-hidden">
+                  {/* Hide button as header of the container */}
+                  <NestedTableExpandButton
+                    typeName={id}
+                    expanded={true}
+                    onClick={() => toggleExpanded(refExpandPath)}
+                  />
+                  {/* Nested properties */}
+                  <div className="divide-y divide-neutral-400 dark:divide-neutral-900">
+                    {table.properties.map((nestedProperty) => (
+                      <div key={nestedProperty.name} className="px-3 sm:px-5">
+                        <NestedTablePropertyRow property={nestedProperty} path={refExpandPath} depth={depth + 1} />
+                      </div>
+                    ))}
+                  </div>
                 </div>
-              </div>
-            )}
-          </>
-        )}
+              )}
+            </React.Fragment>
+          );
+        })}
       </div>
     </div>
   );