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

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-alpha",
   "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,9 @@
+/*
+ * Keep the host transparent to layout: no positioning context, no new
+ * stacking/containment block, no margin/padding. This is critical so the
+ * inner <doc-content-layout>'s sticky math for the sidebar / right-nav / doc-
+ * phase wrapper continues to use the document viewport as its reference.
+ */
+:host {
+    display: block;
+}

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

@@ -0,0 +1,31 @@
+<template>
+    <doc-content-layout
+        breadcrumbs={breadcrumbs}
+        sidebar-content={sidebarContent}
+        sidebar-value={sidebarValue}
+        sidebar-header={sidebarHeader}
+        toc-title={tocTitle}
+        toc-options={tocOptions}
+        toc-aria-level={tocAriaLevel}
+        enable-slot-change={enableSlotChange}
+        use-old-sidebar={useOldSidebar}
+        languages={languages}
+        language={language}
+        bail-href={bailHref}
+        bail-label={bailLabel}
+        dev-center={devCenter}
+        brand={brand}
+        empty-state-message={emptyStateMessage}
+        show-footer={showFooter}
+        reading-time={readingTime}
+        share-title={shareTitle}
+        share-url={shareUrl}
+        share-twitter-via={shareTwitterVia}
+        origin={origin}
+    >
+        <slot></slot>
+        <slot name="doc-phase" slot="doc-phase"></slot>
+        <slot name="version-banner" slot="version-banner"></slot>
+        <slot name="sidebar-header" slot="sidebar-header"></slot>
+    </doc-content-layout>
+</template>

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

@@ -0,0 +1,98 @@
+import { LightningElement, api } from "lwc";
+import type { OptionWithLink } from "typings/custom";
+import "doc/contentLayout";
+import "doc/phase";
+
+/**
+ * Orchestrator LWC for the unified `docs` content-type.
+ *
+ * Today (Phase 2): thin pass-through over `<doc-content-layout>` for markdown
+ * topics. The data contract matches what `DocsContentTypeParser.compile()`
+ * already emits (`dxSideBarContents`, `routeurl`, `breadcrumbs`,
+ * `docPhaseInfo`, etc.), so the parser does not need to fabricate a
+ * `reference-set-config` shape the way `<doc-amf-reference>` requires.
+ *
+ * Navigation: LNB clicks go through the browser's default `<a href>`
+ * navigation (the same behavior as references and every other SFDocs
+ * content-type). SFDocs is a server-rendered (Nunjucks) framework; LWR's
+ * Outlet only swaps LWC view components, not server-rendered HTML, so there
+ * is no soft-nav mechanism here today. A previous experiment to fake soft
+ * nav with `history.pushState` + a synthetic `popstate` was removed because
+ * it updated the URL bar but did NOT re-fetch the new topic's content (the
+ * content body stayed as the originally-loaded topic until a manual
+ * refresh). Real client-side soft nav for server-rendered routes would
+ * require a Turbo-style fetch + DOM surgery; if that becomes a requirement
+ * it should live in @salesforcedocs/doc-framework so every content-type
+ * benefits, not be patched into this wrapper.
+ *
+ * The two side-effect imports above (`doc/contentLayout`, `doc/phase`) exist
+ * so LWR's static-analysis-based modulepreload emitter discovers them on
+ * the route. Without them the docs route's first paint shows a visible
+ * flash on local dev because the inner LWC + phase badge load only after
+ * this wrapper's bundle parses.
+ *
+ * Future:
+ *   - Phase 3: version-picker wiring in the `sidebar-header` named slot
+ *     (parser emits `versions` / `selectedVersion`; wrapper renders
+ *     `<doc-version-picker>` here).
+ *   - Phase 4: markdown-vs-spec branching in the default slot (use the
+ *     existing `<doc-amf-topic>` + `AmfModelParser` primitives, mirroring
+ *     `<doc-amf-reference>`'s template pattern but without inheriting its
+ *     `/references/` URL conventions or per-reference sidebar tiles).
+ *
+ * Every property is a plain pass-through. `contentLayout`'s own setters run
+ * `toJson` / `normalizeBoolean` on the values, so re-normalizing here would
+ * only risk diverging from upstream as the inner component evolves.
+ */
+export default class UnifiedContentLayout extends LightningElement {
+    /* ---------- Sidebar / breadcrumb / TOC inputs ---------- */
+    @api breadcrumbs: string | null = null;
+    @api sidebarContent: string | object | null = null;
+    @api sidebarValue: string | null = null;
+    @api sidebarHeader: string | null = null;
+
+    @api tocTitle?: string;
+    @api tocOptions?: string;
+    @api tocAriaLevel?: string;
+
+    /* ---------- contentLayout feature toggles ---------- */
+    @api enableSlotChange: string | boolean = false;
+    @api useOldSidebar: string | boolean = false;
+    @api showFooter: string | boolean = false;
+
+    /* ---------- Localization ---------- */
+    @api languages: OptionWithLink[] | null = null;
+    @api language: string | null = null;
+
+    /* ---------- Empty-state / chrome ---------- */
+    @api bailHref: string | null = null;
+    @api bailLabel: string | null = null;
+    @api emptyStateMessage: string | null = null;
+    @api readingTime: string | null = null;
+
+    @api devCenter: string | null = null;
+    @api brand: string | null = null;
+
+    /* ---------- Social share ---------- */
+    @api shareTitle: string | null = null;
+    @api shareUrl: string | null = null;
+    @api shareTwitterVia: string | null = null;
+
+    /* ---------- Footer integration ---------- */
+    @api origin: string | null = null;
+
+    /**
+     * Forwarded imperative method so any caller that holds a reference to the
+     * wrapper (and previously called `contentLayout.setSidebarInputValue`)
+     * keeps working without changes.
+     */
+    @api
+    setSidebarInputValue(searchTerm: string): void {
+        const inner = this.template.querySelector("doc-content-layout") as
+            | (HTMLElement & {
+                  setSidebarInputValue?: (term: string) => void;
+              })
+            | null;
+        inner?.setSidebarInputValue?.(searchTerm);
+    }
+}

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;
-}