DefaultTheme.ts

import * as Path from "path";
import * as FS from "fs";

import { Theme } from "../theme";
import { Renderer } from "../renderer";
import {
    Reflection,
    ReflectionKind,
    ProjectReflection,
    ContainerReflection,
    DeclarationReflection,
} from "../../models/reflections/index";
import { ReflectionGroup } from "../../models/ReflectionGroup";
import { UrlMapping } from "../models/UrlMapping";
import { NavigationItem } from "../models/NavigationItem";
import { RendererEvent } from "../events";

/**
 * Defines a mapping of a [[Models.Kind]] to a template file.
 *
 * Used by [[DefaultTheme]] to map reflections to output files.
 */
export interface TemplateMapping {
    /**
     * [[DeclarationReflection.kind]] this rule applies to.
     */
    kind: ReflectionKind[];

    /**
     * Can this mapping have children or should all further reflections be rendered
     * to the defined output page?
     */
    isLeaf: boolean;

    /**
     * The name of the directory the output files should be written to.
     */
    directory: string;

    /**
     * The name of the template that should be used to render the reflection.
     */
    template: string;
}

/**
 * Default theme implementation of TypeDoc. If a theme does not provide a custom
 * [[BaseTheme]] implementation, this theme class will be used.
 */
export class DefaultTheme extends Theme {
    /**
     * Mappings of reflections kinds to templates used by this theme.
     */
    static MAPPINGS: TemplateMapping[] = [
        {
            kind: [ReflectionKind.Class],
            isLeaf: false,
            directory: "classes",
            template: "reflection.hbs",
        },
        {
            kind: [ReflectionKind.Interface],
            isLeaf: false,
            directory: "interfaces",
            template: "reflection.hbs",
        },
        {
            kind: [ReflectionKind.Enum],
            isLeaf: false,
            directory: "enums",
            template: "reflection.hbs",
        },
        {
            kind: [ReflectionKind.Namespace, ReflectionKind.Module],
            isLeaf: false,
            directory: "modules",
            template: "reflection.hbs",
        },
    ];

    static URL_PREFIX = /^(http|ftp)s?:\/\//;

    /**
     * Create a new DefaultTheme instance.
     *
     * @param renderer  The renderer this theme is attached to.
     * @param basePath  The base path of this theme.
     */
    constructor(renderer: Renderer, basePath: string) {
        super(renderer, basePath);
        this.listenTo(
            renderer,
            RendererEvent.BEGIN,
            this.onRendererBegin,
            1024
        );
    }

    /**
     * Test whether the given path contains a documentation generated by this theme.
     *
     * @param path  The path of the directory that should be tested.
     * @returns     TRUE if the given path seems to be a previous output directory,
     *              otherwise FALSE.
     */
    isOutputDirectory(path: string): boolean {
        if (!FS.existsSync(Path.join(path, "index.html"))) {
            return false;
        }
        if (!FS.existsSync(Path.join(path, "assets"))) {
            return false;
        }
        if (!FS.existsSync(Path.join(path, "assets", "js", "main.js"))) {
            return false;
        }
        if (!FS.existsSync(Path.join(path, "assets", "images", "icons.png"))) {
            return false;
        }

        return true;
    }

    /**
     * Map the models of the given project to the desired output files.
     *
     * @param project  The project whose urls should be generated.
     * @returns        A list of [[UrlMapping]] instances defining which models
     *                 should be rendered to which files.
     */
    getUrls(project: ProjectReflection): UrlMapping[] {
        const urls: UrlMapping[] = [];

        if (false == hasReadme(this.application.options.getValue("readme"))) {
            project.url = "index.html";
            urls.push(new UrlMapping("index.html", project, "reflection.hbs"));
        } else {
            project.url = "modules.html";
            urls.push(
                new UrlMapping("modules.html", project, "reflection.hbs")
            );
            urls.push(new UrlMapping("index.html", project, "index.hbs"));
        }

        project.children?.forEach((child: Reflection) => {
            if (child instanceof DeclarationReflection) {
                DefaultTheme.buildUrls(child, urls);
            }
        });

        return urls;
    }

    /**
     * Create a navigation structure for the given project.
     *
     * @param project  The project whose navigation should be generated.
     * @returns        The root navigation item.
     */
    getNavigation(project: ProjectReflection): NavigationItem {
        const multipleEntryPoints =
            project.getChildrenByKind(ReflectionKind.Module).length !== 0;
        const builder = new NavigationBuilder(
            project,
            project,
            multipleEntryPoints
        );
        return builder.build(
            hasReadme(this.application.options.getValue("readme"))
        );
    }

    /**
     * Triggered before the renderer starts rendering a project.
     *
     * @param event  An event object describing the current render operation.
     */
    private onRendererBegin(event: RendererEvent) {
        if (event.project.groups) {
            event.project.groups.forEach(DefaultTheme.applyGroupClasses);
        }

        for (const id in event.project.reflections) {
            const reflection = event.project.reflections[id];
            if (reflection instanceof DeclarationReflection) {
                DefaultTheme.applyReflectionClasses(reflection);
            }

            if (
                reflection instanceof ContainerReflection &&
                reflection.groups
            ) {
                reflection.groups.forEach(DefaultTheme.applyGroupClasses);
            }
        }
    }

    /**
     * Return a url for the given reflection.
     *
     * @param reflection  The reflection the url should be generated for.
     * @param relative    The parent reflection the url generation should stop on.
     * @param separator   The separator used to generate the url.
     * @returns           The generated url.
     */
    static getUrl(
        reflection: Reflection,
        relative?: Reflection,
        separator = "."
    ): string {
        let url = reflection.getAlias();

        if (
            reflection.parent &&
            reflection.parent !== relative &&
            !(reflection.parent instanceof ProjectReflection)
        ) {
            url =
                DefaultTheme.getUrl(reflection.parent, relative, separator) +
                separator +
                url;
        }

        return url;
    }

    /**
     * Return the template mapping for the given reflection.
     *
     * @param reflection  The reflection whose mapping should be resolved.
     * @returns           The found mapping or undefined if no mapping could be found.
     */
    static getMapping(
        reflection: DeclarationReflection
    ): TemplateMapping | undefined {
        return DefaultTheme.MAPPINGS.find((mapping) =>
            reflection.kindOf(mapping.kind)
        );
    }

    /**
     * Build the url for the the given reflection and all of its children.
     *
     * @param reflection  The reflection the url should be created for.
     * @param urls        The array the url should be appended to.
     * @returns           The altered urls array.
     */
    static buildUrls(
        reflection: DeclarationReflection,
        urls: UrlMapping[]
    ): UrlMapping[] {
        const mapping = DefaultTheme.getMapping(reflection);
        if (mapping) {
            if (
                !reflection.url ||
                !DefaultTheme.URL_PREFIX.test(reflection.url)
            ) {
                const url = [
                    mapping.directory,
                    DefaultTheme.getUrl(reflection) + ".html",
                ].join("/");
                urls.push(new UrlMapping(url, reflection, mapping.template));

                reflection.url = url;
                reflection.hasOwnDocument = true;
            }

            for (const child of reflection.children || []) {
                if (mapping.isLeaf) {
                    DefaultTheme.applyAnchorUrl(child, reflection);
                } else {
                    DefaultTheme.buildUrls(child, urls);
                }
            }
        } else if (reflection.parent) {
            DefaultTheme.applyAnchorUrl(reflection, reflection.parent);
        }

        return urls;
    }

    /**
     * Generate an anchor url for the given reflection and all of its children.
     *
     * @param reflection  The reflection an anchor url should be created for.
     * @param container   The nearest reflection having an own document.
     */
    static applyAnchorUrl(reflection: Reflection, container: Reflection) {
        if (!reflection.url || !DefaultTheme.URL_PREFIX.test(reflection.url)) {
            const anchor = DefaultTheme.getUrl(reflection, container, ".");

            reflection.url = container.url + "#" + anchor;
            reflection.anchor = anchor;
            reflection.hasOwnDocument = false;
        }

        reflection.traverse((child) => {
            if (child instanceof DeclarationReflection) {
                DefaultTheme.applyAnchorUrl(child, container);
            }
        });
    }

    /**
     * Generate the css classes for the given reflection and apply them to the
     * [[DeclarationReflection.cssClasses]] property.
     *
     * @param reflection  The reflection whose cssClasses property should be generated.
     */
    static applyReflectionClasses(reflection: DeclarationReflection) {
        const classes: string[] = [];
        let kind: string;

        if (reflection.kind === ReflectionKind.Accessor) {
            if (!reflection.getSignature) {
                classes.push("tsd-kind-set-signature");
            } else if (!reflection.setSignature) {
                classes.push("tsd-kind-get-signature");
            } else {
                classes.push("tsd-kind-accessor");
            }
        } else {
            kind = ReflectionKind[reflection.kind];
            classes.push(DefaultTheme.toStyleClass("tsd-kind-" + kind));
        }

        if (
            reflection.parent &&
            reflection.parent instanceof DeclarationReflection
        ) {
            kind = ReflectionKind[reflection.parent.kind];
            classes.push(DefaultTheme.toStyleClass(`tsd-parent-kind-${kind}`));
        }

        let hasTypeParameters = !!reflection.typeParameters;
        reflection.getAllSignatures().forEach((signature) => {
            hasTypeParameters = hasTypeParameters || !!signature.typeParameters;
        });

        if (hasTypeParameters) {
            classes.push("tsd-has-type-parameter");
        }
        if (reflection.overwrites) {
            classes.push("tsd-is-overwrite");
        }
        if (reflection.inheritedFrom) {
            classes.push("tsd-is-inherited");
        }
        if (reflection.flags.isPrivate) {
            classes.push("tsd-is-private");
        }
        if (reflection.flags.isProtected) {
            classes.push("tsd-is-protected");
        }
        if (reflection.flags.isStatic) {
            classes.push("tsd-is-static");
        }
        if (reflection.flags.isExternal) {
            classes.push("tsd-is-external");
        }

        reflection.cssClasses = classes.join(" ");
    }

    /**
     * Generate the css classes for the given reflection group and apply them to the
     * [[ReflectionGroup.cssClasses]] property.
     *
     * @param group  The reflection group whose cssClasses property should be generated.
     */
    static applyGroupClasses(group: ReflectionGroup) {
        const classes: string[] = [];
        if (group.allChildrenAreInherited) {
            classes.push("tsd-is-inherited");
        }
        if (group.allChildrenArePrivate) {
            classes.push("tsd-is-private");
        }
        if (group.allChildrenAreProtectedOrPrivate) {
            classes.push("tsd-is-private-protected");
        }
        if (group.allChildrenAreExternal) {
            classes.push("tsd-is-external");
        }

        group.cssClasses = classes.join(" ");
    }

    /**
     * Transform a space separated string into a string suitable to be used as a
     * css class, e.g. "constructor method" > "Constructor-method".
     */
    static toStyleClass(str: string) {
        return str
            .replace(/(\w)([A-Z])/g, (_m, m1, m2) => m1 + "-" + m2)
            .toLowerCase();
    }
}

export class NavigationBuilder {
    constructor(
        private project: ProjectReflection,
        private entryPoint: ContainerReflection,
        private multipleEntryPoints: boolean
    ) {}

    /**
     * Build the navigation structure.
     *
     * @param hasReadmeFile True if the project has a readme
     * @returns The root node of the generated navigation structure.
     */
    build(hasReadmeFile: boolean): NavigationItem {
        const root = new NavigationItem("Index", "index.html");
        const sidebarRoot = new NavigationItem(
            this.multipleEntryPoints ? "Modules" : "Exports",
            hasReadmeFile ? "modules.html" : "index.html",
            root
        );
        sidebarRoot.isModules = true;

        const modules: DeclarationReflection[] = [];
        this.project
            .getReflectionsByKind(ReflectionKind.SomeModule)
            .forEach((someModule) => {
                let target = someModule.parent;
                let inScope = someModule === this.entryPoint;
                while (target) {
                    if (target.kindOf(ReflectionKind.Module)) {
                        return;
                    }
                    if (this.entryPoint === target) {
                        inScope = true;
                    }
                    target = target.parent;
                }

                if (inScope && someModule instanceof DeclarationReflection) {
                    modules.push(someModule);
                }
            });

        if (modules.length < 10) {
            this.buildGroups(modules, root);
        } else {
            this.buildGroups(
                this.entryPoint.getChildrenByKind(ReflectionKind.SomeModule),
                root,
                true
            );
        }

        return root;
    }

    /**
     * Create navigation nodes for the given list of reflections. The resulting nodes will be grouped into
     * an "internal" and an "external" section when applicable.
     *
     * @param reflections  The list of reflections which should be transformed into navigation nodes.
     * @param parent       The parent NavigationItem of the newly created nodes.
     * @param buildChildren Whether navigation nodes should also be built for the children of each reflection.
     */
    protected buildGroups(
        reflections: DeclarationReflection[],
        parent: NavigationItem,
        buildChildren = false
    ) {
        let state = -1;
        const hasExternals = this.containsExternals(reflections);
        this.sortReflections(reflections);

        reflections.forEach((reflection) => {
            if (hasExternals && !reflection.flags.isExternal && state !== 1) {
                new NavigationItem(
                    "Internals",
                    undefined,
                    parent,
                    "tsd-is-external"
                );
                state = 1;
            } else if (
                hasExternals &&
                reflection.flags.isExternal &&
                state !== 2
            ) {
                new NavigationItem(
                    "Externals",
                    undefined,
                    parent,
                    "tsd-is-external"
                );
                state = 2;
            }

            const item = NavigationItem.create(reflection, parent);
            this.includeDedicatedUrls(reflection, item);
            if (buildChildren) {
                this.buildChildren(reflection, item);
            }
        });
    }

    /**
     * Create navigation nodes for all container children of the given reflection.
     *
     * @param reflection  The reflection whose children modules should be transformed into navigation nodes.
     * @param parent      The parent NavigationItem of the newly created nodes.
     */
    protected buildChildren(
        reflection: DeclarationReflection,
        parent: NavigationItem
    ) {
        const modules = reflection.getChildrenByKind(ReflectionKind.SomeModule);
        modules.sort((a: DeclarationReflection, b: DeclarationReflection) => {
            return a.getFullName() < b.getFullName() ? -1 : 1;
        });

        modules.forEach((reflection) => {
            const item = NavigationItem.create(reflection, parent);
            this.includeDedicatedUrls(reflection, item);
            this.buildChildren(reflection, item);
        });
    }

    /**
     * Test whether the given list of modules contains an external module.
     *
     * @param modules  The list of modules to test.
     * @returns        TRUE if any of the modules is marked as being external.
     */
    protected containsExternals(modules: DeclarationReflection[]): boolean {
        for (let index = 0, length = modules.length; index < length; index++) {
            if (modules[index].flags.isExternal) {
                return true;
            }
        }
        return false;
    }

    /**
     * Sort the given list of modules by name, groups external modules at the bottom.
     *
     * @param modules  The list of modules that should be sorted.
     */
    protected sortReflections(modules: DeclarationReflection[]) {
        modules.sort((a: DeclarationReflection, b: DeclarationReflection) => {
            if (a.flags.isExternal && !b.flags.isExternal) {
                return 1;
            }
            if (!a.flags.isExternal && b.flags.isExternal) {
                return -1;
            }
            return a.getFullName() < b.getFullName() ? -1 : 1;
        });
    }

    /**
     * Find the urls of all children of the given reflection and store them as dedicated urls
     * of the given NavigationItem.
     *
     * @param reflection  The reflection whose children urls should be included.
     * @param item        The navigation node whose dedicated urls should be set.
     */
    protected includeDedicatedUrls(
        reflection: DeclarationReflection,
        item: NavigationItem
    ) {
        (function walk(reflection: DeclarationReflection) {
            for (const child of reflection.children || []) {
                if (
                    child.hasOwnDocument &&
                    !child.kindOf(ReflectionKind.SomeModule)
                ) {
                    if (!item.dedicatedUrls) {
                        item.dedicatedUrls = [];
                    }
                    item.dedicatedUrls.push(child.url!);
                    walk(child);
                }
            }
        })(reflection);
    }
}

function hasReadme(readme: string) {
    return !readme.endsWith("none");
}