@salesforcedevs/docs-components 1.30.0-fix-alpha → 1.30.1-docs-alpha

package/lwc.config.json

@@ -18,6 +18,7 @@
         "doc/contentMedia",
         "doc/docXmlContent",
         "doc/lwcContentLayout",
+        "doc/unifiedContentLayout",
         "doc/header",
         "doc/heading",
         "doc/headingAnchor",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.30.0-fix-alpha",
+  "version": "1.30.1-docs-alpha",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",

package/src/modules/doc/redocReference/redocReference.ts

@@ -37,7 +37,7 @@ type ReferenceConfig = {
 const SCROLL_THROTTLE_DELAY = 50;
 const ELEMENT_TIMEOUT = 10000;
 const ELEMENT_CHECK_INTERVAL = 100;
-const REFERENCES_SEGMENT = "/references/";
+const DEFAULT_PROJECT_TITLE = "All Reference";
 
 export default class RedocReference extends LightningElement {
     private _referenceConfig: ReferenceConfig = { refList: [] };
@@ -91,19 +91,60 @@ export default class RedocReference extends LightningElement {
      * Project title (same value passed to `<doc-header>` as `subtitle`). Used
      * inside the Redoc-rendered UI to label the parent project.
      */
-    @api projectTitle: string | null = "All Reference";
+    @api
+    get projectTitle(): string | null {
+        return this.isDocContentType
+            ? this._projectTitle
+            : DEFAULT_PROJECT_TITLE;
+    }
+    set projectTitle(value: string | null) {
+        this._projectTitle = value;
+    }
+    private _projectTitle: string | null = null;
+
+    /**
+     * Href to navigate to when the back link is clicked AND there is no
+     * usable referrer (e.g. the user opened the page directly in a fresh
+     * tab).
+     */
+    @api headerHref: string | null = null;
+
+    @api
+    get contentType(): string {
+        return this._contentType;
+    }
+    set contentType(value: string) {
+        this._contentType = value;
+    }
+    private _contentType: string = "";
 
     get specTitle(): string | null {
         return this.getSelectedReference()?.title ?? null;
     }
 
+    get isDocContentType(): boolean {
+        return this.contentType === "docs";
+    }
+
+    get isReferenceContentType(): boolean {
+        return this.contentType === "references";
+    }
+
+    get isMultiSpecSet(): boolean {
+        const refCount = this.referenceConfig?.refList?.length ?? 0;
+        return refCount > 1;
+    }
+
     /**
-     * Whether to show the project header (only for multi-spec reference sets).
+     * Whether to show the project header. Shown for multi-spec reference
+     * sets, and for any docs-content spec topic so it always has a back
+     * link.
      */
     get showRedocHeader(): boolean {
-        const refCount = this._referenceConfig?.refList?.length ?? 0;
-        const isMultiSpecSet = refCount > 1;
-        return isMultiSpecSet && !!(this.projectTitle || this.specTitle);
+        return (
+            (this.isReferenceContentType && this.isMultiSpecSet) ||
+            this.isDocContentType
+        );
     }
 
     /**
@@ -114,11 +155,8 @@ export default class RedocReference extends LightningElement {
         const referrerHref = this.getSameOriginReferrerHref();
         if (referrerHref) {
             window.location.href = referrerHref;
-            return;
-        }
-        const fallbackHref = this.getReferencesRootHref();
-        if (fallbackHref) {
-            window.location.href = fallbackHref;
+        } else if (this.headerHref) {
+            window.location.href = this.headerHref;
         }
     };
 
@@ -143,19 +181,6 @@ export default class RedocReference extends LightningElement {
         }
     }
 
-    /**
-     * Derives the project's `.../references` root from the current URL by
-     * trimming any trailing reference id (and deeper segments). Returns null
-     * when the URL doesn't contain a `/references` segment.
-     */
-    private getReferencesRootHref(): string | null {
-        const { pathname } = window.location;
-        const idx = pathname.lastIndexOf(REFERENCES_SEGMENT);
-        return idx === -1
-            ? null
-            : pathname.slice(0, idx + REFERENCES_SEGMENT.length);
-    }
-
     /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
     get effectiveFooterOrigin(): string {
         return (

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.css

@@ -0,0 +1,19 @@
+:host {
+    display: block;
+}
+
+.content-type-docs doc-phase {
+    --doc-c-phase-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+            var(--dx-g-spacing-xl)
+    );
+}
+
+@media screen and (max-width: 768px) {
+    .content-type-docs doc-phase {
+        --doc-c-phase-top: calc(
+            var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+                40px
+        );
+    }
+}

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.html

@@ -0,0 +1,28 @@
+<template>
+    <doc-content-layout
+        class="content-type content-type-markdown content-type-docs"
+        breadcrumbs={breadcrumbs}
+        share-title={shareTitle}
+        share-twitter-via={twitterVia}
+        sidebar-header={sidebarHeader}
+        sidebar-value={sidebarValue}
+        sidebar-content={sidebarContent}
+        toc-title={tocTitle}
+        toc-options={tocOptions}
+        toc-aria-level={tocAriaLevel}
+        enable-slot-change="true"
+        languages={languages}
+        language={language}
+        show-footer={enableFooter}
+        origin={origin}
+        dev-center={devCenter}
+        brand={brand}
+    >
+        <doc-phase
+            slot="doc-phase"
+            lwc:if={docPhaseInfo}
+            doc-phase-info={docPhaseInfo}
+        ></doc-phase>
+        <slot></slot>
+    </doc-content-layout>
+</template>

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.ts

@@ -0,0 +1,87 @@
+import { LightningElement, api } from "lwc";
+import { toJson } from "dxUtils/normalizers";
+import type { OptionWithLink, TreeNode } from "typings/custom";
+
+/**
+ * Per-topic type emitted by the docs content-type parser
+ * (see @salesforcedevs/sfdocs-doc-framework: `TopicTypeEnum`). Only `spec`
+ * is meaningful inside this component; everything else renders as a plain
+ * markdown-style tile.
+ */
+const TOPIC_TYPE_SPEC = "spec";
+
+/**
+ * Translates per-topic `topicType` into the generic `showForwardArrow` flag
+ * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc).
+ */
+function decorateTopicsWithForwardArrow(
+    topics: Array<TreeNode & { topicType?: string }> | undefined
+): TreeNode[] | undefined {
+    return topics?.map((topic) => {
+        const { topicType, ...decorated } = topic;
+        if (topicType === TOPIC_TYPE_SPEC) {
+            decorated.showForwardArrow = true;
+        }
+        if (decorated.children) {
+            decorated.children = decorateTopicsWithForwardArrow(
+                decorated.children
+            );
+        }
+        return decorated;
+    });
+}
+
+/**
+ * Wrapper around `doc-content-layout` for the "docs" content type emitted by
+ * the `DocsContentTypeParser`.
+ */
+export default class UnifiedContentLayout extends LightningElement {
+    @api breadcrumbs: string | null = null;
+    @api sidebarHeader?: string;
+    @api sidebarValue?: string;
+    @api tocTitle?: string;
+    @api tocOptions?: string;
+    @api tocAriaLevel?: string;
+    @api languages?: OptionWithLink[];
+    @api language?: string;
+    @api devCenter: any = null;
+    @api brand: any = null;
+
+    /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). */
+    @api origin: string | null = null;
+
+    /** Article name from breadcrumbs, used as share title (e.g. for social share). */
+    @api shareTitle: string | null = null;
+
+    /** Optional Twitter "via" handle (e.g. SalesforceDevs) for social share. */
+    @api twitterVia: string | null = null;
+
+    @api hideFooter = false;
+
+    private _docPhaseInfo: string | null = null;
+    private _sidebarContent: unknown = null;
+
+    @api
+    get docPhaseInfo(): string | null {
+        return this._docPhaseInfo;
+    }
+
+    set docPhaseInfo(value: string | null) {
+        this._docPhaseInfo = value || null;
+    }
+
+    @api
+    get sidebarContent(): unknown {
+        return this._sidebarContent;
+    }
+
+    set sidebarContent(value: string) {
+        this._sidebarContent = decorateTopicsWithForwardArrow(
+            toJson(value)?.topics
+        );
+    }
+
+    private get enableFooter(): boolean {
+        return !this.hideFooter;
+    }
+}