ShellDocsOptions.cs

using System.Reflection;
using Microsoft.AspNetCore.Components;
using ShellDocs.Markdown;

namespace ShellDocs.Components;

public class ShellDocsOptions
{
    public string ContentRoot { get; set; } = "content";
    public string SiteName { get; set; } = "";
    public string? SiteTagline { get; set; }
    public string? GitHubRepo { get; set; }

    public string? LogoLight { get; set; }
    public string? LogoDark { get; set; }
    public string? LogoAlt { get; set; }
    public double LogoHeight { get; set; } = 1.375;
    // Rendered as MarkupString — must be trusted content the consumer authored, not user input.
    public string? LogoSvg { get; set; }
    public ShellDocsTheme Theme { get; set; } = ShellDocsTheme.Shadcn;
    public DocsLayoutVariant LayoutVariant { get; set; } = DocsLayoutVariant.TopNav;

    public List<NavLink> PrimaryNav { get; } = new();
    // 0 or 1 entries hides the sidebar package selector entirely.
    public List<DocsPackage> Packages { get; } = new();
    public List<Type> RegisteredComponents { get; } = new();
    /* Per-type tag alias — when a type appears here, BuildTypeRegistry uses this
       string as the markdown-facing tag name instead of the type's short name.
       Consumers use this to expose a component under a different name in docs
       (e.g. RegisterComponent<Button>("Btn")). Last-write-wins if the same type
       is registered under multiple aliases. */
    public Dictionary<Type, string> ComponentAliases { get; } = new();

    public ShellDocsOptions RegisterComponent<T>() where T : ComponentBase
    {
        RegisteredComponents.Add(typeof(T));
        return this;
    }

    public ShellDocsOptions RegisterComponent<T>(string tagName) where T : ComponentBase
    {
        if (string.IsNullOrWhiteSpace(tagName))
            throw new ArgumentException("tagName must be non-empty.", nameof(tagName));
        RegisteredComponents.Add(typeof(T));
        ComponentAliases[typeof(T)] = tagName;
        return this;
    }

    public ShellDocsOptions RegisterComponent(Type type)
    {
        if (!typeof(ComponentBase).IsAssignableFrom(type))
            throw new ArgumentException($"{type.FullName} must derive from ComponentBase.", nameof(type));
        RegisteredComponents.Add(type);
        return this;
    }

    public ShellDocsOptions RegisterComponent(Type type, string tagName)
    {
        if (!typeof(ComponentBase).IsAssignableFrom(type))
            throw new ArgumentException($"{type.FullName} must derive from ComponentBase.", nameof(type));
        if (string.IsNullOrWhiteSpace(tagName))
            throw new ArgumentException("tagName must be non-empty.", nameof(tagName));
        RegisteredComponents.Add(type);
        ComponentAliases[type] = tagName;
        return this;
    }

    /* Scan the assembly that TMarker lives in for all public, concrete,
       non-generic ComponentBase-derived types and register each. Skips types
       tagged with [ShellDocsIgnore]. Duplicate registrations against the same
       tag name are silently ignored downstream in TypeRegistry. */
    public ShellDocsOptions RegisterComponentsFromAssembly<TMarker>(Func<Type, bool>? filter = null)
        => RegisterComponentsFromAssembly(typeof(TMarker).Assembly, filter);

    public ShellDocsOptions RegisterComponentsFromAssembly(Assembly assembly, Func<Type, bool>? filter = null)
    {
        if (assembly is null) throw new ArgumentNullException(nameof(assembly));
        foreach (var type in DiscoverComponentTypes(assembly))
        {
            if (filter is not null && !filter(type)) continue;
            RegisteredComponents.Add(type);
        }
        return this;
    }

    private static IEnumerable<Type> DiscoverComponentTypes(Assembly assembly)
    {
        Type[] types;
        try { types = assembly.GetTypes(); }
        catch (ReflectionTypeLoadException ex)
        {
            /* An assembly with a partially-loadable type surface still yields
               its resolvable types via the exception's Types property (nulls
               are the unresolvable ones). Salvage what we can. */
            types = ex.Types.Where(t => t is not null).ToArray()!;
        }
        foreach (var t in types)
        {
            if (t is null) continue;
            if (!t.IsClass || t.IsAbstract) continue;
            if (!t.IsPublic && !t.IsNestedPublic) continue;
            if (t.IsGenericTypeDefinition) continue;
            if (!typeof(ComponentBase).IsAssignableFrom(t)) continue;
            if (t.IsDefined(typeof(ShellDocsIgnoreAttribute), inherit: false)) continue;
            yield return t;
        }
    }

    public ShellDocsOptions AddNavLink(string label, string href)
    {
        PrimaryNav.Add(new NavLink(label, href));
        return this;
    }

    public ShellDocsOptions AddNavMenu(string label, params NavMenuItem[] items)
    {
        PrimaryNav.Add(new NavLink(label, "#", Children: items.ToList()));
        return this;
    }

    public ShellDocsOptions AddPackage(string id, string title, string description, string rootUrl, string? iconPath = null)
    {
        Packages.Add(new DocsPackage(id, title, description, rootUrl, iconPath));
        return this;
    }

    public ShellDocsOptions SetLogo(string url, string? alt = null)
    {
        LogoLight = url;
        LogoDark = url;
        if (alt is not null) LogoAlt = alt;
        return this;
    }

    public ShellDocsOptions SetLogo(string lightUrl, string darkUrl, string? alt = null)
    {
        LogoLight = lightUrl;
        LogoDark = darkUrl;
        if (alt is not null) LogoAlt = alt;
        return this;
    }

    internal TypeRegistry BuildTypeRegistry()
    {
        var registry = new TypeRegistry();
        foreach (var type in RegisteredComponents)
        {
            if (ComponentAliases.TryGetValue(type, out var alias))
                registry.Register(alias, type);
            else
                registry.Register(type);
        }
        return registry;
    }
}

public record NavLink(string Label, string Href, List<NavMenuItem>? Children = null);
public record NavMenuItem(string Label, string Href, string? Description = null, string? IconSvg = null);

// IconPath is a raw SVG `d` attribute value on a 24×24 viewBox — not a URL.
public record DocsPackage(string Id, string Title, string Description, string RootUrl, string? IconPath = null);

public enum ShellDocsTheme
{
    Shadcn,
    Fuma,
    Nextra
}

/* Which docs-layout chrome to render. TopNav is the classic build (DocsHeader
   spanning the top + sidebar below). Sidebar drops the top nav and moves
   brand + search + collapse into the sidebar itself — floating shadcn
   sidebar-04 / Claude-Code aesthetic. */
public enum DocsLayoutVariant
{
    TopNav = 0,
    Sidebar = 1
}