@salesforcedevs/docs-components 1.29.0-llm-alpha2 → 1.29.0-newct-alpha1

package/lwc.config.json

@@ -5,7 +5,6 @@
         { "npm": "@salesforcedevs/dw-components" }
     ],
     "expose": [
-        "doc/aiToolbar",
         "doc/amfReference",
         "doc/banner",
         "doc/localeBanner",
@@ -18,6 +17,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.29.0-llm-alpha2",
+  "version": "1.29.0-newct-alpha1",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",

package/src/modules/doc/contentLayout/contentLayout.ts

@@ -1,15 +1,11 @@
 /* eslint-disable @lwc/lwc/no-document-query */
-import { LightningElement, api, createElement, track } from "lwc";
-import { closest, querySelector } from "kagekiri";
+import { LightningElement, api, track } from "lwc";
+import { closest } from "kagekiri";
 import { toJson, normalizeBoolean } from "dxUtils/normalizers";
 import { highlightTerms } from "dxUtils/highlight";
 import { SearchSyncer } from "docUtils/searchSyncer";
 import type { OptionWithLink } from "typings/custom";
 import { buildDocLinkClickHandler } from "dxUtils/analytics";
-import AiToolbar from "doc/aiToolbar";
-
-const AI_TOOLBAR_TAG = "doc-ai-toolbar";
-const PAGE_HEADING_SELECTOR = "h1";
 
 type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
 
@@ -99,17 +95,6 @@ export default class ContentLayout extends LightningElement {
     /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). Passed through to dx-footer. */
     @api origin: string | null = null;
 
-    /** Controls whether the AI toolbar is displayed. */
-    @api
-    get showAiToolbar() {
-        return this._showAiToolbar;
-    }
-    set showAiToolbar(value) {
-        this._showAiToolbar = normalizeBoolean(value);
-        this.updateAiToolbar();
-    }
-    private _showAiToolbar = false;
-
     @api
     get breadcrumbs() {
         return this._breadcrumbs;
@@ -167,7 +152,6 @@ export default class ContentLayout extends LightningElement {
     protected hasRendered: boolean = false;
     protected contentLoaded: boolean = false;
     protected sidebarOpen: boolean = false;
-    protected aiToolbarElement: HTMLElement | null = null;
 
     get shouldDisplayFeedback() {
         return this.contentLoaded && typeof Sprig !== "undefined";
@@ -273,8 +257,6 @@ export default class ContentLayout extends LightningElement {
         window.addEventListener("scroll", this.adjustNavPosition);
         window.addEventListener("resize", this.adjustNavPosition);
 
-        this.updateAiToolbar();
-
         if (!this.hasRendered) {
             this.hasRendered = true;
             this.restoreScroll();
@@ -284,47 +266,6 @@ export default class ContentLayout extends LightningElement {
         }
     }
 
-    /**
-     * Inserts the AI toolbar into the slotted content immediately after the
-     * first H1 found inside this layout. The H1 typically lives deep in
-     * `doc-content`'s shadow (rendered via `lwc:dom="manual"`), so we use
-     * kagekiri's shadow-piercing query to locate it from here.
-     */
-    protected updateAiToolbar(): void {
-        if (!this.showAiToolbar) {
-            this.removeAiToolbar();
-            return;
-        }
-
-        const heading = querySelector(
-            PAGE_HEADING_SELECTOR,
-            this.template.host
-        ) as HTMLElement | null;
-
-        if (!heading) {
-            return;
-        }
-
-        if (this.aiToolbarElement?.previousElementSibling === heading) {
-            return;
-        }
-
-        this.removeAiToolbar();
-
-        const toolbar = createElement(AI_TOOLBAR_TAG, {
-            is: AiToolbar
-        }) as unknown as HTMLElement;
-        heading.parentNode?.insertBefore(toolbar, heading.nextSibling);
-        this.aiToolbarElement = toolbar;
-    }
-
-    protected removeAiToolbar(): void {
-        if (this.aiToolbarElement) {
-            this.aiToolbarElement.remove();
-            this.aiToolbarElement = null;
-        }
-    }
-
     disconnectedCallback(): void {
         this.disconnectObserver();
         window.removeEventListener(
@@ -340,8 +281,6 @@ export default class ContentLayout extends LightningElement {
 
         // Remove link click handler
         this.template.removeEventListener("click", this.handleLinkClick);
-
-        this.removeAiToolbar();
     }
 
     restoreScroll() {
@@ -584,7 +523,6 @@ export default class ContentLayout extends LightningElement {
 
     onSlotChange(): void {
         this.updateRNB();
-        this.updateAiToolbar();
         this.contentLoaded = true;
     }
 

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

@@ -0,0 +1,3 @@
+:host {
+    display: block;
+}

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

@@ -0,0 +1,34 @@
+<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}
+    >
+        <doc-phase
+            slot="doc-phase"
+            lwc:if={docPhaseInfo}
+            doc-phase-info={docPhaseInfo}
+        ></doc-phase>
+
+        <template lwc:if={isMarkdownTopic}>
+            <slot></slot>
+        </template>
+        <!--
+            TODO(W-22340752): render OAS specs via doc-redoc-reference when
+            topicType === "spec". The docs content-type parser currently 404s
+            spec topics until that path lands.
+        -->
+    </doc-content-layout>
+</template>

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

@@ -0,0 +1,85 @@
+import { LightningElement, api } from "lwc";
+import { normalizeBoolean } from "dxUtils/normalizers";
+import type { OptionWithLink } from "typings/custom";
+
+/**
+ * Topic types emitted by the docs content-type parser
+ * (see @salesforcedevs/sfdocs-doc-framework: `TopicTypeEnum`).
+ */
+const TOPIC_TYPE_MARKDOWN = "markdown";
+const TOPIC_TYPE_SPEC = "spec";
+
+/**
+ * Wrapper around `doc-content-layout` for the "docs" content type emitted by
+ * the `DocsContentTypeParser`.
+ *
+ * Mirrors the role that `doc-amf-reference` plays for the "reference" content
+ * type: it owns content-type-aware concerns (markdown body vs. OAS spec via
+ * Redoc) and forwards the chrome (sidebar, breadcrumbs, TOC, footer) to
+ * `doc-content-layout`.
+ *
+ * Only the markdown topic type is wired up today. OAS spec rendering via Redoc
+ * is tracked separately (W-22340752) and currently 404s upstream in the parser.
+ */
+export default class UnifiedContentLayout extends LightningElement {
+    @api breadcrumbs: string | null = null;
+    @api sidebarHeader?: string;
+    @api sidebarValue?: string;
+    @api sidebarContent?: string;
+    @api tocTitle?: string;
+    @api tocOptions?: string;
+    @api tocAriaLevel?: string;
+    @api languages?: OptionWithLink[];
+    @api language?: string;
+
+    /** 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;
+
+    /**
+     * Topic type forwarded from the layout template. The docs parser supports
+     * `markdown` today and `spec` (OAS via Redoc) in a follow-up.
+     */
+    @api topicType: string = TOPIC_TYPE_MARKDOWN;
+
+    private _docPhaseInfo: string | null = null;
+
+    @api
+    get docPhaseInfo(): string | null {
+        return this._docPhaseInfo;
+    }
+
+    set docPhaseInfo(value: string | null) {
+        this._docPhaseInfo = value || null;
+    }
+
+    private _expandChildren = false;
+
+    @api
+    get expandChildren(): boolean {
+        return this._expandChildren;
+    }
+
+    set expandChildren(value: boolean | string) {
+        this._expandChildren = normalizeBoolean(value);
+    }
+
+    get isMarkdownTopic(): boolean {
+        return this.topicType === TOPIC_TYPE_MARKDOWN;
+    }
+
+    get isSpecTopic(): boolean {
+        return this.topicType === TOPIC_TYPE_SPEC;
+    }
+
+    private get enableFooter(): boolean {
+        return !this.hideFooter;
+    }
+}

package/src/modules/doc/aiToolbar/aiToolbar.css

@@ -1,40 +0,0 @@
-@import "dxHelpers/reset";
-
-:host {
-    display: inline-flex;
-}
-
-.ai-toolbar {
-    display: flex;
-    align-items: center;
-    gap: var(--dx-g-spacing-smd);
-    padding-bottom: var(--dx-g-spacing-sm);
-}
-
-.toolbar-button {
-    --dx-g-button-inline-color: var(--dx-g-blue-vibrant-50);
-    --dx-g-button-inline-color-hover: var(--dx-g-blue-vibrant-30);
-    --dx-c-button-font-size: var(--dx-g-text-sm);
-    --dx-c-button-horizontal-spacing: 0;
-    --dx-c-button-icon-vertical-align: middle;
-}
-
-.toolbar-button::part(content) {
-    font-family: var(--dx-g-font-display);
-    font-weight: var(--dx-g-font-demi);
-    line-height: var(--dx-g-spacing-mlg);
-    letter-spacing: 0.07px;
-}
-
-.divider {
-    width: 1px;
-    height: var(--dx-g-spacing-md);
-    background-color: var(--dx-g-gray-70);
-}
-
-@media screen and (max-width: 480px) {
-    .toolbar-button_copy-url,
-    .divider_copy-url {
-        display: none;
-    }
-}

package/src/modules/doc/aiToolbar/aiToolbar.html

@@ -1,53 +0,0 @@
-<template>
-    <div class="ai-toolbar">
-        <dx-tooltip placement="top-right" label={copyMarkdownLabel}>
-            <dx-button
-                class="toolbar-button"
-                variant="inline"
-                size="small"
-                icon-sprite="utility"
-                icon-symbol="copy"
-                icon-size="medium"
-                icon-position="right"
-                aria-label="Copy as Markdown"
-                onclick={handleCopyMarkdown}
-            >
-                Copy as Markdown
-            </dx-button>
-        </dx-tooltip>
-
-        <div class="divider"></div>
-
-        <dx-button
-            class="toolbar-button"
-            variant="inline"
-            size="small"
-            icon-sprite="utility"
-            icon-symbol="new_window"
-            icon-size="medium"
-            icon-position="right"
-            aria-label="View as Markdown"
-            onclick={handleViewMarkdown}
-        >
-            View as Markdown
-        </dx-button>
-
-        <div class="divider divider_copy-url"></div>
-
-        <dx-tooltip placement="top-right" label={copyUrlLabel}>
-            <dx-button
-                class="toolbar-button toolbar-button_copy-url"
-                variant="inline"
-                size="small"
-                icon-sprite="utility"
-                icon-symbol="link"
-                icon-size="medium"
-                icon-position="right"
-                aria-label="Copy URL to Markdown"
-                onclick={handleCopyUrl}
-            >
-                Copy URL to Markdown
-            </dx-button>
-        </dx-tooltip>
-    </div>
-</template>

package/src/modules/doc/aiToolbar/aiToolbar.ts

@@ -1,83 +0,0 @@
-import { LightningElement } from "lwc";
-
-const DEFAULT_COPY_TOOLTIP_LABEL = "Click to copy";
-const COPIED_TOOLTIP_LABEL = "Copied!";
-const COPIED_TOOLTIP_RESET_MS = 2000;
-
-export default class AiToolbar extends LightningElement {
-    copyMarkdownLabel: string = DEFAULT_COPY_TOOLTIP_LABEL;
-    copyUrlLabel: string = DEFAULT_COPY_TOOLTIP_LABEL;
-
-    private copyTooltipResetTimeout: number | null = null;
-
-    async handleCopyMarkdown() {
-        const markdownUrl = this.getMarkdownUrl();
-        if (!markdownUrl) {
-            return;
-        }
-
-        try {
-            const response = await fetch(markdownUrl);
-            if (!response.ok) {
-                return;
-            }
-            const markdown = await response.text();
-            await navigator.clipboard.writeText(markdown);
-            this.flashCopied("copyMarkdownLabel");
-        } catch (error) {
-            console.error(error);
-        }
-    }
-
-    handleViewMarkdown() {
-        const markdownUrl = this.getMarkdownUrl();
-        if (!markdownUrl) {
-            return;
-        }
-        window.open(markdownUrl, "_blank", "noopener,noreferrer");
-    }
-
-    async handleCopyUrl() {
-        const markdownUrl = this.getMarkdownUrl();
-        if (!markdownUrl) {
-            return;
-        }
-
-        try {
-            await navigator.clipboard.writeText(markdownUrl);
-            this.flashCopied("copyUrlLabel");
-        } catch (error) {
-            console.error(error);
-        }
-    }
-
-    /**
-     * Returns the `.md` equivalent of the current page URL with any hash and
-     * query string stripped, or `null` when the current page does not end
-     * with `.html`.
-     */
-    private getMarkdownUrl(): string | null {
-        const url = new URL(window.location.href);
-        url.hash = "";
-        url.search = "";
-
-        if (!url.pathname.endsWith(".html")) {
-            return null;
-        }
-
-        url.pathname = url.pathname.replace(/\.html$/, ".md");
-        return url.toString();
-    }
-
-    private flashCopied(labelKey: "copyMarkdownLabel" | "copyUrlLabel") {
-        if (this.copyTooltipResetTimeout !== null) {
-            window.clearTimeout(this.copyTooltipResetTimeout);
-        }
-        this[labelKey] = COPIED_TOOLTIP_LABEL;
-        this.copyTooltipResetTimeout = window.setTimeout(() => {
-            this.copyMarkdownLabel = DEFAULT_COPY_TOOLTIP_LABEL;
-            this.copyUrlLabel = DEFAULT_COPY_TOOLTIP_LABEL;
-            this.copyTooltipResetTimeout = null;
-        }, COPIED_TOOLTIP_RESET_MS);
-    }
-}

package/src/modules/doc/aiToolbar/aiToolbarMocks.ts

@@ -1,48 +0,0 @@
-import { http, HttpResponse } from "msw";
-
-/**
- * Mocks for the AI toolbar so stories never hit the real
- * docs backend. Any story rendering `doc-ai-toolbar` (directly or via
- * `doc-content-layout`) must register `aiToolbarMswHandlers` and call
- * `interceptWindowOpenForAiToolbar()`.
- */
-export const DUMMY_MARKDOWN_CONTENT = `# Dummy Markdown
-
-Storybook serves this placeholder content in place of the real markdown
-that the docs backend would return for the current page. It exists so
-the "Copied" tooltip, the "View as Markdown" new tab, and the
-"Copy URL to Markdown" clipboard behavior are all exercisable in
-storybook without hitting the live backend.
-
-- Item 1
-- Item 2
-- Item 3
-`;
-
-export const DUMMY_MARKDOWN_DATA_URL = `data:text/markdown;charset=utf-8,${encodeURIComponent(
-    DUMMY_MARKDOWN_CONTENT
-)}`;
-
-/** Intercepts any `.md` GET request and returns the dummy markdown. */
-export const aiToolbarMswHandlers = [
-    http.get(/\.md(\?.*)?$/, () => HttpResponse.text(DUMMY_MARKDOWN_CONTENT))
-];
-
-let windowOpenIntercepted = false;
-
-/** Redirects `window.open` calls for `.md` URLs to the dummy markdown data URL (MSW does not cover new tabs). */
-export function interceptWindowOpenForAiToolbar() {
-    if (windowOpenIntercepted) {
-        return;
-    }
-    windowOpenIntercepted = true;
-
-    const originalOpen = window.open.bind(window);
-    window.open = ((url?: string | URL, target?: string, features?: string) => {
-        const stringUrl = url?.toString() ?? "";
-        if (stringUrl.endsWith(".md")) {
-            return originalOpen(DUMMY_MARKDOWN_DATA_URL, target, features);
-        }
-        return originalOpen(url ?? "", target, features);
-    }) as typeof window.open;
-}