@salesforcedevs/dx-components 1.40.11 → 1.42.0

package/src/modules/dx/searchHybrid/searchHybrid.mock.ts

@@ -0,0 +1,244 @@
+/**
+ * Sample /api/search response for the "apex" query, used by the WithResults
+ * story. Shared fields are filled in by `row()`. The two blog rows are
+ * invented so the "blog" filter has something to show; the facet counts are
+ * from the real response.
+ */
+const DEV = "https://developer.salesforce.com/";
+const G = "Apex Developer Guide";
+
+interface Row {
+    url: string;
+    title: string;
+    description?: string;
+    contentType?: string;
+    lastmod?: string | null;
+    matchType?: string;
+    sectionTitle?: string | null;
+    sectionHash?: string | null;
+    snippet: string;
+    snippetSource?: string;
+}
+
+const row = (r: Row, i: number) => ({
+    url: r.url,
+    title: r.title,
+    description: r.description ?? G,
+    locale: "en-us",
+    site: "developer",
+    contentType: r.contentType ?? "docs",
+    lastmod: r.lastmod ?? null,
+    score: 2 - i * 0.04,
+    lexScore: 18,
+    semScore: 0.45,
+    matchType: r.matchType ?? "hybrid",
+    sectionUrl: r.sectionHash ? `${r.url}#${r.sectionHash}` : null,
+    sectionTitle: r.sectionTitle ?? null,
+    snippet: r.snippet,
+    snippetSource: r.snippetSource ?? "headline"
+});
+
+const APEX = `${DEV}docs/platform/apex-dev/references/apex-dev/`;
+const REF = `${DEV}docs/platform/apex-ref/references`;
+const CLI = `${DEV}docs/platform/salesforce-cli-reference/guide/`;
+
+const ROWS: Row[] = [
+    {
+        url: `${APEX}apex-intro.html`,
+        title: `Introducing Apex | ${G}`,
+        snippet:
+            "Introducing <b>Apex</b> | <b>Apex</b> Developer Guide\n\nof hosting server code, such as Java or .NET, in a secure and robust environment. What is <b>Apex</b>?"
+    },
+    {
+        url: `${APEX}apex-intro-what-is-apex.html`,
+        title: `What is Apex? | ${G}`,
+        snippet: "What is <b>Apex</b>?"
+    },
+    {
+        url: `${APEX}connectapi-overview.html`,
+        title: `Connect in Apex | ${G}`,
+        snippet:
+            "Connect in <b>Apex</b> | <b>Apex</b> Developer Guide\n\nConnect in <b>Apex</b> Use Connect in <b>Apex</b> to develop custom experiences in Salesforce."
+    },
+    {
+        url: `${CLI}cli_reference_apex_run.html`,
+        title: "apex run | apex Commands",
+        description:
+            "Execute anonymous Apex code entered on the command line or from a local file.",
+        matchType: "lexical",
+        snippet:
+            "<b>apex</b> run | <b>apex</b> Commands\n\n<b>apex</b> run Execute anonymous <b>Apex</b> code entered on the command line or from a local file."
+    },
+    {
+        url: `${DEV}docs/platform/salesforce-slack-sdk/guide/apex_ref.html`,
+        title: "Apex | Apex SDK for Slack (Beta)",
+        description: "Use Apex classes in the",
+        matchType: "lexical",
+        snippet:
+            "<b>Apex</b> | <b>Apex</b> SDK for Slack (Beta)\n\nk.ActionDispatcher Commands: Slack.SlashCommandDispatcher Events: Slack.EventDispatcher Shortcuts: Slack.ShortcutDispatcher To determine which classes and methods you"
+    },
+    {
+        url: `${DEV}developer-centers/apex`,
+        title: "Apex",
+        description:
+            "Explore the developer resources for Apex to write server-side logic with classes, triggers, and services.",
+        contentType: "page",
+        lastmod: "2026-10-09T20:57:17.000Z",
+        matchType: "lexical",
+        snippet:
+            "Read more Developer Guide Debug, Test, and Deploy <b>Apex</b> Develop your <b>Apex</b> code in a sandbox, debug it, unit-test it"
+    },
+    {
+        url: `${APEX}apex-dev-guide.html`,
+        title: `Apex Developer Guide | ${G}`,
+        snippet:
+            "<b>Apex</b> Developer Guide | <b>Apex</b> Developer Guide\n\nthe Salesforce Release Notes to learn about the most recent updates and changes to <b>Apex</b>."
+    },
+    {
+        url: APEX.slice(0, -1),
+        title: `Apex Developer Guide | ${G}`,
+        snippet:
+            "<b>Apex</b> Developer Guide | <b>Apex</b> Developer Guide\n\nthe Salesforce Release Notes to learn about the most recent updates and changes to <b>Apex</b>."
+    },
+    {
+        url: `${DEV}docs/platform/apex-dev`,
+        title: `Apex Developer Guide | ${G}`,
+        snippet:
+            "You can run <b>Apex</b> code using a variety of mechanisms. <b>Apex</b> code runs in atomic transactions."
+    },
+    {
+        url: `${CLI}cli_reference_apex_run_test.html`,
+        title: "apex run test | apex Commands",
+        description: "Invoke Apex tests in an org.",
+        matchType: "lexical",
+        sectionHash: "aliases-for-apex-run-test",
+        sectionTitle: "Aliases for apex run test",
+        snippet:
+            "<b>apex</b> run test | <b>apex</b> Commands — Aliases for <b>apex</b> run test\n\nd if the target-org configuration variable is already set."
+    },
+    {
+        url: `${APEX}apex-intro-learning-apex.html`,
+        title: `Learning Apex | ${G}`,
+        matchType: "lexical",
+        sectionHash: "in-this-guide-apex-developer-guide",
+        sectionTitle: "In This Guide (Apex Developer Guide)",
+        snippet:
+            "Learning <b>Apex</b> | <b>Apex</b> Developer Guide — In This Guide (<b>Apex</b> Developer Guide)\n\nIn This Guide (<b>Apex</b> Developer Guide) Beginning programmers can look at the following: Introducing <b>Apex</b> , and in particular:"
+    },
+    {
+        url: `${APEX}apex-running.html`,
+        title: `Running Apex | ${G}`,
+        matchType: "lexical",
+        snippet:
+            "Running <b>Apex</b> | <b>Apex</b> Developer Guide\n\nRunning <b>Apex</b> You can access many features of the Salesforce user interface programmatically in <b>Apex</b>, and you can integrate with external SOAP and REST Web services."
+    },
+    {
+        url: `${APEX}apex-testing.html`,
+        title: `Testing Apex | ${G}`,
+        matchType: "lexical",
+        snippet:
+            "Testing <b>Apex</b> | <b>Apex</b> Developer Guide\n\ne tests. You can use it to test classes in isolation, which is important for unit testing."
+    },
+    {
+        url: `${APEX}apex-scheduler.html`,
+        title: `Apex Scheduler | ${G}`,
+        matchType: "lexical",
+        sectionHash: "implementing-the-schedulable-interface",
+        sectionTitle: "Implementing the Schedulable Interface",
+        snippet:
+            "<b>Apex</b> Scheduler | <b>Apex</b> Developer Guide — Implementing the Schedulable Interface\n\nImplementing the Schedulable Interface To schedule an <b>Apex</b> class to run at regular intervals, first write an <b>Apex</b> class that"
+    },
+    {
+        url: `${DEV}docs/platform/apex-ref/references/apex-ref`,
+        title: "Apex Reference Guide",
+        description: "Apex Reference Guide",
+        lastmod: "2026-11-03T01:09:58.000Z",
+        matchType: "semantic",
+        snippet: "Apex Reference Guide",
+        snippetSource: "description"
+    },
+    {
+        url: `${REF}/apex-ref/apex-ref-guide.html`,
+        title: "Apex Reference Guide",
+        description: "Apex Reference Guide",
+        lastmod: "2026-11-03T01:10:03.000Z",
+        matchType: "semantic",
+        snippet: "Apex Reference Guide",
+        snippetSource: "description"
+    },
+    {
+        url: `${REF}/apex-ref/v68.0`,
+        title: "Apex Reference Guide",
+        description: "Apex Reference Guide",
+        lastmod: "2026-11-03T01:10:03.000Z",
+        matchType: "semantic",
+        snippet: "Apex Reference Guide",
+        snippetSource: "description"
+    },
+    {
+        url: REF,
+        title: "Apex Reference Guide",
+        description: "Apex Reference Guide",
+        lastmod: "2026-11-03T01:10:03.000Z",
+        matchType: "semantic",
+        snippet: "Apex Reference Guide",
+        snippetSource: "description"
+    },
+    {
+        url: `${DEV}docs/industries/industries-common-dev/guide/omnistudio-apex-reference.html`,
+        title: "Omnistudio Apex Reference | Industries Common Resources | Industries Common Resources Developer Guide",
+        description:
+            "Apex is a strongly typed, object-oriented programming language that allows developers to execute flow and transaction control statements on the Salesf",
+        matchType: "semantic",
+        snippet:
+            "Apex is a strongly typed, object-oriented programming language that allows developers to execute flow and transaction control statements on the Salesf",
+        snippetSource: "description"
+    },
+    // Invented sample rows so the "blog" filter has results to show.
+    {
+        url: `${DEV}blogs/2026/09/apex-cursors-in-practice`,
+        title: "Apex Cursors in Practice",
+        description: "How to process large result sets with Apex cursors.",
+        contentType: "blog",
+        lastmod: "2026-09-18T00:00:00.000Z",
+        snippet: "Process large result sets with <b>Apex</b> cursors."
+    },
+    {
+        url: `${DEV}blogs/2026/06/apex-testing-tips`,
+        title: "Five Apex Testing Tips",
+        description: "Write faster, more reliable Apex tests.",
+        contentType: "blog",
+        lastmod: "2026-06-02T00:00:00.000Z",
+        snippet: "Write faster, more reliable <b>Apex</b> tests."
+    }
+];
+
+const ALL = ROWS.map(row);
+
+/**
+ * Builds the response the stub returns, honouring the `type` filter and `lang`
+ * query params so the sidebar filters work in Storybook. Facet counts always
+ * reflect the full result set (disjunctive facets), as the real API does.
+ */
+export function mockSearchResponse(params: URLSearchParams) {
+    const type = params.get("type");
+    const results = type ? ALL.filter((r) => r.contentType === type) : ALL;
+    return {
+        query: params.get("q") ?? "apex",
+        locale: params.get("lang") ?? "en-us",
+        site: null,
+        sort: params.get("sort") ?? "relevance",
+        limit: 20,
+        offset: 0,
+        total: type ? results.length : 59,
+        count: results.length,
+        facets: {
+            contentType: [
+                { value: "docs", count: 56 },
+                { value: "blog", count: 2 },
+                { value: "page", count: 1 }
+            ]
+        },
+        results
+    };
+}

package/src/modules/dx/searchHybrid/searchHybrid.ts

@@ -7,11 +7,8 @@ import type { LocaleOption } from "docUtils/searchLocale";
 import {
     decodeHtmlEntities,
     highlightedSnippetHtml,
-    isSortOption,
     resultHref,
-    SORT_OPTIONS,
-    type SearchResult,
-    type SortOption
+    type SearchResult
 } from "docUtils/searchClient";
 import { searchLocalePrefs } from "dxUtils/searchLocalePrefs";
 import { track as trackGTM } from "dxUtils/analytics";
@@ -23,11 +20,19 @@ import { parseSupportedLocales } from "docUtils/searchLocale";
 // are ingested under this site value).
 const DX_SITE = "developer";
 
-const SORT_LABELS: Record<SortOption, string> = {
-    relevance: "Relevance",
-    date: "Most recent"
+// The search backend labels developer docs "docs"; the badge and label
+// constants know them as "documentation". Filtering still sends the raw value.
+const CONTENT_TYPE_ALIASES: Record<string, string> = {
+    docs: "documentation",
+    page: "website"
 };
 
+function normalizeContentType(contentType: string | null): string | null {
+    return contentType != null
+        ? CONTENT_TYPE_ALIASES[contentType] ?? contentType
+        : null;
+}
+
 interface DisplayResult {
     key: string;
     url: string;
@@ -42,6 +47,7 @@ interface DisplayResult {
     // text path renders exactly as before.
     snippetHtml: string | null;
     hasSnippetHtml: boolean;
+    contentType: string | null;
     contentTypeLabel: string | null;
     hasBadge: boolean;
     displayDate: string;
@@ -56,7 +62,7 @@ interface FacetChip {
     cssClass: string;
 }
 
-interface SortSelectOption {
+interface SelectOption {
     value: string;
     label: string;
 }
@@ -162,7 +168,8 @@ export default class SearchHybrid extends LightningElement {
                 r.description != null && r.description !== ""
                     ? decodeHtmlEntities(r.description)
                     : null;
-            const label = this.contentTypeLabel(r.contentType);
+            const contentType = normalizeContentType(r.contentType);
+            const label = this.contentTypeLabel(contentType);
             const displayDate = this.formatDate(r.lastmod);
             // Prefer the highlighted snippet (headline source only); otherwise
             // null → the description text path below renders unchanged.
@@ -176,6 +183,7 @@ export default class SearchHybrid extends LightningElement {
                 hasDescription: description !== null,
                 snippetHtml,
                 hasSnippetHtml: snippetHtml !== null,
+                contentType,
                 contentTypeLabel: label,
                 hasBadge: label !== null,
                 displayDate,
@@ -240,8 +248,9 @@ export default class SearchHybrid extends LightningElement {
         if (contentType == null || contentType === "") {
             return null;
         }
+        const normalized = normalizeContentType(contentType) as string;
         const labels = CONTENT_TYPE_LABELS as Record<string, string>;
-        return labels[contentType] ?? contentType;
+        return labels[normalized] ?? contentType;
     }
 
     // ---- content-type facet chips (disjunctive) ---------------------------
@@ -269,24 +278,51 @@ export default class SearchHybrid extends LightningElement {
         return this.facetChips.length > 0;
     }
 
-    // ---- sort + locale select options -------------------------------------
-
-    get sortOptions(): SortSelectOption[] {
-        return SORT_OPTIONS.map((value) => ({
-            value,
-            label: SORT_LABELS[value]
+    /** Options for the sidebar dx-filter-menu (single-select by content type, sent to the API as `type`). */
+    get typeFilterOptions(): Array<{
+        id: string;
+        name: string;
+        value: string;
+    }> {
+        return this.facetChips.map((chip) => ({
+            id: chip.value,
+            name: `${chip.label} (${chip.count})`,
+            value: chip.value
         }));
     }
 
-    get sortValue(): string {
-        return this.vm?.sort ?? "relevance";
+    get selectedTypeValue(): string {
+        return this.vm?.selectedType ?? "";
+    }
+
+    get hasActiveType(): boolean {
+        return !!this.vm?.selectedType;
+    }
+
+    get noActiveFilters(): boolean {
+        return !this.hasActiveType && this.localeValue === this.defaultLanguage;
+    }
+
+    get showRange(): boolean {
+        return this.hasResults && this.total > 0;
+    }
+
+    get rangeStart(): number {
+        return ((this.vm?.page ?? 1) - 1) * (this.vm?.limit ?? 10) + 1;
+    }
+
+    get rangeEnd(): number {
+        const limit = this.vm?.limit ?? 10;
+        return Math.min(this.rangeStart + limit - 1, this.total);
     }
 
+    // ---- locale select options -------------------------------------
+
     get showLocaleSelector(): boolean {
         return this.controller?.showLocaleSelector ?? false;
     }
 
-    get localeSelectOptions(): SortSelectOption[] {
+    get localeSelectOptions(): SelectOption[] {
         const options = this.controller?.localeOptions ?? [];
         return options.map((l: LocaleOption) => ({
             value: l.id,
@@ -294,6 +330,13 @@ export default class SearchHybrid extends LightningElement {
         }));
     }
 
+    get localeFilterOptions(): Array<{ id: string; name: string }> {
+        return this.localeSelectOptions.map((o) => ({
+            id: o.value,
+            name: o.label
+        }));
+    }
+
     get localeValue(): string {
         return this.vm?.locale ?? this.defaultLanguage;
     }
@@ -314,17 +357,29 @@ export default class SearchHybrid extends LightningElement {
 
     // ---- event handlers ---------------------------------------------------
 
-    handleSortChange(event: CustomEvent<{ value: string }>): void {
-        const value = event.detail?.value;
-        if (isSortOption(value)) {
-            this.controller?.setSort(value);
+    handleLocaleChange(event: CustomEvent<{ value?: { id?: string } }>): void {
+        const value = event.detail?.value?.id;
+        if (value) {
+            this.controller?.setLanguage(value);
         }
     }
 
-    handleLocaleChange(event: CustomEvent<{ value: string }>): void {
-        const value = event.detail?.value;
+    handleTypeFilterChange(
+        event: CustomEvent<{ value?: { value?: string } }>
+    ): void {
+        const value = event.detail?.value?.value;
         if (value) {
-            this.controller?.setLanguage(value);
+            // Disjunctive toggle: the controller clears it if already active.
+            this.controller?.setType(value);
+        }
+    }
+
+    handleClearFilters(): void {
+        if (this.hasActiveType) {
+            this.controller?.setType(null);
+        }
+        if (this.localeValue !== this.defaultLanguage) {
+            this.controller?.setLanguage(this.defaultLanguage);
         }
     }
 

package/src/modules/dx/searchResults/searchResults.css

@@ -248,7 +248,7 @@ li.coveo-dynamic-facet-breadcrumb-value-list-item {
 
 .coveo-pager-list-item {
     border: none;
-    border-radius: 16px;
+    border-radius: var(--dx-g-spacing-xs);
     display: inline-flex;
     align-items: center;
     justify-content: center;
@@ -282,13 +282,64 @@ li.coveo-dynamic-facet-breadcrumb-value-list-item {
     border-right: none;
 }
 
+/* List item states: same padding in all states so text never moves. Ring 8px from text on sides, more on top/bottom. */
 .dx-result {
+    --dx-result-inner-gap-x: var(
+        --dx-g-spacing-sm
+    ); /* 8px between text and ring on sides */
+
+    --dx-result-inner-gap-y: var(
+        --dx-g-spacing-xs
+    ); /* ring closer to card edge so more padding inside box top/bottom */
+
+    position: relative;
     background: white;
-    border-radius: 16px;
+    border-radius: var(--dx-g-spacing-md);
     border: 1px solid rgb(24 24 24 / 4%);
     box-shadow: 0 0 2px 0 rgb(24 24 24 / 8%), 0 2px 4px 1px rgb(24 24 24 / 16%);
-    padding: 20px;
-    margin-bottom: var(--dx-g-spacing-lg);
+    padding: var(--dx-g-spacing-md);
+    margin-bottom: var(--dx-g-spacing-md);
+    transition: background-color 0.1s ease;
+}
+
+/* Hover: same shape as focus box, more padding top/bottom inside box; space between results unchanged */
+.dx-result:hover::after {
+    content: "";
+    position: absolute;
+    top: var(--dx-result-inner-gap-y);
+    bottom: var(--dx-result-inner-gap-y);
+    left: var(--dx-result-inner-gap-x);
+    right: var(--dx-result-inner-gap-x);
+    background: var(--dx-g-cloud-blue-vibrant-95);
+    border-radius: var(--dx-g-spacing-xs);
+    pointer-events: none;
+    z-index: 0;
+}
+
+.dx-result > * {
+    position: relative;
+    z-index: 1;
+}
+
+/* Focus: ring 8px from text via pseudo-element; no padding/layout change */
+.dx-result:focus-within {
+    outline: none;
+}
+
+/* Pseudo: 8px from text; inner ring container/hover (cloud blue 95), outer blue-vibrant-20 */
+.dx-result:focus-within::before {
+    content: "";
+    position: absolute;
+    top: var(--dx-result-inner-gap-y);
+    bottom: var(--dx-result-inner-gap-y);
+    left: var(--dx-result-inner-gap-x);
+    right: var(--dx-result-inner-gap-x);
+    border: none;
+    border-radius: var(--dx-g-spacing-xs);
+    box-shadow: 0 0 0 2px var(--dx-g-cloud-blue-vibrant-95),
+        0 0 0 4px var(--dx-g-blue-vibrant-20);
+    pointer-events: none;
+    z-index: 2;
 }
 
 .dx-result-title {
@@ -322,10 +373,59 @@ li.coveo-dynamic-facet-breadcrumb-value-list-item {
     color: white;
 }
 
-.dx-search-header + .coveo-main-section {
+.dx-search-header + .dx-search-main {
     margin-top: var(--dx-g-spacing-2xl);
 }
 
+.dx-search-results {
+    font-family: var(--dx-g-font-sans);
+    background-color: #fafaf9;
+}
+
+.dx-search-main {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 0 var(--dx-g-spacing-xl);
+}
+
+.dx-search-box-row {
+    margin-bottom: var(--dx-g-spacing-lg);
+}
+
+.dx-search-box-row .dx-search-box {
+    max-width: 400px;
+}
+
+.dx-search-loading {
+    padding: var(--dx-g-spacing-2xl);
+    text-align: center;
+}
+
+.dx-search-loading-image {
+    max-width: 200px;
+}
+
+.dx-search-no-results {
+    display: flex;
+    justify-content: center;
+    gap: 90px;
+    margin: 50px 34px 90px;
+}
+
+.dx-search-no-results-info {
+    text-align: left;
+}
+
+.dx-search-no-results-info > ul {
+    list-style-type: disc;
+    list-style-position: inside;
+    font-size: var(--dx-g-text-xs);
+}
+
+.dx-search-result-list {
+    padding-bottom: var(--dx-g-spacing-2xl);
+}
+
 .dx-search-header-container {
     margin: 0 auto;
     max-width: 1200px;
@@ -498,7 +598,20 @@ li.coveo-dynamic-facet-breadcrumb-value-list-item {
 }
 
 @media screen and (max-width: 768px) {
-    .no-results > img {
+    .no-results > img,
+    .dx-search-no-results > img {
         display: none;
     }
 }
+
+.dx-search-status {
+    border: 0;
+    clip: rect(0 0 0 0);
+    height: 1px;
+    margin: -1px;
+    overflow: hidden;
+    padding: 0;
+    position: absolute;
+    white-space: nowrap;
+    width: 1px;
+}