@limetech/kompendium 1.1.1

package/dist/markdown-typelinks.ts

@@ -0,0 +1,166 @@
+import type { Node } from 'unist';
+import { isElement, isParent, isTextNode } from './markdown-nodes';
+
+type MapFn = (node: Node, index: number, parent: Node | null) => Node[];
+
+export function typeLinks(
+    options: { types?: string[] } = {},
+): (tree: Node) => Node {
+    return transformer(options.types);
+}
+
+const transformer =
+    (types: string[] = []) =>
+    (tree: Node): Node => {
+        if (types.length === 0) {
+            return tree;
+        }
+
+        const preCodeElements = collectPreCodeElements(tree);
+
+        return flatMap(tree, mapCodeNode(types, preCodeElements));
+    };
+
+function collectPreCodeElements(node: Node): Set<Node> {
+    const set = new Set<Node>();
+    collectPreCode(node, set);
+
+    return set;
+}
+
+function collectPreCode(node: Node, set: Set<Node>) {
+    if (!isParent(node)) {
+        return;
+    }
+
+    if (isElement(node) && node.tagName === 'pre') {
+        for (const child of node.children) {
+            if (isElement(child) && child.tagName === 'code') {
+                set.add(child);
+            }
+        }
+    }
+
+    for (const child of node.children) {
+        collectPreCode(child, set);
+    }
+}
+
+const mapCodeNode =
+    (types: string[] = [], preCodeElements: Set<Node>) =>
+    (node: Node, _: number, parent: Node | null) => {
+        if (!isTextNode(node)) {
+            return [node];
+        }
+
+        if (!parent || !isElement(parent)) {
+            return [node];
+        }
+
+        if (parent.tagName !== 'code') {
+            return [node];
+        }
+
+        if (preCodeElements.has(parent)) {
+            return [node];
+        }
+
+        return wrapText(node, types);
+    };
+
+export function wrapText(node: { value: string }, types: string[] = []) {
+    return splitTypeString(node.value).map(createNode(types));
+}
+
+const createNode =
+    (types: string[] = []) =>
+    (type: string) => {
+        if (!types.includes(type)) {
+            return createTextNode(type);
+        }
+
+        return createLinkNode(type);
+    };
+
+function createTextNode(text: string) {
+    return {
+        type: 'text',
+        value: text,
+    };
+}
+
+function createLinkNode(type: string) {
+    return {
+        type: 'element',
+        tagName: 'a',
+        properties: {
+            href: `#/type/${type}`,
+        },
+        children: [
+            {
+                type: 'text',
+                value: type,
+            },
+        ],
+    };
+}
+
+export function splitTypeString(typeString: string): string[] {
+    const pattern = /(\b\w+\b)+/g;
+    const types = typeString.match(pattern);
+    const result: string[] = [];
+
+    if (!types) {
+        return [typeString];
+    }
+
+    let currentString = typeString;
+    types.forEach((type: string) => {
+        const index = currentString.indexOf(type);
+        if (index > 0) {
+            result.push(currentString.substring(0, index));
+        }
+
+        result.push(type);
+        currentString = currentString.substring(index + type.length);
+    });
+
+    if (currentString.length > 0) {
+        result.push(currentString);
+    }
+
+    return result;
+}
+
+function transformChildren(node: Node, fn: MapFn) {
+    if (!isParent(node)) {
+        return;
+    }
+
+    node.children = node.children.flatMap((child, i) =>
+        transform(child, i, node, fn),
+    );
+}
+
+function transform(
+    node: Node,
+    index: number,
+    parent: Node | null,
+    fn: MapFn,
+): Node[] {
+    transformChildren(node, fn);
+
+    return fn(node, index, parent);
+}
+
+function flatMap(ast: Node, fn: MapFn): Node {
+    const result = transform(ast, 0, null, fn);
+
+    if (result.length !== 1) {
+        throw new Error(
+            `flatMap: root must map to exactly one node, got ${result.length}`,
+        );
+    }
+
+    return result[0];
+}

package/dist/markdown.ts

@@ -0,0 +1,49 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkDirective from 'remark-directive';
+import remarkGfm from 'remark-gfm';
+import remarkRehype from 'remark-rehype';
+import rehypeRaw from 'rehype-raw';
+import rehypeSlug from 'rehype-slug';
+import rehypeStringify from 'rehype-stringify';
+import { saveFrontmatter } from './markdown-frontmatter';
+import {
+    admonitions,
+    normalizeLegacyAdmonitions,
+} from './markdown-admonitions';
+import { kompendiumCode } from './markdown-code';
+import { typeLinks } from './markdown-typelinks';
+
+export interface File {
+    data: {
+        frontmatter?: Record<string, any>;
+        path?: string;
+    };
+
+    toString(): string;
+}
+
+export async function markdownToHtml(text: string, types = []): Promise<File> {
+    const normalized = normalizeLegacyAdmonitions(text);
+
+    const file = await unified()
+        .use(remarkParse)
+        .use(remarkGfm)
+        .use(remarkFrontmatter)
+        .use(saveFrontmatter)
+        .use(remarkDirective)
+        .use(admonitions)
+        .use(remarkRehype, { allowDangerousHtml: true })
+        .use(rehypeRaw)
+        .use(rehypeSlug)
+        .use(typeLinks, { types: types })
+        .use(kompendiumCode)
+        .use(rehypeStringify)
+        .process(normalized);
+
+    return {
+        data: file.data as File['data'],
+        toString: () => file.toString(),
+    };
+}

package/dist/menu.ts

@@ -0,0 +1,189 @@
+import { JsonDocsComponent, JsonDocs } from '@stencil/core/internal';
+import startCase from 'lodash/startCase';
+import { MenuItem, KompendiumGuide, TypeDescription } from '../types';
+
+export function createMenu(
+    docs: JsonDocs,
+    guides: KompendiumGuide[],
+    types: TypeDescription[],
+): MenuItem[] {
+    let menu = [];
+
+    guides.forEach(addGuide(menu, ''));
+    menu = [...menu, createComponentMenu(docs), createTypeMenu(types)];
+
+    return menu;
+}
+
+export const addGuide =
+    (menu: MenuItem[], path: string) => (guide: KompendiumGuide) => {
+        const subPath: string = guide.data.path.replace(path, '');
+        const parts = subPath.split('/');
+        const parentPath = `${path}/${parts[1]}`;
+        let submenu = menu.find((item) => item.path === parentPath + '/');
+
+        if (!submenu && parts.length === 2) {
+            const title = getGuideTitle(guide);
+            menu.push({
+                path: guide.data.path + '/',
+                title: title,
+                children: [],
+            });
+
+            return;
+        }
+
+        if (!submenu) {
+            submenu = {
+                path: parentPath + '/',
+                title: startCase(parts[1]),
+                children: [],
+            };
+            menu.push(submenu);
+        }
+
+        addGuide(submenu.children, parentPath)(guide);
+    };
+
+function getGuideTitle(guide: KompendiumGuide): string {
+    const regex = /^#\s?(.+?)$/m;
+    const match = guide.content.match(regex);
+
+    return match?.[1];
+}
+
+export function createComponentMenu(docs: JsonDocs): MenuItem {
+    const components = docs.components || [];
+
+    return {
+        path: '/component/',
+        title: 'Components',
+        children: components
+            .filter(isNotExample)
+            .filter(isPublic)
+            .map(getComponentMenu),
+    };
+}
+
+export function isExample(component: JsonDocsComponent): boolean {
+    return !!component.dirPath.match(/\/examples?$/);
+}
+
+function isNotExample(component: JsonDocsComponent) {
+    return !isExample(component);
+}
+
+export function isPublic(component: JsonDocsComponent): boolean {
+    return !component.docsTags.find((tag) =>
+        ['internal', 'private', 'ignore'].includes(tag.name),
+    );
+}
+
+export function getComponentMenu(component: JsonDocsComponent): MenuItem {
+    return {
+        path: `/component/${component.tag}/`,
+        title: getComponentTitle(component.tag),
+        children: [
+            getComponentPropertyMenu(component),
+            getComponentEventMenu(component),
+            getComponentMethodMenu(component),
+            getComponentSlotMenu(component),
+            getComponentStyleMenu(component),
+        ].filter((item) => !!item),
+    };
+}
+
+function getComponentPropertyMenu(component: JsonDocsComponent): MenuItem {
+    if (!component.props.length) {
+        return;
+    }
+
+    return {
+        title: 'Properties',
+        path: `/component/${component.tag}/properties/`,
+    };
+}
+
+function getComponentEventMenu(component: JsonDocsComponent): MenuItem {
+    if (!component.events.length) {
+        return;
+    }
+
+    return {
+        title: 'Events',
+        path: `/component/${component.tag}/events/`,
+    };
+}
+
+function getComponentMethodMenu(component: JsonDocsComponent): MenuItem {
+    if (!component.methods.length) {
+        return;
+    }
+
+    return {
+        title: 'Methods',
+        path: `/component/${component.tag}/methods/`,
+    };
+}
+
+function getComponentSlotMenu(component: JsonDocsComponent): MenuItem {
+    if (!component.slots.length) {
+        return;
+    }
+
+    return {
+        title: 'Slots',
+        path: `/component/${component.tag}/slots/`,
+    };
+}
+
+function getComponentStyleMenu(component: JsonDocsComponent): MenuItem {
+    if (!component.styles.length) {
+        return;
+    }
+
+    return {
+        title: 'Styles',
+        path: `/component/${component.tag}/styles/`,
+    };
+}
+
+export function getComponentTitle(tag: string): string {
+    const title = tag.split('-').slice(1).join(' ');
+
+    return title[0].toLocaleUpperCase() + title.slice(1);
+}
+
+export function createApiMenu(): MenuItem {
+    return {
+        path: '/api/',
+        title: 'API',
+    };
+}
+
+export function createVersionMenu(): MenuItem {
+    return {
+        path: '/version/',
+        title: 'Versions',
+    };
+}
+
+function createTypeMenu(types: TypeDescription[]): MenuItem {
+    return {
+        path: '/type/',
+        title: 'Types',
+        // Sort types alphabetically by name
+        children: types
+            .slice()
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map(getTypeMenu),
+    };
+}
+
+export function getTypeMenu(type: TypeDescription): MenuItem {
+    return {
+        path: `/type/${type.name}/`,
+        title: type.name,
+        children: [],
+    };
+}

package/dist/schema.ts

@@ -0,0 +1,233 @@
+import { JsonDocsComponent, JsonDocsProp } from '@stencil/core/internal';
+import {
+    ClassDescription,
+    InterfaceDescription,
+    TypeDescription,
+} from '../types';
+import { isExample } from './menu';
+import negate from 'lodash/negate';
+import startCase from 'lodash/startCase';
+import zipObject from 'lodash/zipObject';
+import pick from 'lodash/pick';
+
+const ARRAY_PATTERN = /^(\w+)(<\w+>)?\[\]$|^Array<(.+)>$/;
+const ENUM_PATTERN = /["'](\w+)["']\s?\|?/g;
+const ID_PATTERN = /^number \| string$|string \| number$/g;
+const TS_UTILITY_PATTERN = /(Partial|Required|Readonly|Array)<(.+?)>/g;
+
+/**
+ * Create schemas for the components that describe their interface
+ * @param {JsonDocsComponent[]} components the components
+ * @param {TypeDescription[]} types type definitions
+ * @returns {*} list of schemas for the components
+ */
+export function createSchemas(
+    components: JsonDocsComponent[],
+    types: TypeDescription[],
+): Array<Record<string, any>> {
+    const componentSchemas =
+        components?.filter(negate(isExample)).map(createSchema(types)) || [];
+    const classSchemas = types?.filter(isClass)?.map(createSchema(types)) || [];
+
+    return [...componentSchemas, ...classSchemas];
+}
+
+const createSchema =
+    (types: TypeDescription[]) =>
+    (object: JsonDocsComponent | ClassDescription) => {
+        const definitions = createDefinitions(types);
+        const properties = createProps(object.props, definitions);
+
+        const schema: any = {
+            type: 'object',
+            $id: getSchemaId(object),
+            properties: properties,
+        };
+
+        const data = JSON.stringify(properties);
+        const definitionKeys = Object.keys(definitions).filter(
+            isReferenceUsed(data),
+        );
+
+        if (definitionKeys.length > 0) {
+            schema.definitions = pick(definitions, definitionKeys);
+        }
+
+        return schema;
+    };
+
+function getSchemaId(object: JsonDocsComponent | ClassDescription): string {
+    if (isClass(object)) {
+        return object.name;
+    }
+
+    return object.tag;
+}
+
+function createDefinitions(types: TypeDescription[]): Record<string, any> {
+    const interfaces: InterfaceDescription[] = types.filter(
+        (type) => type.type === 'interface',
+    ) as any;
+    const keys = interfaces.map((i) => i.name);
+    const schemas = interfaces.map((i) => {
+        return {
+            type: 'object',
+            properties: createProps(i.props as JsonDocsProp[], {}),
+        };
+    });
+
+    return zipObject(keys, schemas);
+}
+
+function createProps(
+    props: Array<Partial<JsonDocsProp>>,
+    definitions: Record<string, any>,
+) {
+    const keys = props?.map((prop) => prop.name) || [];
+    const schemas = props?.map(createPropSchema(definitions)) || [];
+
+    return zipObject(keys, schemas);
+}
+
+const createPropSchema =
+    (definitions: Record<string, any>) => (prop: JsonDocsProp) => {
+        const schema: any = {
+            type: getSchemaType(prop.type),
+            title: startCase(prop.name),
+            description: prop.docs,
+        };
+
+        if (prop.default) {
+            schema.default = getDefaultValue(prop.default, schema.type);
+        }
+
+        if (schema.type === 'array') {
+            schema.items = getSchemaItems(prop.type, definitions);
+        }
+
+        if (schema.type === 'object') {
+            const ref = getSchemaPropertiesRef(prop.type, definitions);
+
+            if (ref) {
+                schema.$ref = ref;
+            } else {
+                schema.additionalProperties = true;
+            }
+        }
+
+        if (schema.type === 'string') {
+            const oneOf = getOneOf(prop.type);
+
+            if (oneOf) {
+                schema.oneOf = oneOf;
+            }
+        }
+
+        return schema;
+    };
+
+function getDefaultValue(value: any, type: string) {
+    if (type === 'boolean') {
+        return value === 'true';
+    }
+
+    if (type === 'number') {
+        return Number(value);
+    }
+
+    if (type !== 'string') {
+        return;
+    }
+
+    if (value === 'null') {
+        return;
+    }
+
+    return value;
+}
+
+function getSchemaType(propType: string) {
+    if (['string', 'number', 'boolean'].includes(propType)) {
+        return propType;
+    }
+
+    if (propType.match(ARRAY_PATTERN)) {
+        return 'array';
+    }
+
+    if (propType.match(ENUM_PATTERN) || propType.match(ID_PATTERN)) {
+        return 'string';
+    }
+
+    return 'object';
+}
+
+function getSchemaItems(propType: string, definitions: Record<string, any>) {
+    const result = propType.match(ARRAY_PATTERN);
+    const type = getSchemaType(result[1] || result[3]);
+
+    const items: any = {
+        type: type,
+    };
+
+    if (type === 'object') {
+        const ref = getSchemaPropertiesRef(result[1] || result[3], definitions);
+
+        if (ref) {
+            items.$ref = ref;
+        } else {
+            items.additionalProperties = true;
+        }
+    }
+
+    return items;
+}
+
+function getSchemaPropertiesRef(
+    propType: string,
+    definitions: Record<string, any>,
+): string {
+    const definition = Object.keys(definitions).find((key) => key === propType);
+    if (definition) {
+        return '#/definitions/' + definition;
+    }
+
+    const type = propType.replace(TS_UTILITY_PATTERN, '$2');
+    if (type === propType) {
+        return;
+    }
+
+    return getSchemaPropertiesRef(type, definitions);
+}
+
+function getOneOf(propType: string) {
+    if (!ENUM_PATTERN.test(propType)) {
+        return;
+    }
+
+    const oneOf = propType.split('|').map((token) => {
+        const value = token.trim().replace(/["']/g, '');
+
+        return {
+            type: 'string',
+            const: value,
+            title: value,
+        };
+    });
+
+    if (!oneOf.length) {
+        return;
+    }
+
+    return oneOf;
+}
+
+const isReferenceUsed = (data: string) => (name: string) => {
+    const ref = '#/definitions/' + name;
+
+    return data.includes(ref);
+};
+
+function isClass(type: any): type is ClassDescription {
+    return type.type === 'class';
+}