@coveo/quantic 3.29.0-pre.aeda47bcba → 3.29.0-pre.b2709de119

package/README.md

@@ -125,7 +125,7 @@ npm run deploy:examples --target-org MyCustomOrg
 
 **Note** Before attempting to run [Playwright](https://playwright.dev/) tests, make sure the `Quantic Examples` community is deployed as described in the previous section in both orgs, the one where LWS is enabled and the one where it is disabled.
 
-**Note** For more information on how to add tests, please refer to our [Quantic Testing Strategy](https://github.com/coveo/ui-kit/blob/master/packages/quantic/decisions/0001-testing-strategy.md), which provides detailed guidelines on testing Quantic components.
+**Note** For more information on how to add tests, please refer to our [Quantic Testing Strategy](https://github.com/coveo/ui-kit/blob/main/packages/quantic/decisions/0001-testing-strategy.md), which provides detailed guidelines on testing Quantic components.
 
 To run Playwright tests, run:
 

package/force-app/main/default/lwc/quanticCitation/quanticCitation.html

@@ -7,6 +7,7 @@
       aria-label={citationTitle}
       href={hrefValue}
       target="_blank"
+      rel="noopener"
       onmouseenter={handleMouseEnter}
       onmouseleave={handleMouseLeave}
       onclick={handleClick} 

package/force-app/main/default/lwc/quanticCitation/quanticCitation.js

@@ -1,4 +1,4 @@
-import {LinkUtils} from 'c/quanticUtils';
+import {LinkUtils, generateTextFragmentUrl} from 'c/quanticUtils';
 import {NavigationMixin} from 'lightning/navigation';
 import {LightningElement, api} from 'lwc';
 
@@ -7,6 +7,8 @@ import {LightningElement, api} from 'lwc';
 const minimumTooltipDisplayDurationMs = 1000;
 const debounceDurationBeforeHoverMs = 200;
 
+const supportedFileTypesForTextFragment = ['html', 'SalesforceItem'];
+
 /**
  * The `QuanticCitation` component renders an individual citation.
  * @fires CustomEvent#quantic__citationhover
@@ -18,7 +20,7 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
   /**
    * The citation item information.
    * @api
-   * @type {{title: string, index: number, text: string, clickUri: string, fields: object}}
+   * @type {{title: string, index: number, text: string, uri: string, clickUri: string, fields: object}}
    */
   @api citation;
   /**
@@ -27,6 +29,13 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
    * @type {InteractiveCitation}
    */
   @api interactiveCitation;
+  /**
+   * Whether to disable citation anchoring.
+   * @api
+   * @type {boolean}
+   * @default false
+   */
+  @api disableCitationAnchoring = false;
 
   /** @type {Object} */
   timeout;
@@ -42,6 +51,16 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
   isInitialRender = true;
   /** @type {string} */
   salesforceRecordUrl;
+  /** @type {boolean} */
+  isHrefWithTextFragment = false;
+
+  connectedCallback() {
+    const fileType = this.citation?.fields?.filetype;
+    this.isHrefWithTextFragment =
+      !this.disableCitationAnchoring &&
+      supportedFileTypesForTextFragment.includes(fileType) &&
+      !!this.text;
+  }
 
   renderedCallback() {
     if (this.isInitialRender) {
@@ -111,7 +130,9 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
   }
 
   handleClick(event) {
-    if (this.isSalesforceLink) {
+    // Only apply the Salesforce navigation using the mixin for Salesforce documents and when citation anchoring is disabled.
+    // Otherwise we rely on the default behavior of the browser with a `hrefValue`.
+    if (this.isSalesforceLink && !this.isHrefWithTextFragment) {
       event.preventDefault();
       this.navigateToSalesforceRecord(event);
     }
@@ -145,10 +166,9 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
   }
 
   get hrefValue() {
-    if (this.isSalesforceLink) {
-      return this.salesforceRecordUrl;
-    }
-    return this.clickUri;
+    return this.isHrefWithTextFragment
+      ? generateTextFragmentUrl(this.sourceUri, this.text)
+      : this.sourceUri;
   }
 
   /**
@@ -180,4 +200,10 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
   get index() {
     return this.citation?.index;
   }
+
+  get sourceUri() {
+    return this.isSalesforceLink
+      ? this.salesforceRecordUrl
+      : (this.clickUri ?? this.citation?.uri);
+  }
 }

package/force-app/main/default/lwc/quanticFeedbackModal/quanticFeedbackModal.js

@@ -20,7 +20,7 @@ import successTemplate from './success.html';
  * The `QuanticFeedbackModal` component overlays a message modal on top of the current app window, the modal contains a form that allows the user to give feedback.
  *
  * Under the hood, the component relies on a [`lightningModal`](https://developer.salesforce.com/docs/component-library/bundle/lightning-modal/documentation) component.
- * For an example of how to use the `QuanticFeedbackModal` component, see the [`quanticSmartSnippet`](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/main/default/lwc/quanticSmartSnippet/quanticSmartSnippet.js) implementation.
+ * For an example of how to use the `QuanticFeedbackModal` component, see the [`quanticSmartSnippet`](https://github.com/coveo/ui-kit/blob/main/packages/quantic/force-app/main/default/lwc/quanticSmartSnippet/quanticSmartSnippet.js) implementation.
  *
  * @category Search
  * @category Insight Panel

package/force-app/main/default/lwc/quanticFeedbackModalQna/quanticFeedbackModalQna.js

@@ -32,7 +32,7 @@ import successTemplate from './templates/success.html';
  * The `QuanticFeedbackModalQna` component overlays a message modal on top of the current app window, the modal contains a form that allows the user to give feedback on a CRGA response.
  *
  * Under the hood, the component relies on a [`lightningModal`](https://developer.salesforce.com/docs/component-library/bundle/lightning-modal/documentation) component.
- * For an example of how to use the `QuanticFeedbackModalQna` component, see the [`quanticGeneratedAnswer`](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/main/default/lwc/quanticGeneratedAnswer/quanticGeneratedAnswer.js) implementation.
+ * For an example of how to use the `QuanticFeedbackModalQna` component, see the [`quanticGeneratedAnswer`](https://github.com/coveo/ui-kit/blob/main/packages/quantic/force-app/main/default/lwc/quanticGeneratedAnswer/quanticGeneratedAnswer.js) implementation.
  *
  * @category Search
  * @category Insight Panel

package/force-app/main/default/lwc/quanticGeneratedAnswer/quanticGeneratedAnswer.js

@@ -49,6 +49,7 @@ const MAX_VALID_COLLAPSED_HEIGHT = 500;
 const MIN_VALID_COLLAPSED_HEIGHT = 150;
 
 const GENERATED_ANSWER_DATA_KEY = 'coveo-generated-answer-data';
+const DEFAULT_CITATION_FIELDS = ['sfid', 'sfkbid', 'sfkavid', 'filetype'];
 
 /**
  * The `QuanticGeneratedAnswer` component automatically generates an answer using Coveo machine learning models to answer the query executed by the user.
@@ -71,9 +72,9 @@ export default class QuanticGeneratedAnswer extends LightningElement {
    * A list of fields to fetch with the citations used to generate the answer.
    * @api
    * @type {string}
-   * @defaultValue `'sfid,sfkbid,sfkavid'`
+   * @defaultValue `'sfid,sfkbid,sfkavid,filetype'`
    */
-  @api fieldsToIncludeInCitations = 'sfid,sfkbid,sfkavid';
+  @api fieldsToIncludeInCitations = 'sfid,sfkbid,sfkavid,filetype';
   /**
    * Whether the generated answer should be collapsible when it exceeds the maximum height of 250px.
    * @api
@@ -118,6 +119,13 @@ export default class QuanticGeneratedAnswer extends LightningElement {
       this._maxCollapsedHeight = DEFAULT_COLLAPSED_HEIGHT;
     }
   }
+  /**
+   * Whether to disable citation anchoring.
+   * @api
+   * @type {boolean}
+   * @default false
+   */
+  @api disableCitationAnchoring = false;
 
   labels = {
     generatedAnswerForYou,
@@ -530,10 +538,17 @@ export default class QuanticGeneratedAnswer extends LightningElement {
   }
 
   get citationFields() {
-    return this.fieldsToIncludeInCitations
-      ?.split(',')
-      .map((field) => field.trim())
-      .filter((field) => field.length > 0);
+    const userCitationFields =
+      this.fieldsToIncludeInCitations
+        ?.split(',')
+        .map((field) => field.trim())
+        .filter((field) => field.length > 0) || [];
+
+    const combinedCitationFields = [
+      ...DEFAULT_CITATION_FIELDS,
+      ...userCitationFields,
+    ];
+    return [...new Set(combinedCitationFields)];
   }
 
   get shouldShowDisclaimer() {

package/force-app/main/default/lwc/quanticGeneratedAnswer/templates/generatedAnswer.html

@@ -65,6 +65,7 @@
                     data-testid="generated-answer__citations"
                     citations={citations}
                     citation-hover-handler={handleCitationHover}
+                    disable-citation-anchoring={disableCitationAnchoring}
                   ></c-quantic-source-citations>
                 </div>
               </template>

package/force-app/main/default/lwc/quanticSourceCitations/quanticSourceCitations.html

@@ -10,6 +10,7 @@
           citation={citation.data}
           interactive-citation={citation.interactiveCitation}
           onquantic__citationhover={citation.handleCitationHover}
+          disable-citation-anchoring={disableCitationAnchoring}
         ></c-quantic-citation>
       </template>
     </ol>

package/force-app/main/default/lwc/quanticSourceCitations/quanticSourceCitations.js

@@ -37,6 +37,13 @@ export default class QuanticSourceCitations extends LightningElement {
    * @type {function}
    */
   @api citationHoverHandler;
+  /**
+   * Whether to disable citation anchoring.
+   * @api
+   * @type {boolean}
+   * @default false
+   */
+  @api disableCitationAnchoring = false;
 
   /** @type {AnyHeadless} */
   headless;

package/force-app/main/default/lwc/quanticUtils/citationAnchoringUtils.js

@@ -0,0 +1,43 @@
+/**
+ * Extracts a text to highlight from a given text.
+ * It tries to extract the first sentence, and if it fails, it returns the first few words.
+ * @param {string} text The text from which to extract the text to highlight.
+ * @returns {string} The extracted text to highlight.
+ */
+export function extractTextToHighlight(text) {
+  const fallbackWordCount = 5;
+
+  const trimmedText = text.trim();
+  if (!trimmedText || typeof trimmedText !== 'string') {
+    return '';
+  }
+
+  const sentenceRegex =
+    /(?<=^|\p{P}\s)\p{P}?\p{Lu}.*?[.!?]+(?=\s+(?:\p{Lu}|\d)|$)/gu;
+  const sentences = trimmedText.match(sentenceRegex);
+
+  if (Array.isArray(sentences) && sentences?.length > 0) {
+    return sentences[0].trim();
+  }
+
+  return trimmedText.split(/\s+/).slice(0, fallbackWordCount).join(' ');
+}
+
+/**
+ * Generates an encoded text fragment URL for the citation.
+ * This URL will highlight the text in the citation if it is an HTML file.
+ * @param {string} uri
+ * @param {string} text
+ * @returns {string}
+ * @example
+ * generateTextFragmentUrl('https://example.com', 'This is a sample text.');
+ * // Returns: 'https://example.com#:~:text=This%20is%20a%20sample%20text.'
+ */
+export function generateTextFragmentUrl(uri, text) {
+  const highlight = extractTextToHighlight(text);
+  const encodedTextFragment = encodeURIComponent(highlight).replace(
+    /-/g,
+    '%2D'
+  );
+  return `${uri}#:~:text=${encodedTextFragment}`;
+}

package/force-app/main/default/lwc/quanticUtils/quanticUtils.js

@@ -35,6 +35,7 @@ import pastYear_plural from '@salesforce/label/c.quantic_PastYear_plural';
 export * from './recentQueriesUtils';
 export * from './markdownUtils';
 export * from './facetDependenciesUtils';
+export * from './citationAnchoringUtils';
 
 export class Debouncer {
   _timeout;