From 06b336650bc9a8d7a872e3e42aa69a8961b7abd3 Mon Sep 17 00:00:00 2001
From: platex-rehor-bot <platform-experience-services@redhat.com>
Date: Thu, 30 Apr 2026 11:14:11 +0000
Subject: [PATCH 1/2] feat(creator): add YAML editor with wizard sync and
 validation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

RHCLOUD-40758
Add Creator YAML editor with bidirectional state sync between
wizard and YAML tabs, schema validation, metadata file creation,
and file load/download support.

- Wizard → YAML: switching to YAML tab serializes current wizard
  state (spec, bundles, tags) into the editor
- YAML → Wizard: switching back populates wizard form fields from
  shared state via initialValues
- Kind detection: extracts ItemKind from spec.type.text, propagates
  to parent for correct metadata generation
- Schema validation: warns on missing required fields, unknown tag
  kinds, unknown spec fields, and unrecognized types
- File operations: Load from File, Load Sample Template, Download
  Files (uses parent-generated files for consistency with wizard)
- Sample template updated with metadata tags (bundle, content)
- 27 unit tests covering sync, validation, and file operations

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 jest.config.js                                |   2 +-
 src/Creator.tsx                               |   5 +
 src/components/creator/CreatorWizard.tsx      |  43 ++
 .../creator/CreatorYAMLView.test.tsx          | 635 ++++++++++++++++++
 src/components/creator/CreatorYAMLView.tsx    | 382 ++++++++++-
 src/data/quickstart-templates.ts              |   8 +-
 6 files changed, 1050 insertions(+), 25 deletions(-)
 create mode 100644 src/components/creator/CreatorYAMLView.test.tsx

diff --git a/jest.config.js b/jest.config.js
index 4c79597e..718a9993 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -1,4 +1,4 @@
-const transformIgnorePatterns = ['node_modules/(?!(uuid)/)'];
+const transformIgnorePatterns = ['node_modules/(?!(uuid|yaml)/)'];
 
 /** @type {import('ts-jest').JestConfigWithTsJest} */
 module.exports = {
diff --git a/src/Creator.tsx b/src/Creator.tsx
index 87aa5bbc..c205d9e3 100644
--- a/src/Creator.tsx
+++ b/src/Creator.tsx
@@ -238,6 +238,11 @@ const CreatorInternal = ({
               onChangeCurrentStage={setCurrentStage}
               resetCreator={resetCreator}
               files={files}
+              quickStart={quickStart}
+              currentBundles={bundles}
+              currentTags={tags}
+              currentKind={rawKind}
+              onChangeKindDirect={setRawKind}
             />
           </GridItem>
 
diff --git a/src/components/creator/CreatorWizard.tsx b/src/components/creator/CreatorWizard.tsx
index e6c82964..aa5d47cb 100644
--- a/src/components/creator/CreatorWizard.tsx
+++ b/src/components/creator/CreatorWizard.tsx
@@ -36,6 +36,7 @@ import { useChrome } from '@redhat-cloud-services/frontend-components/useChrome'
 import { downloadFile } from '@redhat-cloud-services/frontend-components-utilities/helpers';
 import SimpleButton from '../SimpleButton';
 import DdfNumberInput from '../DdfNumberInput';
+import { ExtendedQuickstart } from '../../utils/fetchQuickstarts';
 import {
   NAME_BUNDLES,
   NAME_DESCRIPTION,
@@ -66,6 +67,11 @@ export type CreatorWizardProps = {
   filterData: FilterData;
   onChangeTags: (tags: { [kind: string]: string[] }) => void;
   onChangeMetadataTags: (tags: Array<{ kind: string; value: string }>) => void;
+  quickStart?: ExtendedQuickstart;
+  currentBundles?: string[];
+  currentTags?: { [kind: string]: string[] };
+  currentKind?: ItemKind | null;
+  onChangeKindDirect?: (kind: ItemKind | null) => void;
 };
 
 type ViewMode = 'wizard' | 'creator';
@@ -312,11 +318,43 @@ const CreatorWizard = ({
   onChangeMetadataTags,
   files,
   filterData,
+  quickStart,
+  currentBundles,
+  currentTags,
+  currentKind,
+  onChangeKindDirect,
 }: CreatorWizardProps) => {
   const chrome = useChrome();
   const [viewMode, setViewMode] = useState<ViewMode>('wizard');
   const schema = useMemo(() => makeSchema(chrome, filterData), []);
 
+  // Derive initialValues from shared state so wizard ↔ YAML stays in sync.
+  // FormRenderer is conditionally rendered (unmounted in YAML mode), so it
+  // picks up fresh initialValues each time the user switches back to wizard.
+  const initialValues = useMemo(() => {
+    if (!quickStart) return undefined;
+    return {
+      [NAME_KIND]: currentKind || undefined,
+      [NAME_BUNDLES]: currentBundles,
+      [NAME_TAGS]: currentTags,
+      [NAME_TITLE]: quickStart.spec.displayName || '',
+      [NAME_DESCRIPTION]: quickStart.spec.description || '',
+      [NAME_DURATION]: quickStart.spec.durationMinutes,
+      [NAME_URL]: quickStart.spec.link?.href,
+      [NAME_PREREQUISITES]: quickStart.spec.prerequisites,
+      [NAME_PANEL_INTRODUCTION]: quickStart.spec.introduction,
+      [NAME_TASK_TITLES]: quickStart.spec.tasks?.map((t) => t.title || '') || [
+        '',
+      ],
+      [NAME_TASKS_ARRAY]: quickStart.spec.tasks?.map((t) => ({
+        description: t.description,
+        enable_work_check: !!t.review,
+        work_check_instructions: t.review?.instructions,
+        work_check_help: t.review?.failedTaskHelp,
+      })),
+    };
+  }, [quickStart, currentKind, currentBundles, currentTags]);
+
   // Update stage when switching to creator mode to show preview
   const handleViewModeChange = (newMode: ViewMode) => {
     setViewMode(newMode);
@@ -368,6 +406,7 @@ const CreatorWizard = ({
         <FormRenderer
           onSubmit={() => {}}
           schema={schema}
+          initialValues={initialValues}
           componentMapper={componentMapper}
         >
           {({ formFields }) => (
@@ -409,6 +448,10 @@ const CreatorWizard = ({
           onChangeBundles={onChangeBundles}
           onChangeTags={onChangeTags}
           onChangeMetadataTags={onChangeMetadataTags}
+          onChangeKind={onChangeKindDirect}
+          quickStart={quickStart}
+          currentBundles={currentBundles}
+          currentTags={currentTags}
         />
       )}
     </CreatorWizardContext.Provider>
diff --git a/src/components/creator/CreatorYAMLView.test.tsx b/src/components/creator/CreatorYAMLView.test.tsx
new file mode 100644
index 00000000..93b1fc43
--- /dev/null
+++ b/src/components/creator/CreatorYAMLView.test.tsx
@@ -0,0 +1,635 @@
+import React from 'react';
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import CreatorYAMLView from './CreatorYAMLView';
+import { CreatorWizardContext } from './context';
+import { CreatorFiles } from './types';
+import { DEFAULT_QUICKSTART_YAML } from '../../data/quickstart-templates';
+import { ExtendedQuickstart } from '../../utils/fetchQuickstarts';
+
+// Mock downloadFile from frontend-components-utilities
+const mockDownloadFile = jest.fn();
+jest.mock(
+  '@redhat-cloud-services/frontend-components-utilities/helpers',
+  () => ({
+    downloadFile: (...args: unknown[]) => mockDownloadFile(...args),
+  })
+);
+
+// Mock Monaco Editor — render a simple textarea that mirrors onChange behavior
+jest.mock('@monaco-editor/react', () => {
+  const MockEditor = ({
+    value,
+    onChange,
+  }: {
+    value: string;
+    onChange: (value: string | undefined) => void;
+  }) => (
+    <textarea
+      data-testid="mock-monaco-editor"
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+    />
+  );
+  MockEditor.displayName = 'MockEditor';
+  return { __esModule: true, default: MockEditor };
+});
+
+const MOCK_FILES: CreatorFiles = [
+  { name: 'metadata.yaml', content: 'kind: QuickStarts\nname: test\n' },
+  { name: 'test.yaml', content: 'spec:\n  displayName: Test\n' },
+];
+
+const MOCK_QUICKSTART: ExtendedQuickstart = {
+  metadata: {
+    name: 'my-quickstart',
+    tags: [
+      { kind: 'bundle', value: 'insights' },
+      { kind: 'content', value: 'quickstart' },
+    ],
+  },
+  spec: {
+    displayName: 'My Quick Start',
+    description: 'A sample quickstart for testing',
+    icon: null,
+    type: { text: 'Quick start', color: 'green' },
+    durationMinutes: 10,
+    tasks: [
+      {
+        title: 'First Task',
+        description: 'Do something',
+        review: {
+          instructions: 'Check it worked',
+          failedTaskHelp: 'Try again',
+        },
+      },
+    ],
+  },
+};
+
+const renderWithContext = (
+  ui: React.ReactElement,
+  files: CreatorFiles = MOCK_FILES
+) => {
+  return render(
+    <CreatorWizardContext.Provider
+      value={{
+        files,
+        onChangeCurrentStage: jest.fn(),
+        resetCreator: jest.fn(),
+      }}
+    >
+      {ui}
+    </CreatorWizardContext.Provider>
+  );
+};
+
+describe('CreatorYAMLView', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+    mockDownloadFile.mockClear();
+  });
+
+  it('renders both toolbar buttons', () => {
+    renderWithContext(<CreatorYAMLView />);
+    expect(
+      screen.getByRole('button', { name: /load sample template/i })
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', { name: /load from file/i })
+    ).toBeInTheDocument();
+  });
+
+  it('renders hidden file input with correct accept attribute', () => {
+    renderWithContext(<CreatorYAMLView />);
+    const fileInput = screen.getByTestId('yaml-file-input');
+    expect(fileInput).toHaveAttribute('type', 'file');
+    expect(fileInput).toHaveAttribute('accept', '.yaml,.yml');
+    expect(fileInput).not.toBeVisible();
+  });
+
+  describe('Wizard-to-YAML sync', () => {
+    it('initializes editor with serialized wizard state when quickStart has data', () => {
+      renderWithContext(
+        <CreatorYAMLView
+          quickStart={MOCK_QUICKSTART}
+          currentBundles={['insights']}
+          currentTags={{ content: ['quickstart'] }}
+        />
+      );
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      const content = (editor as HTMLTextAreaElement).value;
+
+      expect(content).toContain('displayName: My Quick Start');
+      expect(content).toContain('description: A sample quickstart for testing');
+      expect(content).toContain('durationMinutes: 10');
+      expect(content).toContain('value: insights');
+      expect(content).toContain('value: quickstart');
+    });
+
+    it('shows placeholder when quickStart has no displayName', () => {
+      const emptyQS: ExtendedQuickstart = {
+        metadata: { name: 'test', tags: [] },
+        spec: { displayName: '', icon: null, description: '' },
+      };
+      renderWithContext(<CreatorYAMLView quickStart={emptyQS} />);
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      expect((editor as HTMLTextAreaElement).value).toContain(
+        '# YAML Quickstart Definition'
+      );
+    });
+
+    it('calls onChangeKind when YAML has a recognized spec.type', async () => {
+      const onChangeKind = jest.fn();
+      renderWithContext(<CreatorYAMLView onChangeKind={onChangeKind} />);
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: {
+          value:
+            'metadata:\n  name: test\nspec:\n  displayName: Test\n  type:\n    text: Documentation\n    color: orange\n',
+        },
+      });
+
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+
+      await waitFor(() => {
+        expect(onChangeKind).toHaveBeenCalledWith('documentation');
+      });
+    });
+
+    it('calls onChangeKind with null for unknown type', async () => {
+      const onChangeKind = jest.fn();
+      renderWithContext(<CreatorYAMLView onChangeKind={onChangeKind} />);
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: {
+          value:
+            'metadata:\n  name: test\nspec:\n  displayName: Test\n  type:\n    text: Unknown Type\n',
+        },
+      });
+
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+
+      await waitFor(() => {
+        expect(onChangeKind).toHaveBeenCalledWith(null);
+      });
+    });
+  });
+
+  describe('Validation', () => {
+    it('shows validation warnings for missing required fields', async () => {
+      renderWithContext(<CreatorYAMLView />);
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: { value: 'spec:\n  version: 1\n' },
+      });
+
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+
+      await waitFor(() => {
+        expect(screen.getByText(/Schema Validation/i)).toBeInTheDocument();
+      });
+      expect(screen.getByText(/metadata\.name/)).toBeInTheDocument();
+      expect(screen.getByText(/spec\.displayName/)).toBeInTheDocument();
+      expect(screen.getByText(/spec\.description/)).toBeInTheDocument();
+    });
+
+    it('shows warning for unknown tag kind', async () => {
+      renderWithContext(<CreatorYAMLView />);
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: {
+          value:
+            'metadata:\n  name: test\n  tags:\n    - kind: invalid-kind\n      value: foo\nspec:\n  displayName: Test\n  description: Desc\n',
+        },
+      });
+
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+
+      await waitFor(() => {
+        expect(screen.getByText(/Unknown tag kind/)).toBeInTheDocument();
+      });
+    });
+
+    it('shows warning for unknown spec fields', async () => {
+      renderWithContext(<CreatorYAMLView />);
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: {
+          value:
+            'metadata:\n  name: test\nspec:\n  displayName: Test\n  description: Desc\n  customField: value\n',
+        },
+      });
+
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+
+      await waitFor(() => {
+        expect(screen.getByText(/spec\.customField/)).toBeInTheDocument();
+        expect(screen.getByText(/Unknown field/)).toBeInTheDocument();
+      });
+    });
+
+    it('shows no warnings for valid YAML', async () => {
+      renderWithContext(<CreatorYAMLView />);
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: {
+          value:
+            'metadata:\n  name: test\n  tags:\n    - kind: bundle\n      value: insights\nspec:\n  displayName: Test\n  description: Desc\n',
+        },
+      });
+
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+
+      await waitFor(() => {
+        expect(
+          screen.queryByText(/Schema Validation/i)
+        ).not.toBeInTheDocument();
+      });
+    });
+  });
+
+  describe('Load Sample Template', () => {
+    it('loads sample YAML into editor without confirm when content is placeholder', () => {
+      const confirmSpy = jest.spyOn(window, 'confirm');
+      renderWithContext(<CreatorYAMLView />);
+
+      fireEvent.click(
+        screen.getByRole('button', { name: /load sample template/i })
+      );
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      expect(editor).toHaveValue(DEFAULT_QUICKSTART_YAML);
+      expect(confirmSpy).not.toHaveBeenCalled();
+    });
+
+    it('shows confirmation when editor has user content', () => {
+      const confirmSpy = jest.spyOn(window, 'confirm').mockReturnValue(false);
+      renderWithContext(<CreatorYAMLView />);
+
+      // Type real content to make the editor "dirty"
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: { value: 'metadata:\n  name: test\n' },
+      });
+
+      fireEvent.click(
+        screen.getByRole('button', { name: /load sample template/i })
+      );
+
+      expect(confirmSpy).toHaveBeenCalledWith(
+        'This will overwrite your current work. Are you sure?'
+      );
+    });
+  });
+
+  describe('Load from File', () => {
+    it('opens file picker without confirm when content is placeholder', () => {
+      const confirmSpy = jest.spyOn(window, 'confirm');
+      renderWithContext(<CreatorYAMLView />);
+      const fileInput = screen.getByTestId('yaml-file-input');
+      const clickSpy = jest.spyOn(fileInput, 'click');
+
+      fireEvent.click(screen.getByRole('button', { name: /load from file/i }));
+
+      expect(confirmSpy).not.toHaveBeenCalled();
+      expect(clickSpy).toHaveBeenCalled();
+    });
+
+    it('opens file picker after user confirms overwrite of real content', () => {
+      jest.spyOn(window, 'confirm').mockReturnValue(true);
+      renderWithContext(<CreatorYAMLView />);
+      const fileInput = screen.getByTestId('yaml-file-input');
+      const clickSpy = jest.spyOn(fileInput, 'click');
+
+      // Type real content first
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: { value: 'metadata:\n  name: test\n' },
+      });
+
+      fireEvent.click(screen.getByRole('button', { name: /load from file/i }));
+
+      expect(clickSpy).toHaveBeenCalled();
+    });
+
+    it('shows confirmation when editor has user content before opening file picker', () => {
+      const confirmSpy = jest.spyOn(window, 'confirm').mockReturnValue(false);
+      renderWithContext(<CreatorYAMLView />);
+
+      // Type real content first
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: { value: 'metadata:\n  name: test\n' },
+      });
+
+      fireEvent.click(screen.getByRole('button', { name: /load from file/i }));
+
+      expect(confirmSpy).toHaveBeenCalledWith(
+        'Loading a file will overwrite your current work. Are you sure?'
+      );
+    });
+
+    it('does not open file picker when user cancels confirmation', () => {
+      jest.spyOn(window, 'confirm').mockReturnValue(false);
+      renderWithContext(<CreatorYAMLView />);
+      const fileInput = screen.getByTestId('yaml-file-input');
+      const clickSpy = jest.spyOn(fileInput, 'click');
+
+      // Type real content first
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: { value: 'metadata:\n  name: test\n' },
+      });
+
+      fireEvent.click(screen.getByRole('button', { name: /load from file/i }));
+
+      expect(clickSpy).not.toHaveBeenCalled();
+    });
+
+    it('loads selected YAML file into editor and triggers parse', async () => {
+      const yamlContent = `metadata:\n  name: test-qs\nspec:\n  displayName: Test QS\n`;
+      const mockFile = new File([yamlContent], 'test.yaml', {
+        type: 'application/x-yaml',
+      });
+
+      const onChangeSpec = jest.fn();
+      renderWithContext(
+        <CreatorYAMLView onChangeQuickStartSpec={onChangeSpec} />
+      );
+
+      const fileInput = screen.getByTestId('yaml-file-input');
+      fireEvent.change(fileInput, { target: { files: [mockFile] } });
+
+      await waitFor(() => {
+        const editor = screen.getByTestId('mock-monaco-editor');
+        expect(editor).toHaveValue(yamlContent);
+      });
+
+      await waitFor(() => {
+        expect(onChangeSpec).toHaveBeenCalledWith(
+          expect.objectContaining({ displayName: 'Test QS' })
+        );
+      });
+    });
+
+    it('calls onChangeBundles and onChangeTags for tagged YAML', async () => {
+      const yamlContent = `metadata:
+  name: tagged-qs
+  tags:
+    - kind: bundle
+      value: insights
+    - kind: content
+      value: quickstart
+spec:
+  displayName: Tagged QS
+`;
+      const mockFile = new File([yamlContent], 'tagged.yaml', {
+        type: 'application/x-yaml',
+      });
+
+      const onChangeBundles = jest.fn();
+      const onChangeTags = jest.fn();
+      renderWithContext(
+        <CreatorYAMLView
+          onChangeBundles={onChangeBundles}
+          onChangeTags={onChangeTags}
+        />
+      );
+
+      const fileInput = screen.getByTestId('yaml-file-input');
+      fireEvent.change(fileInput, { target: { files: [mockFile] } });
+
+      await waitFor(() => {
+        expect(onChangeBundles).toHaveBeenCalledWith(['insights']);
+      });
+
+      await waitFor(() => {
+        expect(onChangeTags).toHaveBeenCalledWith({
+          content: ['quickstart'],
+        });
+      });
+    });
+
+    it('shows parse error for invalid YAML', async () => {
+      const invalidYaml = `invalid: [unclosed`;
+      const mockFile = new File([invalidYaml], 'bad.yaml', {
+        type: 'application/x-yaml',
+      });
+
+      renderWithContext(<CreatorYAMLView />);
+
+      const fileInput = screen.getByTestId('yaml-file-input');
+      fireEvent.change(fileInput, { target: { files: [mockFile] } });
+
+      await waitFor(() => {
+        expect(screen.getByText(/YAML Parse Error/i)).toBeInTheDocument();
+      });
+      // Also verify the dynamic parser message is surfaced
+      await waitFor(() => {
+        expect(
+          screen.getByText(/Showing previous valid state in preview/i)
+        ).toBeInTheDocument();
+      });
+    });
+
+    it('shows error when FileReader fails', async () => {
+      const mockFile = new File(['content'], 'test.yaml', {
+        type: 'application/x-yaml',
+      });
+
+      // Mock FileReader to simulate error
+      const originalFileReader = global.FileReader;
+      const mockReader = {
+        readAsText: jest.fn(),
+        onerror: null as (() => void) | null,
+        onload: null as ((e: unknown) => void) | null,
+        error: { message: 'Permission denied' },
+      };
+      global.FileReader = jest.fn(
+        () => mockReader
+      ) as unknown as typeof FileReader;
+
+      renderWithContext(<CreatorYAMLView />);
+
+      const fileInput = screen.getByTestId('yaml-file-input');
+      fireEvent.change(fileInput, { target: { files: [mockFile] } });
+
+      // Trigger the error callback
+      act(() => {
+        mockReader.onerror?.();
+      });
+
+      await waitFor(() => {
+        expect(
+          screen.getByText(/Failed to read file: Permission denied/i)
+        ).toBeInTheDocument();
+      });
+
+      global.FileReader = originalFileReader;
+    });
+
+    it('does nothing when no file is selected', () => {
+      const confirmSpy = jest.spyOn(window, 'confirm');
+      const onChangeSpec = jest.fn();
+      renderWithContext(
+        <CreatorYAMLView onChangeQuickStartSpec={onChangeSpec} />
+      );
+
+      const fileInput = screen.getByTestId('yaml-file-input');
+      fireEvent.change(fileInput, { target: { files: [] } });
+
+      expect(onChangeSpec).not.toHaveBeenCalled();
+      expect(confirmSpy).not.toHaveBeenCalled();
+      expect(screen.queryByText(/YAML Parse Error/i)).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Download Files', () => {
+    it('renders download button', () => {
+      renderWithContext(<CreatorYAMLView />);
+      expect(
+        screen.getByRole('button', { name: /download files/i })
+      ).toBeInTheDocument();
+    });
+
+    it('disables download button when editor has placeholder content', () => {
+      renderWithContext(<CreatorYAMLView />);
+      const downloadBtn = screen.getByRole('button', {
+        name: /download files/i,
+      });
+      expect(downloadBtn).toBeDisabled();
+    });
+
+    it('enables download button after loading valid YAML', () => {
+      renderWithContext(<CreatorYAMLView />);
+      const editor = screen.getByTestId('mock-monaco-editor');
+
+      fireEvent.change(editor, {
+        target: {
+          value: `metadata:\n  name: test-qs\nspec:\n  displayName: Test\n`,
+        },
+      });
+
+      // Flush debounce to clear parseError
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+
+      const downloadBtn = screen.getByRole('button', {
+        name: /download files/i,
+      });
+      expect(downloadBtn).not.toBeDisabled();
+    });
+
+    it('downloads files from context (generated by parent)', () => {
+      renderWithContext(<CreatorYAMLView />);
+      const editor = screen.getByTestId('mock-monaco-editor');
+
+      // Type valid YAML to enable download
+      fireEvent.change(editor, {
+        target: {
+          value: `metadata:\n  name: test\nspec:\n  displayName: Test\n`,
+        },
+      });
+
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+
+      const downloadBtn = screen.getByRole('button', {
+        name: /download files/i,
+      });
+      fireEvent.click(downloadBtn);
+
+      // Downloads the mock context files, not editor content directly
+      expect(mockDownloadFile).toHaveBeenCalledTimes(2);
+      expect(mockDownloadFile).toHaveBeenCalledWith(
+        'kind: QuickStarts\nname: test\n',
+        'metadata',
+        'yaml'
+      );
+      expect(mockDownloadFile).toHaveBeenCalledWith(
+        'spec:\n  displayName: Test\n',
+        'test',
+        'yaml'
+      );
+    });
+
+    it('disables download button when YAML has parse error', () => {
+      renderWithContext(<CreatorYAMLView />);
+      const editor = screen.getByTestId('mock-monaco-editor');
+
+      fireEvent.change(editor, {
+        target: { value: 'invalid: [unclosed' },
+      });
+
+      // Flush debounce to trigger parse error
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+
+      const downloadBtn = screen.getByRole('button', {
+        name: /download files/i,
+      });
+      expect(downloadBtn).toBeDisabled();
+    });
+  });
+
+  describe('editor onChange', () => {
+    it('debounces parse updates', () => {
+      const onChangeSpec = jest.fn();
+      renderWithContext(
+        <CreatorYAMLView onChangeQuickStartSpec={onChangeSpec} />
+      );
+
+      const editor = screen.getByTestId('mock-monaco-editor');
+      fireEvent.change(editor, {
+        target: {
+          value: `metadata:\n  name: debounce-test\nspec:\n  displayName: Debounce\n`,
+        },
+      });
+
+      // Should not be called immediately
+      expect(onChangeSpec).not.toHaveBeenCalled();
+
+      // After debounce timer fires
+      act(() => {
+        jest.advanceTimersByTime(200);
+      });
+      expect(onChangeSpec).toHaveBeenCalledWith(
+        expect.objectContaining({ displayName: 'Debounce' })
+      );
+    });
+  });
+});
diff --git a/src/components/creator/CreatorYAMLView.tsx b/src/components/creator/CreatorYAMLView.tsx
index d5dfe938..ab0fd576 100644
--- a/src/components/creator/CreatorYAMLView.tsx
+++ b/src/components/creator/CreatorYAMLView.tsx
@@ -1,24 +1,232 @@
-import React, { useEffect, useRef, useState } from 'react';
+import React, { useContext, useEffect, useRef, useState } from 'react';
 import {
   Alert,
   Button,
   Flex,
   FlexItem,
+  List,
+  ListItem,
   PageSection,
+  Tooltip,
 } from '@patternfly/react-core';
-import { FileImportIcon } from '@patternfly/react-icons';
+import {
+  DownloadIcon,
+  FileImportIcon,
+  UploadIcon,
+} from '@patternfly/react-icons';
 import Editor from '@monaco-editor/react';
 import YAML from 'yaml';
 import { QuickStartSpec } from '@patternfly/quickstarts';
+import { downloadFile } from '@redhat-cloud-services/frontend-components-utilities/helpers';
 import { ExtendedQuickstart } from '../../utils/fetchQuickstarts';
+import { CreatorWizardContext } from './context';
+import { ALL_KIND_ENTRIES, ItemKind } from './meta';
 import './CreatorYAMLView.scss';
 import { DEFAULT_QUICKSTART_YAML } from '../../data/quickstart-templates';
 
+const PLACEHOLDER_YAML =
+  '# YAML Quickstart Definition\n# Start typing or paste your YAML here\n';
+
+const isUserContent = (content: string): boolean => {
+  const trimmed = content.trim();
+  return trimmed !== '' && content !== PLACEHOLDER_YAML;
+};
+
+/**
+ * Detect ItemKind from spec.type.text by matching against known display names.
+ */
+function detectKind(
+  spec: Record<string, unknown> | undefined
+): ItemKind | null {
+  const typeObj = spec?.type as Record<string, unknown> | undefined;
+  const typeText = typeObj?.text;
+  if (typeof typeText !== 'string') return null;
+
+  for (const [kind, meta] of ALL_KIND_ENTRIES) {
+    if (meta.displayName.toLowerCase() === typeText.toLowerCase()) {
+      return kind;
+    }
+  }
+  return null;
+}
+
+type ValidationWarning = { field: string; message: string };
+
+const VALID_TAG_KINDS = new Set([
+  'bundle',
+  'content',
+  'use-case',
+  'product-families',
+]);
+
+const VALID_SPEC_FIELDS = new Set([
+  'displayName',
+  'description',
+  'icon',
+  'type',
+  'durationMinutes',
+  'link',
+  'prerequisites',
+  'introduction',
+  'tasks',
+  'version',
+]);
+
+/**
+ * Validate parsed YAML against the QuickStart schema.
+ * Returns an array of warnings (non-blocking).
+ */
+function validateQuickstartYaml(
+  parsed: Record<string, unknown>
+): ValidationWarning[] {
+  const warnings: ValidationWarning[] = [];
+  const metadata = parsed.metadata as Record<string, unknown> | undefined;
+  const spec = parsed.spec as Record<string, unknown> | undefined;
+
+  if (!metadata?.name) {
+    warnings.push({
+      field: 'metadata.name',
+      message: 'Required — used as file name and identifier',
+    });
+  }
+
+  if (!spec?.displayName) {
+    warnings.push({
+      field: 'spec.displayName',
+      message: 'Required — title shown on the card',
+    });
+  }
+
+  if (!spec?.description) {
+    warnings.push({
+      field: 'spec.description',
+      message: 'Required — card description text',
+    });
+  }
+
+  // Validate tag kinds
+  if (metadata && Array.isArray(metadata.tags)) {
+    (metadata.tags as Array<{ kind?: string; value?: string }>).forEach(
+      (tag, i) => {
+        if (tag.kind && !VALID_TAG_KINDS.has(tag.kind)) {
+          warnings.push({
+            field: `metadata.tags[${i}].kind`,
+            message: `Unknown tag kind "${tag.kind}". Supported: ${[
+              ...VALID_TAG_KINDS,
+            ].join(', ')}`,
+          });
+        }
+        if (!tag.value) {
+          warnings.push({
+            field: `metadata.tags[${i}].value`,
+            message: 'Tag value is required',
+          });
+        }
+      }
+    );
+  }
+
+  // Validate spec fields
+  if (spec) {
+    Object.keys(spec).forEach((key) => {
+      if (!VALID_SPEC_FIELDS.has(key)) {
+        warnings.push({
+          field: `spec.${key}`,
+          message: `Unknown field — may be ignored`,
+        });
+      }
+    });
+  }
+
+  // Validate kind/type
+  const kind = detectKind(spec);
+  if (spec?.type && !kind) {
+    const typeObj = spec.type as Record<string, unknown>;
+    warnings.push({
+      field: 'spec.type.text',
+      message: `Unknown type "${
+        typeObj?.text
+      }". Supported: ${ALL_KIND_ENTRIES.map(([, m]) => m.displayName).join(
+        ', '
+      )}`,
+    });
+  }
+
+  return warnings;
+}
+
+/**
+ * Serialize current QuickStart state to a YAML string for the editor.
+ */
+function serializeToYaml(
+  quickStart: ExtendedQuickstart,
+  bundles: string[],
+  tags: { [kind: string]: string[] }
+): string {
+  const allTags: Array<{ kind: string; value: string }> = bundles
+    .toSorted()
+    .map((b) => ({ kind: 'bundle', value: b }));
+  Object.entries(tags).forEach(([kind, values]) => {
+    values.forEach((value) => allTags.push({ kind, value }));
+  });
+
+  // Build document matching the expected YAML structure
+  const doc: Record<string, unknown> = {
+    kind: 'QuickStarts',
+    metadata: {
+      name: quickStart.metadata.name || 'untitled-quickstart',
+      ...(allTags.length > 0 ? { tags: allTags } : {}),
+    },
+    spec: {
+      ...(quickStart.spec.displayName
+        ? { displayName: quickStart.spec.displayName }
+        : {}),
+      ...(quickStart.spec.description
+        ? { description: quickStart.spec.description }
+        : {}),
+      ...(quickStart.spec.durationMinutes !== undefined
+        ? { durationMinutes: quickStart.spec.durationMinutes }
+        : {}),
+      ...(quickStart.spec.type
+        ? {
+            type: {
+              text: quickStart.spec.type.text,
+              color: quickStart.spec.type.color,
+            },
+          }
+        : {}),
+      ...(quickStart.spec.link
+        ? {
+            link: {
+              text: quickStart.spec.link.text,
+              href: quickStart.spec.link.href,
+            },
+          }
+        : {}),
+      ...(quickStart.spec.prerequisites?.length
+        ? { prerequisites: quickStart.spec.prerequisites }
+        : {}),
+      ...(quickStart.spec.introduction
+        ? { introduction: quickStart.spec.introduction }
+        : {}),
+      ...(quickStart.spec.tasks?.length
+        ? { tasks: quickStart.spec.tasks }
+        : {}),
+    },
+  };
+
+  return YAML.stringify(doc, { lineWidth: 0 });
+}
+
 export type CreatorYAMLViewProps = {
   onChangeQuickStartSpec?: (newValue: QuickStartSpec) => void;
   onChangeBundles?: (newValue: string[]) => void;
   onChangeTags?: (tags: { [kind: string]: string[] }) => void;
   onChangeMetadataTags?: (tags: Array<{ kind: string; value: string }>) => void;
+  onChangeKind?: (kind: ItemKind | null) => void;
+  quickStart?: ExtendedQuickstart;
+  currentBundles?: string[];
+  currentTags?: { [kind: string]: string[] };
 };
 
 const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
@@ -26,13 +234,37 @@ const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
   onChangeBundles,
   onChangeTags,
   onChangeMetadataTags,
+  onChangeKind,
+  quickStart,
+  currentBundles,
+  currentTags,
 }) => {
-  const [yamlContent, setYamlContent] = useState<string>(
-    '# YAML Quickstart Definition\n# Start typing or paste your YAML here\n'
-  );
+  const { files } = useContext(CreatorWizardContext);
+
+  // On mount, serialize current state to YAML if we have data from the wizard.
+  // This enables switching wizard → YAML without losing data.
+  const getInitialYaml = (): string => {
+    if (
+      quickStart?.spec.displayName &&
+      quickStart.spec.displayName.length > 0
+    ) {
+      return serializeToYaml(
+        quickStart,
+        currentBundles || [],
+        currentTags || {}
+      );
+    }
+    return PLACEHOLDER_YAML;
+  };
+
+  const [yamlContent, setYamlContent] = useState<string>(getInitialYaml);
   const [parseError, setParseError] = useState<string | null>(null);
+  const [validationWarnings, setValidationWarnings] = useState<
+    ValidationWarning[]
+  >([]);
 
   const debounceTimerRef = useRef<NodeJS.Timeout | null>(null);
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
 
   const configureMonacoEnvironment = () => {
     // Disable Monaco workers to prevent CDN fetching in CI environments
@@ -53,15 +285,20 @@ const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
 
       if (!parsed) {
         setParseError('Empty YAML content');
+        setValidationWarnings([]);
         return;
       }
 
+      // Validate structure
+      const warnings = validateQuickstartYaml(parsed);
+      setValidationWarnings(warnings);
+
       // Extract metadata
       const metadata = parsed.metadata || {};
       const spec = parsed.spec || {};
 
       // Build the quickstart object
-      const quickstart: ExtendedQuickstart = {
+      const quickstartObj: ExtendedQuickstart = {
         metadata: {
           name: metadata.name || 'untitled-quickstart',
           tags: metadata.tags || [],
@@ -82,6 +319,12 @@ const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
       // Update state
       setParseError(null);
 
+      // Detect and propagate kind from spec.type
+      const detectedKind = detectKind(spec);
+      if (onChangeKind) {
+        onChangeKind(detectedKind);
+      }
+
       // Extract bundles and tags
       const bundles: string[] = [];
       const tagsByKind: { [kind: string]: string[] } = {};
@@ -100,10 +343,6 @@ const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
       }
 
       // Call the callbacks with updated data
-      // NOTE: We don't call onChangeKind here because in YAML mode, the kind info
-      // is already embedded in the spec (spec.type). Calling onChangeKind would
-      // trigger wizard-mode logic that overwrites our YAML values with defaults.
-      // The spec.type already contains the kind information for the preview.
       if (onChangeBundles) {
         onChangeBundles(bundles);
       }
@@ -115,12 +354,13 @@ const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
         onChangeMetadataTags(metadata.tags || []);
       }
       if (onChangeQuickStartSpec) {
-        onChangeQuickStartSpec(quickstart.spec);
+        onChangeQuickStartSpec(quickstartObj.spec);
       }
     } catch (error) {
       const errorMessage =
         error instanceof Error ? error.message : 'Invalid YAML syntax';
       setParseError(errorMessage);
+      setValidationWarnings([]);
       // Keep using the last valid quickstart state on error
     }
   };
@@ -149,23 +389,71 @@ const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
     };
   }, []);
 
-  const handleLoadSample = () => {
-    const currentContent = yamlContent.trim();
+  const confirmOverwriteIfDirty = (message: string): boolean => {
+    if (!isUserContent(yamlContent)) return true;
+    return window.confirm(message);
+  };
 
-    // If content exists and is not empty, confirm before overwriting
-    if (currentContent && currentContent !== '') {
-      const confirmed = window.confirm(
+  const handleLoadSample = () => {
+    if (
+      !confirmOverwriteIfDirty(
         'This will overwrite your current work. Are you sure?'
-      );
-      if (!confirmed) {
-        return;
-      }
-    }
-
+      )
+    )
+      return;
     setYamlContent(DEFAULT_QUICKSTART_YAML);
     parseAndUpdateQuickstart(DEFAULT_QUICKSTART_YAML);
   };
 
+  const handleLoadFromFile = () => {
+    if (
+      !confirmOverwriteIfDirty(
+        'Loading a file will overwrite your current work. Are you sure?'
+      )
+    )
+      return;
+    fileInputRef.current?.click();
+  };
+
+  const handleFileSelected = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0];
+    if (!file) {
+      return;
+    }
+
+    const reader = new FileReader();
+    reader.onload = (e) => {
+      const content = e.target?.result;
+      if (typeof content === 'string') {
+        setYamlContent(content);
+        parseAndUpdateQuickstart(content);
+      }
+    };
+    reader.onerror = () => {
+      setParseError(
+        `Failed to read file: ${reader.error?.message ?? 'unknown error'}`
+      );
+    };
+    reader.readAsText(file);
+
+    // Reset file input so the same file can be re-selected
+    event.target.value = '';
+  };
+
+  const handleDownload = () => {
+    files.forEach((file) => {
+      const dotIndex = file.name.lastIndexOf('.');
+      const baseName =
+        dotIndex !== -1 ? file.name.substring(0, dotIndex) : file.name;
+      const extension =
+        dotIndex !== -1 ? file.name.substring(dotIndex + 1) : 'txt';
+      downloadFile(file.content, baseName, extension);
+    });
+  };
+
+  const canDownload =
+    isUserContent(yamlContent) && !parseError && files.length > 0;
+
   return (
     <PageSection className="lr-c-creator-yaml-view">
       {parseError && (
@@ -178,6 +466,22 @@ const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
           {parseError}. Showing previous valid state in preview.
         </Alert>
       )}
+      {validationWarnings.length > 0 && !parseError && (
+        <Alert
+          variant="info"
+          title="Schema Validation"
+          className="pf-v6-u-mb-md"
+          isInline
+        >
+          <List>
+            {validationWarnings.map((w, i) => (
+              <ListItem key={i}>
+                <strong>{w.field}</strong>: {w.message}
+              </ListItem>
+            ))}
+          </List>
+        </Alert>
+      )}
       <Flex
         spaceItems={{ default: 'spaceItemsSm' }}
         className="lr-c-creator-yaml-view__toolbar"
@@ -192,6 +496,40 @@ const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
             Load Sample Template
           </Button>
         </FlexItem>
+        <FlexItem>
+          <Button
+            variant="secondary"
+            icon={<UploadIcon />}
+            onClick={handleLoadFromFile}
+            size="sm"
+          >
+            Load from File
+          </Button>
+          <input
+            ref={fileInputRef}
+            type="file"
+            accept=".yaml,.yml"
+            onChange={handleFileSelected}
+            style={{ display: 'none' }}
+            data-testid="yaml-file-input"
+          />
+        </FlexItem>
+        <FlexItem>
+          <Tooltip
+            content="Download metadata.yaml and quickstart YAML files, same as wizard"
+            position="top"
+          >
+            <Button
+              variant="primary"
+              icon={<DownloadIcon />}
+              onClick={handleDownload}
+              size="sm"
+              isDisabled={!canDownload}
+            >
+              Download Files ({files.length})
+            </Button>
+          </Tooltip>
+        </FlexItem>
       </Flex>
       <div className="lr-c-creator-yaml-view__editor">
         <Editor
diff --git a/src/data/quickstart-templates.ts b/src/data/quickstart-templates.ts
index c7422770..c356a9a4 100644
--- a/src/data/quickstart-templates.ts
+++ b/src/data/quickstart-templates.ts
@@ -1,7 +1,11 @@
-export const DEFAULT_QUICKSTART_YAML = `apiVersion: console.openshift.io/v1
-kind: QuickStarts
+export const DEFAULT_QUICKSTART_YAML = `kind: QuickStarts
 metadata:
   name: sample-interactive-quickstart
+  tags:
+    - kind: bundle
+      value: insights
+    - kind: content
+      value: quickstart
 spec:
   version: 0.1
   displayName: Sample Interactive QuickStart

From 855242ddc0522fa757830e98a75924a2c9a17e2f Mon Sep 17 00:00:00 2001
From: platex-rehor-bot <platform-experience-services@redhat.com>
Date: Thu, 30 Apr 2026 11:22:56 +0000
Subject: [PATCH 2/2] fix(creator): normalize kind matching and broaden wizard
 data detection

RHCLOUD-40758
- detectKind() now normalizes whitespace so "Quick start" matches "Quickstart"
- getInitialYaml() checks all wizard fields, not just displayName
- Remove incorrect apiVersion assertion from Cypress test
---
 cypress/component/CreatorYAMLView.cy.tsx   |  3 +--
 src/components/creator/CreatorYAMLView.tsx | 22 +++++++++++++++++-----
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/cypress/component/CreatorYAMLView.cy.tsx b/cypress/component/CreatorYAMLView.cy.tsx
index a1dc1fba..b5863db5 100644
--- a/cypress/component/CreatorYAMLView.cy.tsx
+++ b/cypress/component/CreatorYAMLView.cy.tsx
@@ -363,8 +363,7 @@ spec:
       cy.contains('button', 'Load Sample Template').click();
       
       // Wait for Monaco to update and verify key template fields
-      cy.contains('apiVersion: console.openshift.io/v1', { timeout: 5000 }).should('be.visible');
-      cy.contains('kind: QuickStarts').should('be.visible');
+      cy.contains('kind: QuickStarts', { timeout: 5000 }).should('be.visible');
       cy.contains('name: sample-interactive-quickstart').should('be.visible');
       cy.contains('version: 0.1').should('be.visible');
       cy.contains('displayName: Sample Interactive QuickStart').should('be.visible');
diff --git a/src/components/creator/CreatorYAMLView.tsx b/src/components/creator/CreatorYAMLView.tsx
index ab0fd576..d07285c0 100644
--- a/src/components/creator/CreatorYAMLView.tsx
+++ b/src/components/creator/CreatorYAMLView.tsx
@@ -32,8 +32,12 @@ const isUserContent = (content: string): boolean => {
   return trimmed !== '' && content !== PLACEHOLDER_YAML;
 };
 
+const normalizeKindLabel = (value: string) =>
+  value.toLowerCase().replace(/\s+/g, '');
+
 /**
  * Detect ItemKind from spec.type.text by matching against known display names.
+ * Normalizes whitespace so "Quick start" matches "Quickstart", etc.
  */
 function detectKind(
   spec: Record<string, unknown> | undefined
@@ -43,7 +47,7 @@ function detectKind(
   if (typeof typeText !== 'string') return null;
 
   for (const [kind, meta] of ALL_KIND_ENTRIES) {
-    if (meta.displayName.toLowerCase() === typeText.toLowerCase()) {
+    if (normalizeKindLabel(meta.displayName) === normalizeKindLabel(typeText)) {
       return kind;
     }
   }
@@ -244,10 +248,18 @@ const CreatorYAMLView: React.FC<CreatorYAMLViewProps> = ({
   // On mount, serialize current state to YAML if we have data from the wizard.
   // This enables switching wizard → YAML without losing data.
   const getInitialYaml = (): string => {
-    if (
-      quickStart?.spec.displayName &&
-      quickStart.spec.displayName.length > 0
-    ) {
+    const hasWizardData =
+      !!currentBundles?.length ||
+      !!Object.keys(currentTags || {}).length ||
+      !!quickStart?.spec.displayName ||
+      !!quickStart?.spec.description ||
+      quickStart?.spec.durationMinutes !== undefined ||
+      !!quickStart?.spec.link?.href ||
+      !!quickStart?.spec.prerequisites?.length ||
+      !!quickStart?.spec.introduction ||
+      !!quickStart?.spec.tasks?.length;
+
+    if (quickStart && hasWizardData) {
       return serializeToYaml(
         quickStart,
         currentBundles || [],