@eventcatalog/core 4.10.14 → 4.11.0

package/eventcatalog/src/components/MDX/Columns/MarkdownColumns.tsx

@@ -0,0 +1,37 @@
+import type { CSSProperties, ReactNode } from 'react';
+import { getColumnsLayout, columnsClass, gridClass, columnClass, stickyClass } from './layout';
+
+export function MarkdownColumns({
+  children,
+  cols = 2,
+  ratio,
+  className = '',
+}: {
+  children?: ReactNode;
+  cols?: number;
+  ratio?: string;
+  className?: string;
+}) {
+  const { template } = getColumnsLayout(cols, ratio);
+  return (
+    <div className={`${columnsClass} ${className}`} style={{ '--ec-columns-template': template } as CSSProperties}>
+      <div className={gridClass}>{children}</div>
+    </div>
+  );
+}
+
+export function MarkdownColumn({
+  children,
+  sticky = false,
+  className = '',
+}: {
+  children?: ReactNode;
+  sticky?: boolean;
+  className?: string;
+}) {
+  return (
+    <div className={`${columnClass} ${sticky ? stickyClass : ''} ${className}`} data-sticky={String(sticky)}>
+      {children}
+    </div>
+  );
+}

package/eventcatalog/src/components/MDX/Columns/columns.spec.tsx

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { renderToStaticMarkup } from 'react-dom/server';
+import ReactMarkdown from 'react-markdown';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import * as runtime from 'react/jsx-runtime';
+import { getColumnsLayout } from './layout';
+import { MarkdownColumns, MarkdownColumn } from './MarkdownColumns';
+import { remarkMarkdownColumns } from '../../../remark-plugins/markdown-columns';
+import { remarkMarkdownCodeGroup } from '../../../remark-plugins/markdown-code-group';
+
+const source =
+  '<Columns cols={2} ratio="2:1">\n  <Column>\n\n## Publish an order\n\nSome **explanation**.\n\n  </Column>\n  <Column sticky>\n\n<CodeGroup>\n\n```json OrderCreated\n{"id":"123"}\n```\n\n```js JavaScript\npublish();\n```\n\n</CodeGroup>\n\n  </Column>\n</Columns>';
+
+describe('Columns', () => {
+  it('defaults to two columns and supports one through four', () => {
+    expect(getColumnsLayout().template).toBe('repeat(2, minmax(0, 1fr))');
+    for (const count of [1, 2, 3, 4]) expect(getColumnsLayout(count).count).toBe(count);
+  });
+  it('uses valid ratios and safely falls back for invalid options', () => {
+    expect(getColumnsLayout(2, '2:1').template).toBe('minmax(0, 2fr) minmax(0, 1fr)');
+    for (const ratio of ['0:1', '-1:2', 'NaN:1', '1:2:3', '1fr:2fr', 'Infinity:1']) {
+      expect(getColumnsLayout(2, ratio).template).toBe('repeat(2, minmax(0, 1fr))');
+    }
+    for (const count of [0, 5, 1.5, NaN]) expect(getColumnsLayout(count).count).toBe(2);
+  });
+  it('renders the same API as real MDX with rich content and nested components', async () => {
+    const require = createRequire(import.meta.url);
+    const mdxRequire = createRequire(require.resolve('@astrojs/mdx'));
+    const { evaluate } = await import(pathToFileURL(mdxRequire.resolve('@mdx-js/mdx')).href);
+    const result = await evaluate(source, runtime);
+    const html = renderToStaticMarkup(
+      runtime.jsx(result.default, {
+        components: {
+          Columns: MarkdownColumns,
+          Column: MarkdownColumn,
+          CodeGroup: 'section',
+        },
+      })
+    );
+    expect(html).toContain('--ec-columns-template:minmax(0, 2fr) minmax(0, 1fr)');
+    expect(html).toContain('data-sticky="true"');
+    expect(html).toContain('<strong>explanation</strong>');
+    expect(html).toContain('language-json');
+  });
+  it('recognizes adjacent layout tags in Markdown and lets CodeGroup transform within columns', () => {
+    const html = renderToStaticMarkup(
+      <ReactMarkdown remarkPlugins={[remarkMarkdownColumns, remarkMarkdownCodeGroup]}>{source}</ReactMarkdown>
+    );
+    expect(html).toContain('data-columns="true"');
+    expect(html.match(/data-column="true"/g)).toHaveLength(2);
+    expect(html).toContain('data-cols="2"');
+    expect(html).toContain('data-ratio="2:1"');
+    expect(html).toContain('data-sticky="true"');
+    expect(html).toContain('data-code-panel="OrderCreated"');
+    expect(html).toContain('<strong>explanation</strong>');
+    expect(html).not.toContain('&lt;Column');
+  });
+  it('preserves nested column layouts and leaves unrelated HTML escaped', () => {
+    const nested =
+      '<Columns>\n\n<Column>\n\n<Columns cols={1}>\n\n<Column>\n\nInner\n\n</Column>\n\n</Columns>\n\n</Column>\n\n</Columns>\n\n<script>alert(1)</script>';
+    const html = renderToStaticMarkup(<ReactMarkdown remarkPlugins={[remarkMarkdownColumns]}>{nested}</ReactMarkdown>);
+    expect(html.match(/data-columns="true"/g)).toHaveLength(2);
+    expect(html).not.toContain('<script>');
+  });
+});

package/eventcatalog/src/components/MDX/Columns/layout.ts

@@ -0,0 +1,16 @@
+export function getColumnsLayout(cols: number = 2, ratio?: string) {
+  const count = Number.isInteger(cols) && cols >= 1 && cols <= 4 ? cols : 2;
+  const weights = ratio?.split(':').map(Number);
+  const validRatio = weights?.length === count && weights.every((weight) => Number.isFinite(weight) && weight > 0);
+  return {
+    count,
+    template: validRatio ? weights.map((weight) => `minmax(0, ${weight}fr)`).join(' ') : `repeat(${count}, minmax(0, 1fr))`,
+  };
+}
+
+export const columnsClass = 'ec-columns @container/ec-columns my-6';
+export const gridClass =
+  'ec-columns-grid grid grid-cols-1 items-start gap-8 [&>*]:min-w-0 @min-[640px]/ec-columns:grid-cols-[var(--ec-columns-template)]';
+export const columnClass = 'ec-column min-w-0 [&>:first-child]:mt-0 [&>:last-child]:mb-0';
+export const stickyClass =
+  '@min-[640px]/ec-columns:sticky @min-[640px]/ec-columns:top-[var(--ec-column-sticky-top,5rem)] print:static';

package/eventcatalog/src/components/MDX/components.tsx

@@ -22,6 +22,9 @@ import ResourceGroupTable from '@components/MDX/ResourceGroupTable/ResourceGroup
 import EntityPropertiesTable from '@components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro';
 import Tabs from '@components/MDX/Tabs/Tabs.astro';
 import TabItem from '@components/MDX/Tabs/TabItem.astro';
+import CodeGroup from '@components/MDX/CodeGroup/CodeGroup.astro';
+import Columns from '@components/MDX/Columns/Columns.astro';
+import Column from '@components/MDX/Columns/Column.astro';
 import ResourceLink from '@components/MDX/ResourceLink/ResourceLink.astro';
 import ResourceRef from '@components/MDX/ResourceRef/ResourceRef.astro';
 import Link from '@components/MDX/Link/Link.astro';
@@ -85,6 +88,9 @@ const components = (props: any) => {
     Step,
     Steps,
     TabItem,
+    CodeGroup,
+    Columns,
+    Column,
     Tabs,
     Tile,
     Tiles,

package/eventcatalog/src/components/SchemaExplorer/ApiContentViewer.tsx

@@ -134,7 +134,7 @@ export default function ApiContentViewer({ message, onCopy, copiedId, apiAccessE
                 className="rounded-md border bg-[rgb(var(--ec-content-hover)/0.45)] px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))]"
                 style={{ borderColor: boxBorderColor }}
               >
-                application/json
+                text/plain
               </code>
             </div>
             <div className="flex items-center justify-between gap-4 border-t px-4 py-3" style={{ borderColor: dividerColor }}>

package/eventcatalog/src/components/SchemaExplorer/ExamplesViewer.tsx

@@ -1,146 +1,183 @@
-import { useState, useEffect } from 'react';
-import { ClipboardDocumentIcon } from '@heroicons/react/24/outline';
+import { createContext, useContext, useState, type ReactNode } from 'react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { CheckIcon, ClipboardDocumentIcon } from '@heroicons/react/24/outline';
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { oneDark } from 'react-syntax-highlighter/dist/cjs/styles/prism';
 import { oneLight } from 'react-syntax-highlighter/dist/cjs/styles/prism';
-import { getLanguageForHighlight } from './utils';
 import { copyToClipboard } from './utils';
 import type { MessageExample } from './types';
 import { useDarkMode } from './useDarkMode';
+import { remarkMarkdownCodeGroup } from '../../remark-plugins/markdown-code-group';
+import { MarkdownCodeGroup } from '../MDX/CodeGroup/MarkdownCodeGroup';
+import { MarkdownColumns, MarkdownColumn } from '../MDX/Columns/MarkdownColumns';
+import { remarkMarkdownColumns } from '../../remark-plugins/markdown-columns';
+import { getLanguageForHighlight } from './utils';
 
 interface ExamplesViewerProps {
   examples: MessageExample[];
 }
 
-export default function ExamplesViewer({ examples }: ExamplesViewerProps) {
-  const [selectedIndex, setSelectedIndex] = useState(0);
-  const [copiedId, setCopiedId] = useState<string | null>(null);
-  const isDarkMode = useDarkMode();
+const PROSE_CLASS = [
+  'prose prose-sm max-w-none',
+  'prose-headings:text-[rgb(var(--ec-page-text))] prose-h1:mt-0 prose-h1:text-4xl prose-h1:font-bold prose-h1:tracking-tight',
+  'prose-p:text-[rgb(var(--ec-page-text-muted))] prose-li:text-[rgb(var(--ec-page-text-muted))] prose-strong:text-[rgb(var(--ec-page-text))]',
+  'prose-a:text-[rgb(var(--ec-accent))] prose-table:text-[rgb(var(--ec-page-text-muted))] prose-th:text-[rgb(var(--ec-page-text))]',
+  'prose-blockquote:border-[rgb(var(--ec-page-border))] prose-blockquote:text-[rgb(var(--ec-page-text-muted))] prose-hr:border-[rgb(var(--ec-page-border))]',
+].join(' ');
 
-  useEffect(() => {
-    setSelectedIndex(0);
-  }, [examples]);
+const getCodeText = (children: ReactNode): string =>
+  Array.isArray(children) ? children.map(getCodeText).join('') : typeof children === 'string' ? children : '';
 
-  if (examples.length === 0) {
+/** True while rendering inside a CodeGroup panel, where the group supplies the header and copy button. */
+const CodeGroupPanelContext = createContext(false);
+
+/** Fenced code block rendered as the same themed code panel used across the schema page. */
+function CodeBlock({ language, code }: { language?: string; code: string }) {
+  const isDarkMode = useDarkMode();
+  const [isCopied, setIsCopied] = useState(false);
+  const inCodeGroup = useContext(CodeGroupPanelContext);
+  const content = code.replace(/\s+$/, '');
+  const highlighter = (
+    <SyntaxHighlighter
+      language={language || 'text'}
+      style={isDarkMode ? oneDark : oneLight}
+      customStyle={{
+        margin: 0,
+        padding: '1rem 1.25rem',
+        borderRadius: 0,
+        fontSize: '0.8125rem',
+        lineHeight: '1.65',
+        background: 'transparent',
+      }}
+      showLineNumbers={content.includes('\n')}
+      wrapLines={true}
+      wrapLongLines={true}
+    >
+      {content}
+    </SyntaxHighlighter>
+  );
+
+  // Inside a group the panel chrome (file name, language picker, copy) belongs to the group.
+  // Keep the raw source on a data attribute so the group's copy button gets clean text.
+  if (inCodeGroup) {
     return (
-      <div className="flex items-center justify-center h-full text-[rgb(var(--ec-page-text-muted))]">
-        <p className="text-sm">No examples available</p>
+      <div data-code={content} className="not-prose max-h-[70vh] overflow-auto">
+        {highlighter}
       </div>
     );
   }
 
-  const selected = examples[selectedIndex];
-  const lang = getLanguageForHighlight(selected.extension);
-
-  const handleCopy = async (content: string, id: string) => {
-    const success = await copyToClipboard(content);
-    if (success) {
-      setCopiedId(id);
-      setTimeout(() => setCopiedId(null), 2000);
+  const handleCopy = async () => {
+    if (await copyToClipboard(content)) {
+      setIsCopied(true);
+      setTimeout(() => setIsCopied(false), 2000);
     }
   };
 
   return (
-    <div className="h-full flex gap-4 overflow-hidden">
-      {/* Left: example list */}
-      <div className="flex-shrink-0 w-56 overflow-y-auto space-y-1">
-        {examples.map((ex, idx) => (
-          <button
-            key={ex.fileName}
-            onClick={() => setSelectedIndex(idx)}
-            className={`w-full text-left px-3 py-2.5 rounded-lg transition-colors ${
-              idx === selectedIndex
-                ? 'bg-[rgb(var(--ec-accent-subtle))] border border-[rgb(var(--ec-accent)/0.3)]'
-                : 'hover:bg-[rgb(var(--ec-content-hover))] border border-transparent'
-            }`}
-          >
-            <span
-              className={`block text-xs font-medium truncate ${
-                idx === selectedIndex ? 'text-[rgb(var(--ec-page-text))]' : 'text-[rgb(var(--ec-page-text-muted))]'
-              }`}
-            >
-              {ex.title}
-            </span>
-            {ex.summary && (
-              <span className="block text-[11px] text-[rgb(var(--ec-page-text-muted))] mt-0.5 line-clamp-2 leading-relaxed">
-                {ex.summary}
-              </span>
-            )}
-          </button>
-        ))}
+    <div
+      data-example-code-block
+      className="not-prose my-4 overflow-hidden rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-code-bg))] shadow-sm"
+    >
+      <div className="flex items-center justify-between gap-3 border-b border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover)/0.45)] px-3 py-1.5">
+        <span className="rounded-md bg-[rgb(var(--ec-content-hover))] px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wider text-[rgb(var(--ec-page-text-muted))]">
+          {language || 'text'}
+        </span>
+        <button
+          type="button"
+          onClick={handleCopy}
+          className={`inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium transition-colors ${
+            isCopied
+              ? 'text-emerald-500'
+              : 'text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))]'
+          }`}
+          title="Copy code"
+        >
+          {isCopied ? <CheckIcon className="h-3.5 w-3.5" /> : <ClipboardDocumentIcon className="h-3.5 w-3.5" />}
+          {isCopied ? 'Copied' : 'Copy'}
+        </button>
       </div>
+      <div className="max-h-[70vh] overflow-auto">{highlighter}</div>
+    </div>
+  );
+}
 
-      {/* Right: code + usage */}
-      <div className="flex-1 flex flex-col min-w-0 overflow-auto">
-        {/* Code window */}
-        <div className="flex flex-col rounded-lg border border-[rgb(var(--ec-page-border))] overflow-hidden bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
-          {/* Window title bar */}
-          <div className="flex items-center justify-between border-b border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover)/0.45)] px-4 py-2.5">
-            <div className="flex items-center gap-3">
-              <div className="flex items-center gap-1.5">
-                <div className="w-3 h-3 rounded-full bg-[#FF5F56]" />
-                <div className="w-3 h-3 rounded-full bg-[#FFBD2E]" />
-                <div className="w-3 h-3 rounded-full bg-[#27C93F]" />
-              </div>
-              <span className="text-xs font-mono text-[rgb(var(--ec-page-text-muted))]">{selected.fileName}</span>
-            </div>
-
-            <button
-              onClick={() => handleCopy(selected.content, selected.fileName)}
-              className="inline-flex items-center gap-1 px-2 py-1 text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-page-bg)/0.5)] hover:text-[rgb(var(--ec-page-text))] rounded transition-colors"
-              title="Copy code"
-            >
-              <ClipboardDocumentIcon className="h-3 w-3" />
-              {copiedId === selected.fileName ? 'Copied!' : 'Copy'}
-            </button>
-          </div>
+const markdownComponents = {
+  div: ({ node: _node, children, ...props }: any) =>
+    props['data-columns'] ? (
+      <MarkdownColumns cols={Number(props['data-cols'])} ratio={props['data-ratio']} className={props.className}>
+        {children}
+      </MarkdownColumns>
+    ) : props['data-column'] ? (
+      <MarkdownColumn sticky={props['data-sticky'] === 'true'} className={props.className}>
+        {children}
+      </MarkdownColumn>
+    ) : props['data-code-group'] ? (
+      <MarkdownCodeGroup dropdown={props['data-dropdown'] === 'true'} className={props.className}>
+        {children}
+      </MarkdownCodeGroup>
+    ) : props['data-code-panel'] ? (
+      <div {...props}>
+        <CodeGroupPanelContext.Provider value={true}>{children}</CodeGroupPanelContext.Provider>
+      </div>
+    ) : (
+      <div {...props}>{children}</div>
+    ),
+  // Fenced blocks arrive as <pre><code class="language-x">. Render the panel from `code` and drop the <pre>.
+  pre: ({ children }: { children?: ReactNode }) => <>{children}</>,
+  code: ({ className, children }: { className?: string; children?: ReactNode }) => {
+    const language = /language-(\w+)/.exec(className || '')?.[1];
+    const text = getCodeText(children);
+    if (language || text.includes('\n')) return <CodeBlock language={language} code={text} />;
+    return (
+      <code className="rounded bg-[rgb(var(--ec-content-hover)/0.6)] px-1.5 py-0.5 font-mono text-[12px] font-normal text-[rgb(var(--ec-page-text))] before:content-none after:content-none">
+        {children}
+      </code>
+    );
+  },
+};
 
-          {/* Code content */}
-          <div className="overflow-auto">
-            <SyntaxHighlighter
-              language={lang}
-              style={isDarkMode ? oneDark : oneLight}
-              customStyle={{
-                margin: 0,
-                padding: '1rem 1.25rem',
-                borderRadius: 0,
-                fontSize: '0.8125rem',
-                lineHeight: '1.625',
-                overflow: 'auto',
-                background: 'transparent',
-              }}
-              showLineNumbers={true}
-              wrapLines={true}
-              wrapLongLines={true}
-            >
-              {selected.content}
-            </SyntaxHighlighter>
-          </div>
-        </div>
+/** Lists every usage example, rendering Markdown as prose and other formats as source. */
+export default function ExamplesViewer({ examples }: ExamplesViewerProps) {
+  if (examples.length === 0) {
+    return (
+      <div className="flex h-full items-center justify-center text-[rgb(var(--ec-page-text-muted))]">
+        <p className="text-sm">No examples available</p>
+      </div>
+    );
+  }
 
-        {/* Usage section */}
-        {selected.usage && (
-          <div className="flex-shrink-0 mt-3">
-            <div className="rounded-lg border border-[rgb(var(--ec-page-border))] overflow-hidden bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
-              <div className="flex items-center justify-between border-b border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover)/0.45)] px-4 py-2">
-                <span className="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Usage</span>
-                <button
-                  onClick={() => handleCopy(selected.usage!, `usage-${selected.fileName}`)}
-                  className="inline-flex items-center gap-1 px-2 py-1 text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-page-bg)/0.5)] hover:text-[rgb(var(--ec-page-text))] rounded transition-colors"
-                  title="Copy usage"
+  return (
+    <div className="h-full overflow-auto pr-1">
+      <div className="divide-y divide-[rgb(var(--ec-page-border))]">
+        {examples.map((example) => (
+          <section
+            key={example.fileName}
+            id={`example-${example.fileName.replace(/[^a-zA-Z0-9]+/g, '-')}`}
+            className="w-full py-8 pr-8 first:pt-0 last:pb-0"
+          >
+            {example.summary && <p className="mb-4 text-sm text-[rgb(var(--ec-page-text-muted))]">{example.summary}</p>}
+            {example.renderMode === 'markdown' ? (
+              <div className={PROSE_CLASS}>
+                <ReactMarkdown
+                  remarkPlugins={[remarkGfm, remarkMarkdownColumns, remarkMarkdownCodeGroup]}
+                  components={markdownComponents}
                 >
-                  <ClipboardDocumentIcon className="h-3 w-3" />
-                  {copiedId === `usage-${selected.fileName}` ? 'Copied!' : 'Copy'}
-                </button>
+                  {example.content}
+                </ReactMarkdown>
               </div>
-              <div className="overflow-auto max-h-32">
-                <pre className="m-0 px-5 py-3 text-[0.75rem] leading-[1.5] whitespace-pre-wrap break-words text-[rgb(var(--ec-page-text-muted))] bg-transparent font-mono">
-                  <code>{selected.usage}</code>
-                </pre>
+            ) : (
+              <CodeBlock language={getLanguageForHighlight(example.extension)} code={example.content} />
+            )}
+            {example.usage && (
+              <div className="mt-5">
+                <h3 className="text-xs font-semibold uppercase tracking-wider text-[rgb(var(--ec-page-text-muted))]">Usage</h3>
+                <CodeBlock language="bash" code={example.usage} />
               </div>
-            </div>
-          </div>
-        )}
+            )}
+          </section>
+        ))}
       </div>
     </div>
   );

package/eventcatalog/src/components/SchemaExplorer/JSONSchemaViewer.test.tsx

@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import JSONSchemaViewer from './JSONSchemaViewer';
+
+const constraintOnlyVariantSchema = {
+  type: 'object',
+  properties: {
+    detail: { $ref: '#/$defs/detail' },
+  },
+  $defs: {
+    detail: {
+      type: 'object',
+      properties: {
+        data: { $ref: '#/$defs/data' },
+      },
+    },
+    data: {
+      type: 'object',
+      properties: {
+        userId: { type: 'string' },
+        customerId: { type: 'string' },
+        correlationId: { type: 'string' },
+      },
+      required: ['correlationId'],
+      oneOf: [
+        {
+          title: 'Authenticated user',
+          required: ['userId'],
+          not: { required: ['customerId'] },
+        },
+        {
+          title: 'Customer account',
+          required: ['customerId'],
+          not: { required: ['userId'] },
+        },
+      ],
+    },
+  },
+};
+
+describe('JSONSchemaViewer variants', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true);
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  it('renders parent properties selected by constraint-only oneOf branches', () => {
+    act(() => {
+      root.render(createElement(JSONSchemaViewer, { schema: constraintOnlyVariantSchema, expand: true, search: false }));
+    });
+
+    expect(container.textContent).toContain('Authenticated user');
+    expect(container.textContent).toContain('userId');
+    expect(container.textContent).not.toContain('customerId');
+    expect(container.textContent).toContain('correlationId');
+
+    const selector = container.querySelector<HTMLSelectElement>('select');
+    expect(selector).not.toBeNull();
+
+    act(() => {
+      selector!.value = '1';
+      selector!.dispatchEvent(new Event('change', { bubbles: true }));
+    });
+
+    expect(container.textContent).toContain('customerId');
+    expect(container.textContent).not.toContain('userId');
+    expect(container.textContent).toContain('correlationId');
+  });
+
+  it('applies constraint-only oneOf branches at the schema root', () => {
+    const rootSchema = constraintOnlyVariantSchema.$defs.data;
+
+    act(() => {
+      root.render(createElement(JSONSchemaViewer, { schema: rootSchema, expand: true, search: false }));
+    });
+
+    expect(container.textContent).toContain('userId');
+    expect(container.textContent).not.toContain('customerId');
+    expect(container.textContent).toContain('correlationId');
+  });
+
+  it('does not render array item parent properties twice when variants are present', () => {
+    const arraySchema = {
+      type: 'object',
+      properties: {
+        identities: {
+          type: 'array',
+          items: constraintOnlyVariantSchema.$defs.data,
+        },
+      },
+    };
+
+    act(() => {
+      root.render(createElement(JSONSchemaViewer, { schema: arraySchema, expand: true, search: false }));
+    });
+
+    expect(container.textContent?.match(/userId/g)).toHaveLength(1);
+    expect(container.textContent).not.toContain('customerId');
+    expect(container.textContent?.match(/correlationId/g)).toHaveLength(1);
+  });
+});

package/eventcatalog/src/components/SchemaExplorer/JSONSchemaViewer.tsx

@@ -31,6 +31,15 @@ function formatType(type: any): string {
   return type ?? '';
 }
 
+function getForbiddenVariantProperties(variant: any): string[] {
+  const forbiddenRequired = variant?.not?.required;
+
+  // `not: { required: ['field'] }` forbids that field from being present. When
+  // multiple fields are listed, JSON Schema only forbids them being present
+  // together, so none of them can safely be hidden individually.
+  return Array.isArray(forbiddenRequired) && forbiddenRequired.length === 1 ? forbiddenRequired : [];
+}
+
 // Helper function to count properties recursively
 function countProperties(obj: any): number {
   if (!obj || typeof obj !== 'object') return 0;
@@ -173,26 +182,35 @@ function processSchema(schema: any, rootSchema?: any): any {
     const variantsArray = schema.oneOf || schema.anyOf;
     const variantType = schema.oneOf ? 'oneOf' : 'anyOf';
 
+    const processedProperties = schema.properties
+      ? Object.fromEntries(
+          Object.entries(schema.properties).map(([key, prop]: [string, any]) => [key, processSchema(prop, root)])
+        )
+      : {};
+
     const processedVariants = variantsArray.map((variant: any, index: number) => {
       const processedVariant = processSchema(variant, root);
+      const forbiddenProperties = new Set(getForbiddenVariantProperties(processedVariant));
+      const properties = Object.fromEntries(
+        Object.entries({ ...processedProperties, ...(processedVariant.properties || {}) }).filter(
+          ([propertyName]) => !forbiddenProperties.has(propertyName)
+        )
+      );
+
       return {
+        ...processedVariant,
         title: processedVariant.title || variant.title || processedVariant.$id || `Option ${index + 1}`,
         description: processedVariant.description || variant.description,
-        required: processedVariant.required || variant.required || [],
-        properties: processedVariant.properties || {},
+        required: [...new Set([...(schema.required || []), ...(processedVariant.required || variant.required || [])])],
+        properties,
         type: processedVariant.type || variant.type || 'object',
-        ...processedVariant,
       };
     });
 
     return {
       ...schema,
       type: schema.type || 'object',
-      properties: schema.properties
-        ? Object.fromEntries(
-            Object.entries(schema.properties).map(([key, prop]: [string, any]) => [key, processSchema(prop, root)])
-          )
-        : {},
+      properties: processedProperties,
       variants: processedVariants,
       variantType,
     };
@@ -462,6 +480,7 @@ const SchemaProperty = ({ name, details, isRequired, level, isListItem = false,
                 <div className="mt-1 border-l border-dashed border-[rgb(var(--ec-page-border))] pl-3 ml-1.5">
                   <span className="text-xs italic text-[rgb(var(--ec-page-text-muted))] block mb-1">Item Details:</span>
                   {details.items.properties &&
+                    !details.items.variants &&
                     Object.entries(details.items.properties).map(([itemPropName, itemPropDetails]: [string, any]) => (
                       <SchemaProperty
                         key={itemPropName}
@@ -823,7 +842,7 @@ export default function JSONSchemaViewer({
           // Determine which properties to display
           const propsToDisplay =
             variants && variants.length > 0 && variants[selectedVariantIndex]?.properties
-              ? { ...properties, ...variants[selectedVariantIndex].properties }
+              ? variants[selectedVariantIndex].properties
               : properties;
           const requiredProps = variants && variants.length > 0 ? variants[selectedVariantIndex]?.required || [] : required;