DirectiveHtmlRenderer.cs

// Licensed to Elasticsearch B.V under one or more agreements.
// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
// See the LICENSE file in the project root for more information

using System;
using System.Diagnostics.CodeAnalysis;
using Elastic.Documentation.AppliesTo;
using Elastic.Markdown.Diagnostics;
using Elastic.Markdown.Helpers;
using Elastic.Markdown.Myst.CodeBlocks;
using Elastic.Markdown.Myst.Directives.Admonition;
using Elastic.Markdown.Myst.Directives.AgentSkill;
using Elastic.Markdown.Myst.Directives.AppliesSwitch;
using Elastic.Markdown.Myst.Directives.Button;
using Elastic.Markdown.Myst.Directives.Changelog;
using Elastic.Markdown.Myst.Directives.CliModifiers;
using Elastic.Markdown.Myst.Directives.CsvInclude;
using Elastic.Markdown.Myst.Directives.Dropdown;
using Elastic.Markdown.Myst.Directives.Image;
using Elastic.Markdown.Myst.Directives.Include;
using Elastic.Markdown.Myst.Directives.Math;
using Elastic.Markdown.Myst.Directives.PageCard;
using Elastic.Markdown.Myst.Directives.Settings;
using Elastic.Markdown.Myst.Directives.Stepper;
using Elastic.Markdown.Myst.Directives.SubPages;
using Elastic.Markdown.Myst.Directives.Table;
using Elastic.Markdown.Myst.Directives.Tabs;
using Elastic.Markdown.Myst.Directives.Version;
using Elastic.Markdown.Myst.InlineParsers.Substitution;
using Elastic.Markdown.Myst.Roles;
using Markdig;
using Markdig.Renderers;
using Markdig.Renderers.Html;
using Markdig.Syntax;
using Markdig.Syntax.Inlines;
using Microsoft.AspNetCore.Html;
using RazorSlices;
using YamlDotNet.Core;

namespace Elastic.Markdown.Myst.Directives;

/// <summary>
/// An HTML renderer for a <see cref="DirectiveBlock"/>.
/// </summary>
/// <seealso cref="HtmlObjectRenderer{CustomContainer}" />
public class DirectiveHtmlRenderer : HtmlObjectRenderer<DirectiveBlock>
{
	protected override void Write(HtmlRenderer renderer, DirectiveBlock directiveBlock)
	{
		_ = renderer.EnsureLine();

		switch (directiveBlock)
		{
			case FigureBlock imageBlock:
				WriteFigure(renderer, imageBlock);
				return;
			case ImageBlock imageBlock:
				WriteImage(renderer, imageBlock);
				return;
			case ImageCarouselBlock carouselBlock:
				WriteImageCarousel(renderer, carouselBlock);
				return;
			case DropdownBlock dropdownBlock:
				WriteDropdown(renderer, dropdownBlock);
				return;
			case AdmonitionBlock admonitionBlock:
				WriteAdmonition(renderer, admonitionBlock);
				return;
			case VersionBlock versionBlock:
				WriteVersion(renderer, versionBlock);
				return;
			case TabSetBlock tabSet:
				WriteTabSet(renderer, tabSet);
				return;
			case TabItemBlock tabItem:
				WriteTabItem(renderer, tabItem);
				return;
			case AppliesSwitchBlock appliesSwitch:
				WriteAppliesSwitch(renderer, appliesSwitch);
				return;
			case AppliesItemBlock appliesItem:
				WriteAppliesItem(renderer, appliesItem);
				return;
			case LiteralIncludeBlock literalIncludeBlock:
				WriteLiteralIncludeBlock(renderer, literalIncludeBlock);
				return;
			case IncludeBlock includeBlock:
				if (includeBlock.Literal)
					WriteLiteralIncludeBlock(renderer, includeBlock);
				else
					WriteIncludeBlock(renderer, includeBlock);
				return;
			case SettingsBlock settingsBlock:
				WriteSettingsBlock(renderer, settingsBlock);
				return;
			case CsvIncludeBlock csvIncludeBlock:
				WriteCsvIncludeBlock(renderer, csvIncludeBlock);
				return;
			case ChangelogBlock changelogBlock:
				WriteChangelogBlock(renderer, changelogBlock);
				return;
			case MathBlock mathBlock:
				WriteMathBlock(renderer, mathBlock);
				return;
			case PageCardBlock pageCardBlock:
				WritePageCard(renderer, pageCardBlock);
				return;
			case StepperBlock stepperBlock:
				WriteStepperBlock(renderer, stepperBlock);
				return;
			case StepBlock stepBlock:
				WriteStepBlock(renderer, stepBlock);
				return;
			case ButtonGroupBlock buttonGroupBlock:
				WriteButtonGroup(renderer, buttonGroupBlock);
				return;
			case ButtonBlock buttonBlock:
				WriteButton(renderer, buttonBlock);
				return;
			case ListSubPagesBlock listSubPagesBlock:
				WriteListSubPages(renderer, listSubPagesBlock);
				return;
			case TableDirectiveBlock tableDirectiveBlock:
				WriteTableDirective(renderer, tableDirectiveBlock);
				return;
			case AgentSkillBlock agentSkillBlock:
				WriteAgentSkill(renderer, agentSkillBlock);
				return;
			case CliModifiersBlock cliModifiersBlock:
				WriteCliModifiers(renderer, cliModifiersBlock);
				return;
			default:
				// if (!string.IsNullOrEmpty(directiveBlock.Info) && !directiveBlock.Info.StartsWith('{'))
				// 	WriteCode(renderer, directiveBlock);
				// else if (!string.IsNullOrEmpty(directiveBlock.Info))
				// 	WriteAdmonition(renderer, directiveBlock);
				// else
				WriteChildren(renderer, directiveBlock);
				break;
		}
	}

	private static void WriteImage(HtmlRenderer renderer, ImageBlock block)
	{
		var imageUrl = block.ImageUrl;

		var slice = ImageView.Create(new ImageViewModel
		{
			DirectiveBlock = block,
			Label = block.Label,
			Align = block.Align,
			Alt = block.Alt ?? string.Empty,
			Title = block.Title,
			Height = block.Height,
			Scale = block.Scale ?? string.Empty,
			Target = block.Target,
			Width = block.Width,
			Screenshot = block.Screenshot,
			ImageUrl = imageUrl,
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteImageCarousel(HtmlRenderer renderer, ImageCarouselBlock block)
	{
		var slice = ImageCarouselView.Create(new ImageCarouselViewModel
		{
			DirectiveBlock = block,
			Images = block.Images.Select(img => new ImageViewModel
			{
				DirectiveBlock = img,
				Label = img.Label,
				Align = img.Align ?? string.Empty,
				Alt = img.Alt ?? string.Empty,
				Title = img.Title,
				Height = img.Height,
				Width = img.Width,
				Scale = img.Scale ?? string.Empty,
				Screenshot = img.Screenshot,
				Target = img.Target,
				ImageUrl = img.ImageUrl
			}).ToList(),
			MaxHeight = block.MaxHeight
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WritePageCard(HtmlRenderer renderer, PageCardBlock block)
	{
		var slice = PageCardView.Create(new PageCardViewModel
		{
			DirectiveBlock = block,
			Title = block.Title,
			Url = block.ResolvedUrl
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteStepperBlock(HtmlRenderer renderer, StepperBlock block)
	{
		var slice = StepperView.Create(new StepperViewModel { DirectiveBlock = block });
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteStepBlock(HtmlRenderer renderer, StepBlock block)
	{
		var slice = StepView.Create(new StepViewModel
		{
			DirectiveBlock = block,
			Title = block.Title,
			Anchor = block.Anchor,
			HeadingLevel = block.HeadingLevel
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteButtonGroup(HtmlRenderer renderer, ButtonGroupBlock block)
	{
		var slice = ButtonGroupView.Create(new ButtonGroupViewModel
		{
			DirectiveBlock = block,
			Align = block.Align
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteButton(HtmlRenderer renderer, ButtonBlock block)
	{
		var slice = ButtonView.Create(new ButtonViewModel
		{
			DirectiveBlock = block,
			Type = block.Type,
			Align = block.Align,
			IsInGroup = block.IsInGroup
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteListSubPages(HtmlRenderer renderer, ListSubPagesBlock block)
	{
		var slice = ListSubPagesView.Create(new ListSubPagesViewModel
		{
			DirectiveBlock = block,
			SubPages = block.SubPages
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteTableDirective(HtmlRenderer renderer, TableDirectiveBlock block)
	{
		block.ValidateTableColumnCount();
		var slice = TableDirectiveView.Create(new TableDirectiveViewModel
		{
			DirectiveBlock = block,
			ColumnWidths = block.ColumnWidths
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteCliModifiers(HtmlRenderer renderer, CliModifiersBlock block)
	{
		if (!block.Destructive && !block.RequiresConfirmation && !block.RequiresAuth
			&& !block.Idempotent && string.IsNullOrWhiteSpace(block.Scope)
			&& !block.Streaming && !block.LongRunning)
			return;

		var slice = CliModifiersView.Create(new CliModifiersViewModel
		{
			DirectiveBlock = block,
			Destructive = block.Destructive,
			RequiresConfirmation = block.RequiresConfirmation,
			RequiresAuth = block.RequiresAuth,
			Idempotent = block.Idempotent,
			Scope = block.Scope,
			Streaming = block.Streaming,
			LongRunning = block.LongRunning,
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteAgentSkill(HtmlRenderer renderer, AgentSkillBlock block)
	{
		if (string.IsNullOrEmpty(block.Url))
			return;

		var prefix = block.Build.UrlPathPrefix?.TrimEnd('/') ?? string.Empty;
		var slice = AgentSkillView.Create(new AgentSkillViewModel
		{
			DirectiveBlock = block,
			Url = block.Url,
			HasBody = block.Count > 0,
			LearnMoreUrl = $"{prefix}/explore-analyze/ai-features/agent-skills"
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteFigure(HtmlRenderer renderer, ImageBlock block)
	{
		var imageUrl = block.ImageUrl != null &&
					   (block.ImageUrl.StartsWith("/_static") || block.ImageUrl.StartsWith("_static"))
			? $"{block.Build.UrlPathPrefix}/{block.ImageUrl.TrimStart('/')}"
			: block.ImageUrl;
		var slice = FigureView.Create(new ImageViewModel
		{
			DirectiveBlock = block,
			Label = block.Label,
			Align = block.Align ?? string.Empty,
			Alt = block.Alt ?? string.Empty,
			Title = block.Title,
			Height = block.Height,
			Scale = block.Scale ?? string.Empty,
			Target = block.Target,
			Width = block.Width,
			Screenshot = block.Screenshot,
			ImageUrl = imageUrl,
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteChildren(HtmlRenderer renderer, DirectiveBlock directiveBlock) =>
		renderer.WriteChildren(directiveBlock);

	private static void WriteVersion(HtmlRenderer renderer, VersionBlock block)
	{
		var slice = VersionView.Create(new VersionViewModel
		{
			DirectiveBlock = block,
			Directive = block.Directive,
			Title = block.Title,
			VersionClass = block.Class
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteAdmonition(HtmlRenderer renderer, AdmonitionBlock block)
	{
		var slice = AdmonitionView.Create(new AdmonitionViewModel
		{
			DirectiveBlock = block,
			Directive = block.Admonition,
			CrossReferenceName = block.CrossReferenceName,
			Classes = block.Classes,
			Title = block.Title,
			Open = block.DropdownOpen.GetValueOrDefault() ? "open" : null,
			AppliesToDefinition = block.AppliesToDefinition,
			AppliesTo = block.AppliesTo,
			BuildContext = block.Build
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteDropdown(HtmlRenderer renderer, DropdownBlock block)
	{
		var slice = DropdownView.Create(new AdmonitionViewModel
		{
			DirectiveBlock = block,
			Directive = block.Admonition,
			CrossReferenceName = block.CrossReferenceName,
			Classes = block.Classes,
			Title = block.Title,
			Open = block.DropdownOpen.GetValueOrDefault() ? "open" : null,
			AppliesToDefinition = block.AppliesToDefinition,
			AppliesTo = block.AppliesTo,
			BuildContext = block.Build
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteTabSet(HtmlRenderer renderer, TabSetBlock block)
	{
		var slice = TabSetView.Create(new TabSetViewModel { DirectiveBlock = block });
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteTabItem(HtmlRenderer renderer, TabItemBlock block)
	{
		var slice = TabItemView.Create(new TabItemViewModel
		{
			DirectiveBlock = block,
			Index = block.Index,
			Title = block.Title,
			TabSetIndex = block.TabSetIndex,
			SyncKey = block.SyncKey,
			TabSetGroupKey = block.TabSetGroupKey
		});
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteAppliesSwitch(HtmlRenderer renderer, AppliesSwitchBlock block)
	{
		var slice = AppliesSwitchView.Create(new AppliesSwitchViewModel { DirectiveBlock = block });
		RenderRazorSlice(slice, renderer);
	}

	private static void WriteAppliesItem(HtmlRenderer renderer, AppliesItemBlock block)
	{
		// Parse the applies_to definition to get the ApplicableTo object
		// Use the pre-parsed AppliesTo from the block (implementing IBlockAppliesTo)
		var appliesTo = block.AppliesTo ?? (block.AppliesToDefinition is not null ? ParseApplicableTo(block.AppliesToDefinition, block) : null);
		var slice = AppliesItemView.Create(new AppliesItemViewModel
		{
			DirectiveBlock = block,
			Index = block.Index,
			AppliesToDefinition = block.AppliesToDefinition,
			AppliesTo = appliesTo,
			AppliesSwitchIndex = block.AppliesSwitchIndex,
			SyncKey = block.SyncKey,
			AppliesSwitchGroupKey = block.AppliesSwitchGroupKey,
			BuildContext = block.Build
		});
		RenderRazorSlice(slice, renderer);
	}

	private static ApplicableTo? ParseApplicableTo(string yaml, DirectiveBlock block)
	{
		try
		{
			var applicableTo = YamlSerialization.Deserialize<ApplicableTo>(yaml, block.Build.ProductsConfiguration);
			if (applicableTo.Diagnostics is null)
				return applicableTo;
			foreach (var (severity, message) in applicableTo.Diagnostics)
				block.Emit(severity, message);
			applicableTo.Diagnostics = null;
			return applicableTo;
		}
		catch (Exception e)
		{
			block.EmitError($"Unable to parse applies_to definition: {yaml}", e);
		}

		return null;
	}

	private static void WriteLiteralIncludeBlock(HtmlRenderer renderer, IncludeBlock block)
	{
		if (!block.Found || block.IncludePath is null)
			return;

		var file = block.Build.ReadFileSystem.FileInfo.New(block.IncludePath);
		var content = block.Build.ReadFileSystem.File.ReadAllText(file.FullName);
		if (string.IsNullOrEmpty(block.Language))
			_ = renderer.Write(content);
		else
		{
			var slice = Code.Create(new CodeViewModel
			{
				CrossReferenceName = null,
				Language = block.Language,
				Caption = null,
				ApiSegments = [],
				RawIncludedFileContents = content
			});
			RenderRazorSlice(slice, renderer);
		}
	}

	private static void WriteIncludeBlock(HtmlRenderer renderer, IncludeBlock block)
	{
		if (!block.Found || block.IncludePath is null)
			return;

		var snippet = block.Build.ReadFileSystem.FileInfo.New(block.IncludePath);

		var parentPath = block.Context.MarkdownParentPath ?? block.Context.MarkdownSourcePath;
		var document = MarkdownParser.ParseSnippetAsync(block.Build, block.Context, snippet, parentPath, block.Context.YamlFrontMatter, default, block.Line)
			.GetAwaiter().GetResult();

		var html = document.ToHtml(MarkdownParser.Pipeline);
		_ = renderer.Write(html);
	}

	[SuppressMessage("Reliability", "CA2012:Use ValueTasks correctly")]
	private static void WriteSettingsBlock(HtmlRenderer renderer, SettingsBlock block)
	{
		if (!block.Found || block.IncludePath is null)
			return;

		var file = block.Build.ReadFileSystem.FileInfo.New(block.IncludePath);
		YamlSettings? settings;
		try
		{
			var yaml = file.FileSystem.File.ReadAllText(file.FullName);
			settings = SettingsBlock.PrepareSettingsForRendering(
				YamlSerialization.Deserialize<YamlSettings>(yaml, block.Context.Build.ProductsConfiguration),
				block.Context
			);
		}
		catch (YamlException e)
		{
			block.EmitError("Can not be parsed as a valid settings file", e.InnerException ?? e);
			return;
		}
		catch (Exception e)
		{
			block.EmitError("Can not be parsed as a valid settings file", e);
			return;
		}

		var settingsSourceFile = block.Build.ReadFileSystem.FileInfo.New(block.IncludePath);
		var slice = SettingsView.Create(new SettingsViewModel
		{
			SettingsCollection = settings,
			GroupHeadingLevel = block.GroupHeadingLevel,
			VersionsConfig = block.Build.VersionsConfiguration,
			ActiveDeploymentFilter = block.ActiveDeploymentFilter,
			RenderMarkdown = s =>
			{
				var normalized = SettingsMarkdownNormalizer.Normalize(s, settings.Product);
				var document = MarkdownParser.ParseMarkdownStringAsync(
					block.Build,
					block.Context,
					normalized,
					settingsSourceFile,
					block.Context.YamlFrontMatter,
					block.IncludeFrom,
					MarkdownParser.Pipeline);
				var html = document.ToHtml(MarkdownParser.Pipeline);

				// Trim to ensure consistent whitespace
				return html.EnsureTrimmed();
			}
		});
		var html = slice.RenderAsync().GetAwaiter().GetResult();
		_ = renderer.Write(html);
	}

	[SuppressMessage("Reliability", "CA2012:Use ValueTasks correctly")]
	private static void RenderRazorSlice<T>(RazorSlice<T> slice, HtmlRenderer renderer)
	{
		var html = slice.RenderAsync().GetAwaiter().GetResult();
		_ = renderer.Write(html.EnsureTrimmed());
	}

	[SuppressMessage("Reliability", "CA2012:Use ValueTasks correctly")]
	private static void RenderRazorSliceRawContent<T>(RazorSlice<T> slice, HtmlRenderer renderer, DirectiveBlock obj)
		where T : DirectiveViewModel
	{
		var html = slice.RenderAsync().GetAwaiter().GetResult();
		var blocks = html.Split("[CONTENT]", 2, StringSplitOptions.RemoveEmptyEntries);
		_ = renderer.Write(blocks[0]);
		foreach (var o in obj)
			Render(o);

		_ = renderer.Write(blocks[1]);

		void RenderLeaf(LeafBlock p)
		{
			_ = renderer.WriteLeafRawLines(p, true, false, false);
			renderer.EnableHtmlForInline = false;
			foreach (var oo in p.Inline ?? [])
			{
				if (oo is SubstitutionLeaf sl)
					_ = renderer.Write(sl.Replacement);
				else if (oo is LiteralInline li)
					renderer.Write(li);
				else if (oo is LineBreakInline)
					_ = renderer.WriteLine();
				else if (oo is Role r)
				{
					_ = renderer.Write(new string(r.DelimiterChar, r.DelimiterCount));
					renderer.WriteChildren(r);
				}

				else
					_ = renderer.Write($"(LeafBlock: {oo.GetType().Name}");
			}

			renderer.EnableHtmlForInline = true;
		}

		void RenderListBlock(ListBlock l)
		{
			foreach (var bb in l)
			{
				if (bb is LeafBlock lbi)
					RenderLeaf(lbi);
				else if (bb is ListItemBlock ll)
				{
					_ = renderer.Write(ll.TriviaBefore);
					_ = renderer.Write("-");
					foreach (var lll in ll)
						Render(lll);
				}
				else
					_ = renderer.Write($"(ListBlock: {l.GetType().Name}");
			}
		}

		void Render(Block o)
		{
			if (o is LeafBlock p)
				RenderLeaf(p);
			else if (o is ListBlock l)
				RenderListBlock(l);
			else
				_ = renderer.Write($"(Block: {o.GetType().Name}");
		}
	}

	private static void WriteCsvIncludeBlock(HtmlRenderer renderer, CsvIncludeBlock block)
	{
		var viewModel = CsvIncludeViewModel.Create(block, value => RenderCsvCellMarkdown(block, value));
		var slice = CsvIncludeView.Create(viewModel);
		RenderRazorSlice(slice, renderer);
	}

	private static HtmlString RenderCsvCellMarkdown(CsvIncludeBlock block, string value)
	{
		if (string.IsNullOrWhiteSpace(value))
			return HtmlString.Empty;

		var document = MarkdownParser.ParseMarkdownStringAsync(
			block.Build,
			block.Context,
			value,
			block.IncludeFrom,
			block.Context.YamlFrontMatter,
			MarkdownParser.Pipeline);

		if (document.Count == 1 && document.FirstOrDefault() is ParagraphBlock paragraph && paragraph.Inline != null)
			return RenderInlineMarkdown(paragraph);

		var html = document.ToHtml(MarkdownParser.Pipeline);
		return new HtmlString(html.EnsureTrimmed());
	}

	private static HtmlString RenderInlineMarkdown(ParagraphBlock paragraph)
	{
		if (paragraph.Inline is null)
			return HtmlString.Empty;

		var subscription = DocumentationObjectPoolProvider.HtmlRendererPool.Get();
		subscription.HtmlRenderer.WriteChildren(paragraph.Inline);

		var result = subscription.RentedStringBuilder?.ToString();
		DocumentationObjectPoolProvider.HtmlRendererPool.Return(subscription);

		return result == null ? HtmlString.Empty : new HtmlString(result.EnsureTrimmed());
	}

	private static void WriteChangelogBlock(HtmlRenderer renderer, ChangelogBlock block)
	{
		if (!block.Found || block.BundlesFolderPath is null)
			return;

		var markdown = ChangelogInlineRenderer.RenderChangelogMarkdown(block);
		if (string.IsNullOrEmpty(markdown))
			return;

		var document = MarkdownParser.ParseMarkdownStringAsync(
			block.Build,
			block.Context,
			markdown,
			block.CurrentFile,
			block.Context.YamlFrontMatter,
			MarkdownParser.Pipeline);

		var html = document.ToHtml(MarkdownParser.Pipeline);
		_ = renderer.Write(html);
	}

	private static void WriteMathBlock(HtmlRenderer renderer, MathBlock block)
	{
		// Output HTML that KaTeX can render client-side
		var labelAttr = !string.IsNullOrEmpty(block.Label) ? $" id=\"{block.Label}\"" : "";

		if (block.IsDisplayMath)
		{
			// Display math should be a block element
			_ = renderer.Write($"<div class=\"math\"{labelAttr}>");
			_ = renderer.WriteEscape(block.Content ?? "");
			_ = renderer.Write("</div>");
		}
		else
		{
			// Inline math should be a span element to behave like text
			_ = renderer.Write($"<span class=\"math\"{labelAttr}>");
			_ = renderer.WriteEscape(block.Content ?? "");
			_ = renderer.Write("</span>");
		}
		_ = renderer.EnsureLine();
	}
}