@salesforcedevs/docs-components 1.16.0 → 1.17.0-hack-alpha

package/lwc.config.json

@@ -7,6 +7,7 @@
     "expose": [
         "doc/amfReference",
         "doc/breadcrumbs",
+        "doc/commentPopup",
         "doc/componentPlayground",
         "doc/content",
         "doc/contentCallout",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "1.16.0",
+    "version": "1.17.0-hack-alpha",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",
@@ -25,5 +25,5 @@
         "@types/lodash.orderby": "4.6.9",
         "@types/lodash.uniqby": "4.7.9"
     },
-    "gitHead": "977c82c3a242a1476eee4eee5c70b03472a7492e"
+    "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
 }

package/src/modules/doc/commentPopup/commentPopup.css

@@ -0,0 +1,332 @@
+/* Comment Icon Container */
+.comment-icon-container {
+    position: absolute;
+    top: 20px;
+    right: 20px;
+    z-index: 1000;
+}
+
+.comment-icon-button {
+    background: #1976d2;
+    border-radius: 50%;
+    box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+    width: 56px;
+    height: 56px;
+    border: none;
+    cursor: pointer;
+    transition: all 0.3s ease;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.comment-icon-button:hover {
+    background: #1565c0;
+    transform: scale(1.05);
+    box-shadow: 0 6px 16px rgb(0 0 0 / 20%);
+}
+
+.comment-icon-button:active {
+    transform: scale(0.95);
+}
+
+/* Comment Count Badge */
+.comment-count-badge {
+    position: absolute;
+    top: -8px;
+    right: -8px;
+    background: #f44336;
+    color: white;
+    border-radius: 50%;
+    width: 20px;
+    height: 20px;
+    font-size: 12px;
+    font-weight: bold;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 20px;
+    padding: 0 2px;
+    box-sizing: border-box;
+    border: 2px solid white;
+    box-shadow: 0 2px 4px rgb(0 0 0 / 20%);
+}
+
+/* Popup Overlay */
+.popup-overlay {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgb(0 0 0 / 50%);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 2000;
+    padding: 20px;
+    box-sizing: border-box;
+}
+
+/* Popup Container */
+.popup-container {
+    background: white;
+    border-radius: 12px;
+    box-shadow: 0 20px 40px rgb(0 0 0 / 10%);
+    max-width: 500px;
+    width: 100%;
+    max-height: 80vh;
+    overflow-y: auto;
+    position: relative;
+}
+
+/* Popup Header */
+.popup-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 24px 24px 0;
+    border-bottom: 1px solid #e0e0e0;
+    margin-bottom: 24px;
+}
+
+.popup-title {
+    margin: 0;
+    font-size: 20px;
+    font-weight: 600;
+    color: #212121;
+}
+
+.close-button {
+    background: none;
+    border: none;
+    cursor: pointer;
+    padding: 8px;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: background-color 0.2s ease;
+}
+
+.close-button:hover {
+    background: #f5f5f5;
+}
+
+/* Popup Content */
+.popup-content {
+    padding: 0 24px 24px;
+}
+
+/* Comment Form */
+.comment-form {
+    margin-bottom: 24px;
+}
+
+.form-group {
+    margin-bottom: 20px;
+}
+
+.form-label {
+    display: block;
+    margin-bottom: 8px;
+    font-weight: 500;
+    color: #424242;
+    font-size: 14px;
+}
+
+.form-input,
+.form-textarea {
+    width: 100%;
+    padding: 12px 16px;
+    border: 2px solid #e0e0e0;
+    border-radius: 8px;
+    font-size: 14px;
+    font-family: inherit;
+    transition: border-color 0.2s ease;
+    box-sizing: border-box;
+}
+
+.form-input:focus,
+.form-textarea:focus {
+    outline: none;
+    border-color: #1976d2;
+}
+
+.form-textarea {
+    resize: vertical;
+    min-height: 100px;
+}
+
+.error-message {
+    color: #d32f2f;
+    font-size: 12px;
+    margin-top: 4px;
+}
+
+.form-actions {
+    display: flex;
+    justify-content: flex-end;
+}
+
+/* Comments Section */
+.comments-section {
+    border-top: 1px solid #e0e0e0;
+    padding-top: 24px;
+}
+
+.comments-title {
+    margin: 0 0 16px;
+    font-size: 16px;
+    font-weight: 600;
+    color: #212121;
+}
+
+.comments-list {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+}
+
+.comment-item {
+    background: #f8f9fa;
+    border-radius: 8px;
+    padding: 16px;
+    border-left: 4px solid #1976d2;
+}
+
+.comment-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 8px;
+}
+
+.comment-email {
+    font-weight: 500;
+    color: #1976d2;
+    font-size: 14px;
+}
+
+.comment-time {
+    font-size: 12px;
+    color: #757575;
+}
+
+.comment-text {
+    color: #424242;
+    line-height: 1.5;
+    font-size: 14px;
+}
+
+/* Responsive Design */
+@media (max-width: 768px) {
+    .comment-icon-container {
+        top: 16px;
+        right: 16px;
+    }
+
+    .comment-icon-button {
+        width: 48px;
+        height: 48px;
+    }
+
+    .comment-count-badge {
+        width: 18px;
+        height: 18px;
+        font-size: 11px;
+        top: -6px;
+        right: -6px;
+    }
+
+    .popup-overlay {
+        padding: 16px;
+    }
+
+    .popup-container {
+        max-height: 90vh;
+    }
+
+    .popup-header {
+        padding: 16px 16px 0;
+        margin-bottom: 16px;
+    }
+
+    .popup-title {
+        font-size: 18px;
+    }
+
+    .popup-content {
+        padding: 0 16px 16px;
+    }
+
+    .comments-section {
+        padding-top: 16px;
+    }
+}
+
+/* Dark mode support */
+@media (prefers-color-scheme: dark) {
+    .popup-container {
+        background: #303030;
+        color: #fff;
+    }
+
+    .popup-title {
+        color: #fff;
+    }
+
+    .popup-header {
+        border-bottom-color: #424242;
+    }
+
+    .form-label {
+        color: #e0e0e0;
+    }
+
+    .form-input,
+    .form-textarea {
+        background: #424242;
+        border-color: #616161;
+        color: #fff;
+    }
+
+    .form-input:focus,
+    .form-textarea:focus {
+        border-color: #42a5f5;
+    }
+
+    .form-input::placeholder,
+    .form-textarea::placeholder {
+        color: #bdbdbd;
+    }
+
+    .close-button:hover {
+        background: #424242;
+    }
+
+    .comments-section {
+        border-top-color: #424242;
+    }
+
+    .comments-title {
+        color: #fff;
+    }
+
+    .comment-item {
+        background: #424242;
+        border-left-color: #42a5f5;
+    }
+
+    .comment-email {
+        color: #42a5f5;
+    }
+
+    .comment-text {
+        color: #e0e0e0;
+    }
+
+    .comment-count-badge {
+        border-color: #303030;
+    }
+}

package/src/modules/doc/commentPopup/commentPopup.html

@@ -0,0 +1,119 @@
+<template>
+    <!-- Floating Comment Icon -->
+    <div class="comment-icon-container">
+        <dx-button
+            icon-symbol={iconSymbol}
+            icon-size={iconSize}
+            variant="base"
+            onclick={handleIconClick}
+            aria-label="Open comment popup"
+            class="comment-icon-button"
+        ></dx-button>
+        <div if:true={showCommentCount} class="comment-count-badge">
+            {commentCount}
+        </div>
+    </div>
+
+    <!-- Popup Overlay -->
+    <div if:true={open} class="popup-overlay" onclick={handleOverlayClick}>
+        <div
+            class="popup-container"
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="popup-title"
+        >
+            <!-- Popup Header -->
+            <div class="popup-header">
+                <h3 id="popup-title" class="popup-title">{popupTitle}</h3>
+                <dx-button
+                    icon-symbol="close"
+                    icon-size="small"
+                    variant="base"
+                    onclick={handleClose}
+                    aria-label="Close popup"
+                    class="close-button"
+                ></dx-button>
+            </div>
+
+            <!-- Comment Form -->
+            <div class="popup-content">
+                <form class="comment-form" onsubmit={handleSubmit}>
+                    <div class="form-group">
+                        <label for="email-input" class="form-label">
+                            Email
+                        </label>
+                        <input
+                            id="email-input"
+                            type="email"
+                            class="form-input"
+                            placeholder={emailPlaceholder}
+                            value={email}
+                            oninput={handleEmailChange}
+                            required
+                        />
+                        <div if:true={emailError} class="error-message">
+                            {emailError}
+                        </div>
+                    </div>
+
+                    <div class="form-group">
+                        <label for="comment-input" class="form-label">
+                            Comment
+                        </label>
+                        <textarea
+                            id="comment-input"
+                            class="form-textarea"
+                            placeholder={commentPlaceholder}
+                            value={comment}
+                            oninput={handleCommentChange}
+                            rows="4"
+                            required
+                        ></textarea>
+                        <div if:true={commentError} class="error-message">
+                            {commentError}
+                        </div>
+                    </div>
+
+                    <div class="form-actions">
+                        <dx-button
+                            type="submit"
+                            variant="brand"
+                            disabled={submitButtonDisabled}
+                            onclick={handleSubmit}
+                        >
+                            <span if:false={isSubmitting}>
+                                {submitButtonLabel}
+                            </span>
+                            <span if:true={isSubmitting}>Posting...</span>
+                        </dx-button>
+                    </div>
+                </form>
+
+                <!-- Comments List -->
+                <div if:true={showComments} class="comments-section">
+                    <h4 class="comments-title">Comments</h4>
+                    <div class="comments-list">
+                        <template
+                            for:each={formattedComments}
+                            for:item="comment"
+                        >
+                            <div key={comment.email} class="comment-item">
+                                <div class="comment-header">
+                                    <span class="comment-email">
+                                        {comment.maskedEmail}
+                                    </span>
+                                    <span class="comment-time">
+                                        {comment.formattedTimestamp}
+                                    </span>
+                                </div>
+                                <div class="comment-text">
+                                    {comment.comment}
+                                </div>
+                            </div>
+                        </template>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>

package/src/modules/doc/commentPopup/commentPopup.ts

@@ -0,0 +1,213 @@
+import { LightningElement, api, track } from "lwc";
+import { normalizeBoolean } from "dxUtils/normalizers";
+
+interface Comment {
+    email: string;
+    comment: string;
+    url: string;
+    timestamp: Date;
+}
+
+export default class CommentPopup extends LightningElement {
+    @api iconSymbol = "chat";
+    @api iconSize = "medium";
+    @api popupTitle = "Leave a Comment";
+    @api submitButtonLabel = "Post Comment";
+    @api emailPlaceholder = "Enter your email";
+    @api commentPlaceholder = "Enter your comment";
+
+    private _open = false;
+    @api get open() {
+        return this._open;
+    }
+    set open(value) {
+        this._open = normalizeBoolean(value);
+    }
+
+    @track private comments: Comment[] = [];
+    @track private email = "";
+    @track private comment = "";
+    @track private emailError = "";
+    @track private commentError = "";
+    @track private isSubmitting = false;
+
+    get showComments() {
+        const unwrapped = JSON.parse(JSON.stringify(this.comments));
+        console.log("Comments (JSON unwrapped):", unwrapped);
+        return this.comments.length > 0;
+    }
+
+    get commentCount() {
+        return this.comments.length;
+    }
+
+    get showCommentCount() {
+        return this.commentCount > 0;
+    }
+
+    get sortedComments() {
+        return [...this.comments].sort(
+            (a, b) => b.timestamp.getTime() - a.timestamp.getTime()
+        );
+    }
+
+    get isFormValid() {
+        return this.email.trim() !== "" && this.comment.trim() !== "";
+    }
+
+    get submitButtonDisabled() {
+        return !this.isFormValid || this.isSubmitting;
+    }
+
+    handleIconClick() {
+        this._open = !this._open;
+    }
+
+    handleEmailChange(event: Event) {
+        this.email = (event.target as HTMLInputElement).value;
+        this.emailError = "";
+    }
+
+    handleCommentChange(event: Event) {
+        this.comment = (event.target as HTMLTextAreaElement).value;
+        this.commentError = "";
+    }
+
+    handleSubmit() {
+        if (!this.validateForm()) {
+            return;
+        }
+
+        this.isSubmitting = true;
+
+        // Simulate API call
+        setTimeout(() => {
+            this.addComment();
+            this.resetForm();
+            this.isSubmitting = false;
+        }, 500);
+    }
+
+    private validateForm(): boolean {
+        let isValid = true;
+
+        if (!this.email.trim()) {
+            this.emailError = "Email is required";
+            isValid = false;
+        } else if (!this.isValidEmail(this.email)) {
+            this.emailError = "Please enter a valid email address";
+            isValid = false;
+        }
+
+        if (!this.comment.trim()) {
+            this.commentError = "Comment is required";
+            isValid = false;
+        }
+
+        return isValid;
+    }
+
+    private isValidEmail(email: string): boolean {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return emailRegex.test(email);
+    }
+
+    private addComment() {
+        const newComment: Comment = {
+            email: this.email.trim(),
+            comment: this.comment.trim(),
+            url: window.location.href,
+            timestamp: new Date()
+        };
+
+        this.comments = [newComment, ...this.comments];
+
+        // Dispatch custom event
+        this.dispatchEvent(
+            new CustomEvent("commentadded", {
+                detail: newComment
+            })
+        );
+    }
+
+    private resetForm() {
+        this.email = "";
+        this.comment = "";
+        this.emailError = "";
+        this.commentError = "";
+
+        // Force DOM update by accessing the form elements
+        const emailInput = this.template.querySelector(
+            "#email-input"
+        ) as HTMLInputElement;
+        const commentInput = this.template.querySelector(
+            "#comment-input"
+        ) as HTMLTextAreaElement;
+
+        if (emailInput) {
+            emailInput.value = "";
+        }
+        if (commentInput) {
+            commentInput.value = "";
+        }
+    }
+
+    handleClose() {
+        this._open = false;
+        this.resetForm();
+    }
+
+    handleOverlayClick(event: Event) {
+        if (event.target === event.currentTarget) {
+            this.handleClose();
+        }
+    }
+
+    handleKeyDown(event: KeyboardEvent) {
+        if (event.key === "Escape") {
+            this.handleClose();
+        }
+    }
+
+    connectedCallback() {
+        document.addEventListener("keydown", this.handleKeyDown.bind(this));
+    }
+
+    disconnectedCallback() {
+        document.removeEventListener("keydown", this.handleKeyDown.bind(this));
+    }
+
+    private formatTimestamp(timestamp: Date): string {
+        const now = new Date();
+        const diff = now.getTime() - timestamp.getTime();
+        const minutes = Math.floor(diff / 60000);
+        const hours = Math.floor(diff / 3600000);
+        const days = Math.floor(diff / 86400000);
+
+        if (minutes < 1) {
+            return "Just now";
+        } else if (minutes < 60) {
+            return `${minutes} minute${minutes > 1 ? "s" : ""} ago`;
+        } else if (hours < 24) {
+            return `${hours} hour${hours > 1 ? "s" : ""} ago`;
+        }
+        return `${days} day${days > 1 ? "s" : ""} ago`;
+    }
+
+    get formattedComments() {
+        return this.sortedComments.map((comment) => ({
+            ...comment,
+            formattedTimestamp: this.formatTimestamp(comment.timestamp),
+            maskedEmail: this.maskEmail(comment.email)
+        }));
+    }
+
+    private maskEmail(email: string): string {
+        const [localPart, domain] = email.split("@");
+        const maskedLocal =
+            localPart.length > 2
+                ? localPart.substring(0, 2) + "*".repeat(localPart.length - 2)
+                : localPart;
+        return `${maskedLocal}@${domain}`;
+    }
+}

package/src/modules/doc/content/content.ts

@@ -43,26 +43,10 @@ export default class Content extends LightningElement {
         return this.docContent;
     }
 
-    @api
-    set codeBlockTheme(value) {
-        this._codeBlockTheme = value;
-    }
-
-    get codeBlockTheme() {
-        return this._codeBlockTheme;
-    }
-
     @track docContent: DocContent = "";
-    _codeBlockTheme: string = "dark";
     _docRendered: boolean = false;
-    originalCodeBlockThemeValue: String = "";
 
     connectedCallback() {
-        this.template.addEventListener(
-            "themechange",
-            this.updateTheme.bind(this) // eslint-disableline no-use-before-define
-        );
-
         window.addEventListener(
             "highlightedtermchange",
             this.updateHighlighted
@@ -76,15 +60,6 @@ export default class Content extends LightningElement {
         );
     }
 
-    updateTheme() {
-        this._codeBlockTheme =
-            this._codeBlockTheme === "dark" ? "light" : "dark";
-        const codeBlockEls = this.template.querySelectorAll("dx-code-block");
-        codeBlockEls.forEach((codeBlockEl) => {
-            codeBlockEl.setAttribute("theme", this._codeBlockTheme);
-        });
-    }
-
     renderPaginationButton(anchorEl: HTMLElement) {
         const isNext = anchorEl.textContent!.includes("Next →");
         anchorEl.innerHTML = "";
@@ -116,11 +91,11 @@ export default class Content extends LightningElement {
             const codeBlockEls = divEl.querySelectorAll(".codeSection");
             codeBlockEls.forEach((codeBlockEl) => {
                 codeBlockEl.setAttribute("lwc:dom", "manual");
-                const classList = (codeBlockEl.firstChild as any).classList;
+                const classList = codeBlockEl.firstElementChild?.classList;
                 let language = "";
-                for (const key in classList) {
-                    if (typeof classList[key] === "string") {
-                        const className = classList[key];
+                if (classList) {
+                    for (let i = 0; i < classList.length; i++) {
+                        const className = classList[i];
                         if (className.startsWith("brush:")) {
                             language = className.split(":")[1];
                         }
@@ -133,7 +108,6 @@ export default class Content extends LightningElement {
                     codeBlock: codeBlockEl.innerHTML,
                     // ! Hot fix for incoming html tags from couchdb for xml blocks, fix me soon please
                     language: LANGUAGE_MAP[language] || language,
-                    theme: this.codeBlockTheme,
                     header: "", // Default no title.
                     variant: this.codeBlockType,
                     isEncoded: true
@@ -158,6 +132,7 @@ export default class Content extends LightningElement {
                     }
                 });
 
+                // Set a flag to 1 (true) if and only if all detailEls have no content.
                 let flag = 1;
                 for (let i: number = 0; i < detailEls.length; i++) {
                     flag &= (detailEls[i].innerHTML.trim() === "") as any; // Dark Magic TM
@@ -359,7 +334,7 @@ export default class Content extends LightningElement {
         );
 
     @api
-    public navigateToHash(hash: String) {
+    public navigateToHash = (hash: String) => {
         const splitHash = hash.split("#");
         if (splitHash.length === 2) {
             hash = splitHash[1];
@@ -370,7 +345,7 @@ export default class Content extends LightningElement {
         } else {
             window.scrollTo({ top: 0, behavior: "smooth" });
         }
-    }
+    };
 
     renderedCallback() {
         if (this._docRendered) {

package/src/modules/doc/contentLayout/contentLayout.html

@@ -59,6 +59,7 @@
                         value={tocValue}
                     ></dx-toc>
                 </div>
+                <doc-comment-popup></doc-comment-popup>
             </div>
             <div lwc:if={showFooter} class="footer-container">
                 <dx-footer variant="no-signup"></dx-footer>

package/src/modules/doc/lwcContentLayout/lwcContentLayout.html

@@ -59,6 +59,7 @@
                         value={tocValue}
                     ></dx-toc>
                 </div>
+                <doc-comment-popup></doc-comment-popup>
             </div>
             <div lwc:if={showFooter} class="footer-container">
                 <dx-footer variant="no-signup"></dx-footer>

package/src/modules/docHelpers/contentLayoutStyle/contentLayoutStyle.css

@@ -70,6 +70,7 @@ dx-toc {
     margin: auto;
     padding: 0 var(--dx-g-global-header-padding-horizontal);
     margin-bottom: calc(2 * (var(--dx-g-spacing-5xl) + 4px));
+    position: relative;
 }
 
 .content-body {

package/LICENSE

@@ -1,12 +0,0 @@
-Copyright (c) 2020, Salesforce.com, Inc.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.