@salesforcedevs/docs-components 0.17.0 → 0.17.12-search-alpha

package/src/modules/doc/amfModelParser/amfModelParser.ts

@@ -0,0 +1,674 @@
+// @ts-nocheck not going to check this file because it deals almost entirely with the AmfHelperMixin, which is terrible and not worth messing with. We should just upgrade our LWC version instead.
+import {
+    AmfHelperMixin,
+    EndPoint,
+    Operation
+} from "@api-components/amf-helper-mixin";
+import { normalizeDomId } from "dxUtils/normalizers";
+
+const ID_PROPERTY = "@id";
+const TYPE_PROPERTY = "@type";
+
+export class AmfModelParser extends AmfHelperMixin(Object) {
+    _parsedModel = null;
+
+    constructor(api: any) {
+        super();
+        if (api) {
+            this.amf = Array.isArray(api) ? api[0] : api;
+        }
+    }
+
+    parse() {
+        let model = this.amf;
+        let data = {};
+        let isFragment = true;
+        const moduleKey = this._getAmfKey(
+            this.ns.aml.vocabularies.document.Module
+        );
+        if (this._hasType(model, this.ns.aml.vocabularies.document.Document)) {
+            isFragment = false;
+            model = this._ensureAmfModel(model);
+            data = this._collectData(model);
+        } else if (
+            this._hasType(
+                model,
+                this.ns.aml.vocabularies.security.SecuritySchemeFragment
+            )
+        ) {
+            data = this._collectSecurityData(model);
+        } else if (
+            this._hasType(
+                model,
+                this.ns.aml.vocabularies.apiContract.UserDocumentationFragment
+            )
+        ) {
+            data = this._collectDocumentationData(model);
+        } else if (
+            this._hasType(
+                model,
+                this.ns.aml.vocabularies.shapes.DataTypeFragment
+            )
+        ) {
+            data = this._collectTypeData(model);
+        } else if (
+            model[TYPE_PROPERTY] &&
+            moduleKey === model[TYPE_PROPERTY][0]
+        ) {
+            data = this._collectData(model);
+        }
+
+        this._collectName(model, data);
+
+        const summaryId = data.title + "Summary";
+
+        return {
+            title: data.title,
+            summary: {
+                id: summaryId,
+                label: "Summary",
+                domId: normalizeDomId(summaryId)
+            },
+            types: data.types,
+            security: data.securitySchemes,
+            endpoints: data.endpoints,
+            docs: data.documentation,
+            isFragment
+        };
+    }
+
+    get parsedModel() {
+        if (!this._parsedModel) {
+            this._parsedModel = this.parse();
+        }
+
+        return this._parsedModel;
+    }
+
+    /**
+     * Collects the information about the API and creates data model
+     * for the navigation element
+     *
+     * @param {object} model
+     * @return {Object} Data model for the API navigation
+     */
+    _collectData(model) {
+        const result = {
+            documentation: [],
+            types: [],
+            securitySchemes: [],
+            endpoints: []
+        };
+        if (!model) {
+            return result;
+        }
+        result._typeIds = [];
+        result._basePaths = [];
+        this._traverseDeclarations(model, result);
+        this._traverseReferences(model, result);
+        this._traverseEncodes(model, result);
+        delete result._typeIds;
+        delete result._basePaths;
+        return result;
+    }
+
+    /**
+     * Collects the data from the security fragment
+     * @param {object} model Security fragment model
+     * @return {Object|undefined}
+     */
+    _collectSecurityData(model) {
+        const result = {
+            securitySchemes: []
+        };
+        const encodes = this._computeEncodes(model);
+        if (!encodes) {
+            return undefined;
+        }
+        this._appendSecurityItem(encodes, result);
+        return result;
+    }
+
+    /**
+     * Collects the data from the documentation fragment
+     * @param {object} model Documentation fragment model
+     * @return {Object|undefined}
+     */
+    _collectDocumentationData(model) {
+        const result = {
+            documentation: []
+        };
+        const encodes = this._computeEncodes(model);
+        if (!encodes) {
+            return undefined;
+        }
+        this._appendDocumentationItem(encodes, result);
+        return result;
+    }
+
+    /**
+     * Collects the data from the type fragment
+     * @param {object} model Type fragment model
+     * @return {Object|undefined}
+     */
+    _collectTypeData(model) {
+        const result = {
+            types: [],
+            _typeIds: []
+        };
+        const encodes = this._computeEncodes(model);
+        if (!encodes) {
+            return undefined;
+        }
+        this._appendTypeItem(encodes, result);
+        delete result._typeIds;
+        return result;
+    }
+
+    /**
+     * Traverses the `http://raml.org/vocabularies/document#declares`
+     * node to find types and security schemes.
+     *
+     * @param {object} model AMF model
+     * @param {TargetModel} target Target object where to put data.
+     */
+    _traverseDeclarations(model, target) {
+        const declares = this._computeDeclares(model);
+        if (!declares) {
+            return;
+        }
+        declares.forEach((item) => this._appendModelItem(item, target));
+    }
+
+    /**
+     * Traverses the `http://raml.org/vocabularies/document#references`
+     *
+     * @param {object} model AMF model
+     * @param {TargetModel} target Target object where to put data.
+     */
+    _traverseReferences(model, target) {
+        const refs = this._computeReferences(model);
+        if (!refs) {
+            return;
+        }
+        refs.forEach((item) => {
+            if (
+                !this._hasType(item, this.ns.aml.vocabularies.document.Module)
+            ) {
+                return;
+            }
+            this._traverseDeclarations(item, target);
+        });
+    }
+
+    /**
+     * Traverses the `http://raml.org/vocabularies/document#encodes`
+     * node to find documentation and endpoints.
+     *
+     * @param {object} model AMF model
+     * @param {TargetModel} target Target object where to put data.
+     */
+    _traverseEncodes(model, target) {
+        const webApi = this._computeWebApi(model);
+        const endpoints = this._computeEndpoints(webApi);
+
+        if (endpoints) {
+            endpoints.forEach((item) => this._appendModelItem(item, target));
+        }
+        const dkey = this._getAmfKey(
+            this.ns.aml.vocabularies.core.documentation
+        );
+        const documentation = this._ensureArray(webApi[dkey]);
+        if (documentation) {
+            documentation.forEach((item) =>
+                this._appendModelItem(item, target)
+            );
+        }
+    }
+
+    /**
+     * Extract API title from `http://raml.org/vocabularies/document#encodes`
+     *
+     * @param {object} model AMF model
+     * @param {TargetModel} target Target object where to put data.
+     */
+    _collectName(model, target) {
+        const encodes = this._computeEncodes(model);
+        if (!encodes) {
+            return;
+        }
+
+        target.title = this._getValue(
+            encodes,
+            this._getAmfKey(this.ns.aml.vocabularies.core.name)
+        );
+    }
+
+    /**
+     * Appends declaration of navigation data model to the target if
+     * it matches documentation or security types.
+     *
+     * @param {Object} item AMF model item to check for data.
+     * @param {TargetModel} target The target to which append values.
+     * @return {void}
+     */
+    _appendModelItem(item, target) {
+        if (this._hasType(item, this.ns.w3.shacl.Shape)) {
+            this._appendTypeItem(item, target);
+        } else if (
+            this._hasType(
+                item,
+                this.ns.aml.vocabularies.security.SecurityScheme
+            )
+        ) {
+            this._appendSecurityItem(item, target);
+        } else if (
+            this._hasType(item, this.ns.aml.vocabularies.core.CreativeWork)
+        ) {
+            this._appendDocumentationItem(item, target);
+        } else if (
+            this._hasType(item, this.ns.aml.vocabularies.apiContract.EndPoint)
+        ) {
+            this._appendEndpointItem(item, target);
+        }
+    }
+
+    /**
+     * Appends "type" item to the results.
+     *
+     * @param {Object} item Type item declaration
+     * @param {TargetModel} target
+     * @return {void}
+     */
+    _appendTypeItem(item, target) {
+        const w3name = this._getValue(item, this.ns.w3.shacl.name);
+        if (w3name && w3name.indexOf("amf_inline_type") === 0) {
+            // https://www.mulesoft.org/jira/browse/APIMF-972
+            return;
+        }
+        let name = this._getValue(item, this.ns.aml.vocabularies.core.name);
+        if (!name && w3name) {
+            name = w3name;
+        } else if (!name) {
+            return;
+        }
+        const id = item[ID_PROPERTY];
+        if (!id) {
+            return;
+        }
+        const rfIdKey = this._getAmfKey(
+            this.ns.aml.vocabularies.document.referenceId
+        );
+        const compareId = id;
+        const refNode = this._ensureArray(item[rfIdKey]);
+        const refId = refNode ? refNode[0][ID_PROPERTY] : undefined;
+        const idIndex = target._typeIds.indexOf(compareId);
+        const refIndex = refId ? target._typeIds.indexOf(refId) : -1;
+        if (idIndex === -1 && refIndex === -1) {
+            target._typeIds[target._typeIds.length] = id;
+            if (refId) {
+                target._typeIds[target._typeIds.length] = refId;
+            }
+            target.types.push({
+                label: name,
+                id,
+                domId: normalizeDomId(id)
+            });
+        }
+    }
+
+    /**
+     * Appends "security" item to the results.
+     *
+     * @param {Object} item Type item declaration
+     * @param {TargetModel} target
+     * @return {void}
+     */
+    _appendSecurityItem(item, target) {
+        const voc = this.ns.aml.vocabularies;
+        let name = this._getValue(item, voc.core.displayName);
+        if (!name) {
+            name = this._getValue(item, voc.security.name);
+        }
+        if (!name) {
+            const apiName = this._getValue(item, voc.core.name);
+            const secType = this._getValue(item, voc.security.type);
+            let result = "";
+            if (apiName) {
+                result = `${apiName} - `;
+            }
+            name = result + this._mapAuthName(secType);
+        }
+        const id = item[ID_PROPERTY];
+        target.securitySchemes.push({
+            label: String(name),
+            id,
+            domId: normalizeDomId(id)
+        });
+    }
+
+    /**
+     * Maps authorization scheme name to a label
+     * @param {string} name
+     * @return {string}
+     */
+    _mapAuthName(name) {
+        switch (name) {
+            case "http":
+                return "HTTP";
+            case "openIdConnect":
+                return "OpenID Connect";
+            default:
+                return name;
+        }
+    }
+
+    /**
+     * Checks if url is valid and return it, otherwise returns 'about:blank'.
+     * @param {string} url
+     * @return {string}
+     */
+    _validUrl(url) {
+        return url.startsWith("http://") || url.startsWith("https://")
+            ? url
+            : "about:blank";
+    }
+
+    /**
+     * Appends "documentation" item to the results.
+     *
+     * @param {Object} item Type item declaration
+     * @param {TargetModel} target
+     * @return {void}
+     */
+    _appendDocumentationItem(item, target) {
+        const { core } = this.ns.aml.vocabularies;
+        const id = item[ID_PROPERTY];
+        const urlNode = item[this._getAmfKey(core.url)];
+        const title = this._getValue(item, core.title);
+        const description = this._getValue(item, core.description);
+        const label = title ? String(title) : String(description);
+        let isExternal = false;
+        let url = urlNode ? (urlNode[0] || urlNode)[ID_PROPERTY] : undefined;
+        if (url) {
+            url = this._validUrl(url);
+            isExternal = true;
+        }
+        const result = {
+            id,
+            label,
+            isExternal,
+            url,
+            domId: normalizeDomId(id)
+        };
+        target.documentation.push(result);
+    }
+
+    /**
+     * Appends "endpoint" item to the results.
+     * This also iterates over methods to extract method data.
+     *
+     * @param {Object} item Endpoint item declaration
+     * @param {TargetModel} target
+     * @return {void}
+     */
+    _appendEndpointItem(item, target) {
+        const result = {};
+
+        let name = this._getValue(item, this.ns.aml.vocabularies.core.name);
+        const path = this._getValue(
+            item,
+            this.ns.raml.vocabularies.apiContract.path
+        );
+        result.path = path;
+
+        let tmpPath = path;
+        if (tmpPath[0] === "/") {
+            tmpPath = tmpPath.substr(1);
+        }
+        const parts = tmpPath.split("/");
+        let indent = 0;
+        target._basePaths[target._basePaths.length] = path;
+        if (parts.length > 1) {
+            const lowerParts = parts.slice(0, parts.length - 1);
+            if (lowerParts.length) {
+                for (let i = lowerParts.length - 1; i >= 0; i--) {
+                    const currentPath = `/${lowerParts
+                        .slice(0, i + 1)
+                        .join("/")}`;
+                    if (target._basePaths.indexOf(currentPath) !== -1) {
+                        indent++;
+                    }
+                }
+            }
+        }
+        if (!name) {
+            result.renderPath = false;
+            if (indent > 0) {
+                try {
+                    name = this._computePathName(
+                        path,
+                        parts,
+                        indent,
+                        target._basePaths
+                    );
+                } catch (_) {
+                    name = path;
+                }
+            } else {
+                name = path;
+            }
+        } else {
+            result.renderPath = true;
+        }
+        const id = item[ID_PROPERTY];
+        const key = this._getAmfKey(this.ns.w3.hydra.supportedOperation);
+        const operations = this._ensureArray(item[key]) || [];
+        const methods = operations.map((op) => this._createOperationModel(op));
+        result.label = String(name);
+        result.id = id;
+        result.indent = indent;
+        result.methods = methods;
+        result.domId = normalizeDomId(id);
+        target.endpoints.push(result);
+    }
+
+    /**
+     * Computes label for an endpoint when name is missing and the endpoint
+     * is indented, hence name should be truncated.
+     * @param {string} currentPath Endpoint's path
+     * @param {string[]} parts Path parts
+     * @param {number} indent Endpoint indentation
+     * @param {string[]} basePaths List of base paths already used.
+     * @return {string} Name of the path to render.
+     */
+    _computePathName(currentPath, parts, indent, basePaths) {
+        let path = "";
+        for (let i = 0, len = parts.length; i < len; i++) {
+            path += `/${parts[i]}`;
+            if (basePaths.indexOf(path) !== -1) {
+                indent--;
+            }
+            if (indent === 0) {
+                break;
+            }
+        }
+        return currentPath.replace(path, "");
+    }
+
+    /**
+     * Creates the view model for an opration.
+     *
+     * @param {Object} item Operation AMF model
+     * @return {Object} Method view model
+     */
+    _createOperationModel(item) {
+        const label = this._getValue(item, this.ns.aml.vocabularies.core.name);
+        const methodKey = this.ns.aml.vocabularies.apiContract.method;
+        const id = item[ID_PROPERTY];
+        const method = this._getValue(item, methodKey);
+        return {
+            label,
+            id,
+            method,
+            domId: normalizeDomId(id)
+        };
+    }
+
+    /**
+     * Computes Endpoint definition model from web API and current selection.
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for an endpoint fragment.
+     */
+    computeEndpointApiModel(model, selectedId): EndPoint {
+        const webApi = this._computeApi(model);
+        return this._computeEndpointModel(webApi, selectedId);
+    }
+
+    /**
+     * Computes Method definition model from web API and current selection.
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for an endpoint fragment.
+     */
+    computeMethodApiModel(model, selected): Operation | undefined {
+        const webApi = this._computeApi(model);
+        return this._computeMethodModel(webApi, selected);
+    }
+
+    /**
+     * Computes Endpoint definition model for a method from web API and current selection.
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for an endpoint fragment.
+     */
+    computeEndpointApiMethodModel(model, selected): EndPoint | undefined {
+        const webApi = this._computeApi(model);
+        return this._computeMethodEndpoint(webApi, selected);
+    }
+
+    /**
+     * Computes security scheme definition model from web API and current selection.
+     * It looks for the definition in both `declares` and `references` properties.
+     * Returned value is already resolved AMF model (references are resolved).
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for the security scheme.
+     */
+    computeSecurityApiModel(model, selected) {
+        const declares = this._computeDeclares(model);
+        let result;
+        if (declares) {
+            result = declares.find((item) => item["@id"] === selected);
+        }
+        if (!result) {
+            const references = this._computeReferences(model);
+            if (references && references.length) {
+                for (let i = 0, len = references.length; i < len; i++) {
+                    if (
+                        !this._hasType(
+                            references[i],
+                            this.ns.aml.vocabularies.document.Module
+                        )
+                    ) {
+                        continue;
+                    }
+                    result = this._computeReferenceSecurity(
+                        references[i],
+                        selected
+                    );
+                    if (result) {
+                        break;
+                    }
+                }
+            }
+        } else {
+            result = this._resolve(result);
+        }
+        return result;
+    }
+
+    /**
+     * Computes documentation definition model from web API and current selection.
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for a documentation fragment.
+     */
+    computeDocsApiModel(model, selected) {
+        const webApi = this._computeApi(model);
+        return this._computeDocument(webApi, selected);
+    }
+
+    /**
+     * Computes type definition model from web API and current selection.
+     * It looks for the definition in both `declares` and `references` properties.
+     * Returned value is already resolved AMF model (references are resolved).
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for a type.
+     */
+    computeTypeApiModel(model, selected) {
+        const declares = this._computeDeclares(model);
+        const references = this._computeReferences(model);
+        return this._computeType(declares, references, selected);
+    }
+
+    /**
+     * Computes a security model from a reference (library for example).
+     * @param {any|any[]} reference AMF model for a reference to extract the data from
+     * @param {string} selected Node ID to look for
+     * @return {any|undefined} Type definition or undefined if not found.
+     */
+    _computeReferenceSecurity(reference, selected) {
+        const declare = this._computeDeclares(reference);
+        if (!declare) {
+            return undefined;
+        }
+        let result = declare.find((item) => {
+            if (Array.isArray(item)) {
+                [item] = item;
+            }
+            return item["@id"] === selected;
+        });
+        if (Array.isArray(result)) {
+            [result] = result;
+        }
+        return this._resolve(result);
+    }
+
+    /**
+     * Computes API's media types when requesting type documentation view.
+     * This is passed to the type documentation to render examples in the type
+     * according to API's defined media type.
+     *
+     * @param {any} model API model.
+     * @return {string[]|undefined} List of supported media types or undefined.
+     */
+    computeApiMediaTypes(model) {
+        if (Array.isArray(model)) {
+            [model] = model;
+        }
+        let webApi = this._computeWebApi(model);
+        if (!webApi) {
+            return undefined;
+        }
+        if (Array.isArray(webApi)) {
+            [webApi] = webApi;
+        }
+        const key = this._getAmfKey(
+            this.ns.aml.vocabularies.apiContract.accepts
+        );
+        const value = this._ensureArray(webApi[key]);
+        if (value) {
+            return value.map((item) => item["@value"]);
+        }
+        return undefined;
+    }
+}

package/src/modules/doc/amfReference/amfReference.css

@@ -0,0 +1,25 @@
+doc-phase {
+    --doc-c-phase-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+            var(--dx-g-spacing-xl)
+    );
+}
+
+/* We need to apply some borders when there are two doc phases */
+doc-phase:not(:only-of-type)::part(container) {
+    border-top: 1px solid var(--dx-g-yellow-vibrant-90);
+}
+
+doc-phase:nth-child(2)::part(container) {
+    border-top: 1px solid var(--dx-g-yellow-vibrant-90);
+    border-bottom: 1px solid var(--dx-g-yellow-vibrant-90);
+}
+
+/* We don't want second component to sticky as we need to handle different cases like position */
+doc-phase:nth-child(2) {
+    position: static;
+}
+
+.api-documentation {
+    margin-top: 48px;
+}