@salesforcedevs/docs-components 0.0.4 → 0.0.5-edit

package/src/modules/doc/breadcrumbs/breadcrumbs.html

@@ -0,0 +1,58 @@
+<template>
+    <nav role="navigation" aria-label={ariaLabel}>
+        <template if:true={displayCrumbs}>
+            <template if:false={renderSmallVariant}>
+                <doc-breadcrumb-item
+                    href={firstCrumb.href}
+                    label={firstCrumb.label}
+                    breadcrumb-labels={breadcrumbLabels}
+                ></doc-breadcrumb-item>
+                <span class="breadcrumb-item_slash">/</span>
+                <template if:true={renderDropdown}>
+                    <dx-dropdown
+                        analytics-event="custEv_breadcrumbClick"
+                        analytics-payload={ANALYTICS_PAYLOAD}
+                        if:true={renderDropdown}
+                        options={dropdownOptions}
+                        open-on-hover
+                        placement="bottom"
+                        variant="indented"
+                        width="fit-content"
+                    >
+                        <dx-button
+                            aria-label="Open Breadcrumbs Dropdown"
+                            icon-size="large"
+                            icon-symbol="threedots"
+                            variant="tertiary"
+                        ></dx-button>
+                    </dx-dropdown>
+                    <span class="breadcrumb-item_slash">/</span>
+                </template>
+                <template for:each={breadcrumbItems} for:item="breadcrumb">
+                    <doc-breadcrumb-item
+                        href={breadcrumb.href}
+                        key={breadcrumb.id}
+                        label={breadcrumb.label}
+                        level={breadcrumb.level}
+                        breadcrumb-labels={breadcrumbLabels}
+                    ></doc-breadcrumb-item>
+                    <span class="breadcrumb-item_slash" key={breadcrumb.label}>
+                        /
+                    </span>
+                </template>
+                <doc-breadcrumb-item
+                    label={lastCrumb.label}
+                    breadcrumb-labels={breadcrumbLabels}
+                ></doc-breadcrumb-item>
+            </template>
+            <template if:true={renderSmallVariant}>
+                <doc-breadcrumb-item
+                    href={lastLinkCrump.href}
+                    label={lastLinkCrump.label}
+                    breadcrumb-labels={breadcrumbLabels}
+                    variant="back-arrow"
+                ></doc-breadcrumb-item>
+            </template>
+        </template>
+    </nav>
+</template>

package/src/modules/doc/breadcrumbs/breadcrumbs.ts

@@ -0,0 +1,183 @@
+import { LightningElement, api } from "lwc";
+import { Breadcrumb, OptionWithLink } from "typings/custom";
+import { toJson } from "dxUtils/normalizers";
+
+type BreadcrumbConfig = {
+    minWidth: number;
+    crumbsInDropdown: number;
+};
+
+const GAP = 8;
+
+// Unit in pixels based on Salesforce Sans font-family.
+const CONSTANTS = {
+    pixelPerCharacter: 7.7,
+    pixelPerCrumbSpace: GAP * 2 + 8.6,
+    minWidthPerCrumb: 200,
+    dropdownWidth: 32
+};
+
+export default class Breadcrumbs extends LightningElement {
+    @api ariaLabel: string = "Documentation Breadcrumbs";
+
+    @api
+    get breadcrumbs(): Breadcrumb[] {
+        return this._breadcrumbs;
+    }
+
+    set breadcrumbs(value) {
+        this.normalizeAndAssignBreadcrumbs(value);
+        this.calculateBreadcrumbsConfigs();
+        if (this.isRendered) {
+            this.onWidthOrContentChange();
+        }
+    }
+
+    @api
+    get pixelPerCharacter(): number {
+        return this._pixelPerCharacter;
+    }
+
+    set pixelPerCharacter(value: number | string) {
+        this._pixelPerCharacter = +value;
+    }
+
+    private _breadcrumbs: Breadcrumb[] = [];
+    private _pixelPerCharacter = CONSTANTS.pixelPerCharacter;
+    private navWidth = 0;
+    private breadcrumbConfigs: BreadcrumbConfig[] = [];
+    private dropdownOptionAmount? = 0;
+    private isRendered = false;
+
+    private get renderSmallVariant(): boolean {
+        return (
+            !this.dropdownOptionAmount &&
+            this.dropdownOptionAmount !== 0 &&
+            !!this.lastLinkCrump
+        );
+    }
+
+    private get lastLinkCrump(): Breadcrumb {
+        return this.breadcrumbs[this.breadcrumbs.length - 2];
+    }
+
+    private get hasInternalBreadcrumbs(): boolean {
+        return this.breadcrumbs.length > 2;
+    }
+
+    private get breadcrumbItems(): Breadcrumb[] {
+        return this.breadcrumbs!.slice(
+            this.dropdownOptionAmount! + 1,
+            this._breadcrumbs.length - 1
+        );
+    }
+
+    private get renderDropdown(): boolean {
+        return this.hasInternalBreadcrumbs && !!this.dropdownOptionAmount;
+    }
+    private get dropdownOptions(): OptionWithLink[] {
+        return this.breadcrumbs!.slice(1, this.dropdownOptionAmount! + 1).map(
+            (link) => ({
+                id: link.id!,
+                label: link.label,
+                link: { href: link.href! }
+            })
+        );
+    }
+
+    private get displayCrumbs(): boolean {
+        return this.breadcrumbs.length > 1;
+    }
+
+    private get firstCrumb(): Breadcrumb {
+        return this.breadcrumbs[0];
+    }
+
+    private get breadcrumbLabels(): string {
+        return this.breadcrumbs.map((crumb) => crumb.label).join(":");
+    }
+
+    private get lastCrumb(): Breadcrumb {
+        return this.breadcrumbs[this.breadcrumbs.length - 1];
+    }
+
+    // this payload is only used for breadcrumb dropdown
+    private get ANALYTICS_PAYLOAD() {
+        return {
+            element_type: "link",
+            nav_type: "breadcrumb",
+            nav_level: 1
+        };
+    }
+
+    private onWidthOrContentChange = () => {
+        this.navWidth = this.template
+            .querySelector("nav")!
+            .getBoundingClientRect().width;
+        this.updateDropdownOptionAmount();
+    };
+
+    renderedCallback(): void {
+        this.isRendered = true;
+        this.onWidthOrContentChange();
+        window.addEventListener("resize", this.onWidthOrContentChange);
+    }
+
+    disconnectedCallback(): void {
+        window.removeEventListener("resize", this.onWidthOrContentChange);
+    }
+
+    private normalizeAndAssignBreadcrumbs(breadcrumbs?: Breadcrumb[] | string) {
+        if (!breadcrumbs) {
+            return;
+        }
+
+        this._breadcrumbs = toJson(breadcrumbs).map(
+            (crumb: Breadcrumb, index: number) => ({
+                ...crumb,
+                id: crumb.id || crumb.href,
+                level: index
+            })
+        );
+    }
+
+    private updateDropdownOptionAmount(): void {
+        this.dropdownOptionAmount = this.breadcrumbConfigs.find(
+            ({ minWidth }) => minWidth <= this.navWidth
+        )?.crumbsInDropdown;
+    }
+
+    private calculateBreadcrumbsConfigs(): void {
+        this.breadcrumbConfigs = [
+            ...Array(this._breadcrumbs.length - 1).keys()
+        ].map((optionsAmount) => {
+            const breadcrumbs = [...this._breadcrumbs];
+            breadcrumbs.splice(1, optionsAmount);
+            return {
+                crumbsInDropdown: optionsAmount,
+                minWidth: this.reduceBreadcrumbs(
+                    breadcrumbs,
+                    optionsAmount
+                        ? CONSTANTS.dropdownWidth + CONSTANTS.pixelPerCrumbSpace
+                        : 0
+                )
+            };
+        });
+    }
+
+    private reduceBreadcrumbs(
+        breadcrumbs: Breadcrumb[],
+        offset: number = 0
+    ): number {
+        return breadcrumbs.reduce(
+            (previousValue, element) =>
+                previousValue +
+                Math.min(
+                    element.label.length *
+                        (this.pixelPerCharacter || CONSTANTS.pixelPerCharacter),
+                    CONSTANTS.minWidthPerCrumb
+                ),
+            (breadcrumbs.length - 1) * CONSTANTS.pixelPerCrumbSpace + offset
+        );
+    }
+}

package/src/modules/doc/chat/README.md

@@ -0,0 +1,179 @@
+# Sliding Chat Component (doc-chat)
+
+A self-contained sliding chat component with a floating trigger button that can be embedded in any layout, perfect for customer support, documentation help, or any conversational interface.
+
+## Features
+
+- 🎯 **Sliding Component**: Slides in/out with smooth animations
+- 🔘 **Floating Trigger**: Built-in floating button to open chat (bottom-right corner)
+- 💬 **Real-time Chat**: Interactive messaging with typing indicators
+- 🎨 **Modern Design**: Clean, responsive interface with subtle animations
+- ⚙️ **Configurable**: Customizable title, placeholder, and assistant name
+- 📱 **Mobile Friendly**: Full-width on mobile devices
+- ♿ **Accessible**: ARIA labels and keyboard navigation
+- 🎭 **Storybook Ready**: Multiple story variations for testing
+
+## Basic Usage
+
+The component is completely self-contained with a built-in floating trigger button:
+
+```html
+<doc-chat
+    title="Customer Support"
+    placeholder="How can we help you today?"
+    assistant-name="Support Bot"
+    is-open="false"
+    show-timestamp="true"
+></doc-chat>
+```
+
+That's it! The component will automatically show a floating chat button in the bottom-right corner when closed, and slide in the chat interface when opened.
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `title` | String | `"Chat"` | Title displayed in the chat header |
+| `placeholder` | String | `"Type your message..."` | Placeholder text for input field |
+| `assistant-name` | String | `"Assistant"` | Name of the assistant/bot |
+| `disabled` | Boolean | `false` | Disables the chat functionality |
+| `show-timestamp` | Boolean | `false` | Shows timestamps on messages |
+| `is-open` | Boolean | `false` | Controls sidebar visibility |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `openChat()` | Opens the chat sidebar |
+| `closeChat()` | Closes the chat sidebar |
+
+## Events
+
+| Event | Description | Detail |
+|-------|-------------|--------|
+| `chatopened` | Fired when chat is opened | `{ opened: true }` |
+| `chatclosed` | Fired when chat is closed | `{ closed: true }` |
+
+## Integration Example
+
+### Simple Integration (Self-Contained)
+```html
+<!-- The component includes its own trigger button -->
+<doc-chat
+    title="Customer Support"
+    placeholder="How can we help you today?"
+    assistant-name="Support Bot"
+    show-timestamp="true"
+    is-open="false"
+></doc-chat>
+```
+
+### Advanced Integration (With Custom Triggers)
+```html
+<!-- Optional: Custom trigger button -->
+<button id="chat-trigger" onclick="openSupportChat()">
+    💬 Need Help?
+</button>
+
+<!-- Chat component -->
+<doc-chat
+    id="support-chat"
+    title="Customer Support"
+    placeholder="How can we help you today?"
+    assistant-name="Support Bot"
+    show-timestamp="true"
+    is-open="false"
+></doc-chat>
+```
+
+### JavaScript
+```javascript
+// Optional: Custom trigger function
+function openSupportChat() {
+    const chat = document.getElementById('support-chat');
+    chat.openChat();
+}
+
+// Listen for chat events
+document.getElementById('support-chat').addEventListener('chatclosed', (event) => {
+    console.log('Chat was closed');
+});
+
+document.getElementById('support-chat').addEventListener('chatopened', (event) => {
+    console.log('Chat was opened');
+});
+```
+
+## Styling
+
+The component uses CSS custom properties for easy theming:
+
+```css
+doc-chat {
+    --chat-width: 400px;
+    --chat-z-index: 1000;
+    --chat-transition-duration: 0.3s;
+    --chat-header-bg: #f8f9fa;
+    --chat-primary-color: #0066cc;
+    --chat-border-color: #e0e0e0;
+}
+```
+
+## Responsive Behavior
+
+- **Desktop**: Fixed width component (400px)
+- **Tablet**: Full width component
+- **Mobile**: Full width component
+
+## Accessibility
+
+- ARIA labels for screen readers
+- Keyboard navigation support
+- High contrast mode support
+- Reduced motion preferences respected
+
+## Assistant Response Simulation
+
+The component includes a built-in response simulation system that responds to:
+
+- **Greetings**: "Hello", "Hi" → Friendly greeting
+- **Help requests**: "Help" → Assistance offer
+- **Documentation**: "Documentation", "Docs" → Navigation help
+- **General messages**: Contextual responses
+
+### Replacing with Real API
+
+To integrate with a real chat API, replace the `simulateAssistantResponse` method:
+
+```javascript
+// Replace this method in your extended component
+simulateAssistantResponse(userMessage) {
+    // Call your chat API
+    fetch('/api/chat', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ message: userMessage })
+    })
+    .then(response => response.json())
+    .then(data => {
+        this.addMessage(data.response, 'assistant');
+    });
+}
+```
+
+## Browser Support
+
+- Chrome 80+
+- Firefox 72+
+- Safari 13+
+- Edge 80+
+
+## Examples
+
+Check out the Storybook examples for various use cases:
+
+- **Default**: Basic chat setup
+- **With Timestamps**: Shows message timestamps
+- **Interactive Demo**: Fully functional example
+- **Mobile View**: Mobile device simulation
+- **Chat Trigger Example**: Integration patterns