@customviews-js/customviews 1.2.0 → 1.3.0

package/dist/custom-views.js

@@ -1,5 +1,5 @@
 /*!
- * @customviews-js/customviews v1.2.0
+ * @customviews-js/customviews v1.3.0
  * (c) 2025 Chan Ger Teck
  * Released under the MIT License.
  */
@@ -160,7 +160,9 @@
             return url.toString();
         }
         /**
-         * Encode state into URL-safe string (Toggles and Tabs only currently)
+         * Encode state into URL-safe string
+         *
+         * (Covers Toggles, Tabs and Focus currently)
          */
         static encodeState(state) {
             try {
@@ -174,6 +176,10 @@
                 if (state.tabs && Object.keys(state.tabs).length > 0) {
                     compact.g = Object.entries(state.tabs);
                 }
+                // Add focus if present
+                if (state.focus && state.focus.length > 0) {
+                    compact.f = state.focus;
+                }
                 // Convert to JSON and encode
                 const json = JSON.stringify(compact);
                 let encoded;
@@ -195,7 +201,9 @@
             }
         }
         /**
-         * Decode custom state from URL parameter (Toggles and Tabs only currently)
+         * Decode custom state from URL parameter
+         *
+         * (Covers Toggles, Tabs and Focus currently)
          */
         static decodeState(encoded) {
             try {
@@ -234,6 +242,10 @@
                         }
                     }
                 }
+                // Reconstruct Focus
+                if (Array.isArray(compact.f)) {
+                    state.focus = compact.f;
+                }
                 return state;
             }
             catch (error) {
@@ -418,6 +430,12 @@
     </svg>
   `.trim();
     }
+    function getShareIcon() {
+        return `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+            <path fill="currentColor" d="M18 8h-2a1 1 0 0 0 0 2h2v8H6v-8h2a1 1 0 0 0 0-2H6a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8a2 2 0 0 0-2-2z"/>
+            <path fill="currentColor" d="M11 6.41V12a1 1 0 0 0 2 0V6.41l1.29 1.3a1 1 0 0 0 1.42 0a1 1 0 0 0 0-1.42l-3-3a1 1 0 0 0-1.42 0l-3 3a1 1 0 1 0 1.42 1.42L11 6.41z"/>
+          </svg>`;
+    }
 
     // Constants for selectors
     const TABGROUP_SELECTOR$1 = 'cv-tabgroup';
@@ -1382,6 +1400,1185 @@ ${TAB_STYLES}
         document.head.appendChild(style);
     }
 
+    const TOAST_STYLE_ID = 'cv-toast-styles';
+    const TOAST_CLASS = 'cv-toast-notification';
+    const TOAST_STYLES = `
+  .cv-toast-notification {
+    position: fixed;
+    top: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    background-color: #323232;
+    color: white;
+    padding: 12px 24px;
+    border-radius: 4px;
+    z-index: 100000;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+    opacity: 0;
+    transition: opacity 0.3s ease;
+    pointer-events: none; /* Let clicks pass through if needed, though usually it blocks */
+    font-family: system-ui, -apple-system, sans-serif;
+    font-size: 14px;
+  }
+`;
+
+    /**
+     * Manages toast notifications for the application.
+     */
+    class ToastManager {
+        static isStyleInjected = false;
+        static toastEl = null;
+        static navTimeout = null;
+        static fadeTimeout = null;
+        static show(message, duration = 2500) {
+            this.injectStyles();
+            // specific reuse logic
+            if (!this.toastEl) {
+                this.toastEl = document.createElement('div');
+                this.toastEl.className = TOAST_CLASS;
+                document.body.appendChild(this.toastEl);
+            }
+            // Reset state
+            this.toastEl.textContent = message;
+            this.toastEl.style.opacity = '0';
+            this.toastEl.style.display = 'block';
+            // Clear any pending dismissal
+            if (this.navTimeout)
+                clearTimeout(this.navTimeout);
+            if (this.fadeTimeout)
+                clearTimeout(this.fadeTimeout);
+            // Trigger reflow & fade in
+            requestAnimationFrame(() => {
+                if (this.toastEl)
+                    this.toastEl.style.opacity = '1';
+            });
+            // Schedule fade out
+            this.navTimeout = setTimeout(() => {
+                if (this.toastEl)
+                    this.toastEl.style.opacity = '0';
+                this.fadeTimeout = setTimeout(() => {
+                    if (this.toastEl)
+                        this.toastEl.style.display = 'none';
+                }, 300);
+            }, duration);
+        }
+        static injectStyles() {
+            if (this.isStyleInjected)
+                return;
+            if (document.getElementById(TOAST_STYLE_ID)) {
+                this.isStyleInjected = true;
+                return;
+            }
+            const style = document.createElement('style');
+            style.id = TOAST_STYLE_ID;
+            style.innerHTML = TOAST_STYLES;
+            document.head.appendChild(style);
+            this.isStyleInjected = true;
+        }
+    }
+
+    /**
+     * Engine for generating and resolving robust anchors.
+     *
+     * It implements a simple anchor generation and resolution algorithm that uses a combination of
+     * structural, contextual, and content-based hints to generate a unique anchor for a given DOM element.
+     *
+     * The anchor is generated by first creating an AnchorDescriptor for the element, which contains
+     * information about the element's tag, index, parent ID, and text content. This descriptor is then
+     * serialized into a URL-safe string using a minification algorithm.
+     *
+     * The anchor is then resolved by searching for the element in the DOM using the serialized string.
+     *
+     */
+    class AnchorEngine {
+        /**
+         * Generates a simple hash code for a string.
+         *
+         * It takes each character's Unicode code point and uses it to update the hash value.
+         */
+        static hashCode(str) {
+            let hash = 0;
+            if (str.length === 0)
+                return hash;
+            for (let i = 0; i < str.length; i++) {
+                const char = str.charCodeAt(i);
+                hash = ((hash << 5) - hash) + char;
+                hash = hash & hash; // Convert to 32bit integer
+            }
+            return hash;
+        }
+        /**
+         * Normalizes text content by removing excessive whitespace.
+         *
+         * It trims leading and trailing whitespace and replaces multiple spaces with a single space.
+         */
+        static normalizeText(text) {
+            return text.trim().replace(/\s+/g, ' ');
+        }
+        /**
+         * Creates an AnchorDescriptor for a given DOM element.
+         */
+        static createDescriptor(el) {
+            const tag = el.tagName;
+            const textContent = el.textContent || "";
+            const normalizedText = this.normalizeText(textContent);
+            // Find nearest parent with an ID
+            let parentId;
+            let parent = el.parentElement;
+            while (parent) {
+                if (parent.id) {
+                    parentId = parent.id;
+                    break;
+                }
+                parent = parent.parentElement;
+            }
+            // Calculate index relative to the container (either the found parent or document.body)
+            const container = parent || document.body;
+            const siblings = Array.from(container.querySelectorAll(tag));
+            // Index is the position of the element in the list of siblings, where siblings are those of the same tag.
+            const index = siblings.indexOf(el);
+            const descriptor = {
+                tag,
+                index: index !== -1 ? index : 0,
+                textSnippet: normalizedText.substring(0, 32),
+                textHash: this.hashCode(normalizedText)
+            };
+            if (parentId) {
+                descriptor.parentId = parentId;
+            }
+            return descriptor;
+        }
+        /**
+         * Serializes a list of AnchorDescriptors into a URL-safe string.
+         */
+        static serialize(descriptors) {
+            // Minify keys for compactness
+            const minified = descriptors.map(d => ({
+                t: d.tag,
+                i: d.index,
+                p: d.parentId,
+                s: d.textSnippet,
+                h: d.textHash
+            }));
+            const json = JSON.stringify(minified);
+            // Base64 encode
+            return btoa(encodeURIComponent(json));
+        }
+        /**
+         * Deserializes a URL-safe string back into a list of AnchorDescriptors.
+         */
+        static deserialize(encoded) {
+            try {
+                const json = decodeURIComponent(atob(encoded));
+                const minified = JSON.parse(json);
+                return minified.map((m) => ({
+                    tag: m.t,
+                    index: m.i,
+                    parentId: m.p,
+                    textSnippet: m.s,
+                    textHash: m.h
+                }));
+            }
+            catch (e) {
+                console.error("Failed to deserialize anchor:", e);
+                return [];
+            }
+        }
+        /**
+         * Finds the best DOM element match for a descriptor.
+         */
+        static resolve(root, descriptor) {
+            // 1. Scope
+            let scope = root;
+            if (descriptor.parentId) {
+                const foundParent = root.querySelector(`#${descriptor.parentId}`);
+                if (foundParent instanceof HTMLElement) {
+                    scope = foundParent;
+                }
+                else {
+                    // Fallback: if parent ID not found, search global root - document.body
+                    const globalParent = document.getElementById(descriptor.parentId);
+                    if (globalParent) {
+                        scope = globalParent;
+                    }
+                }
+            }
+            // 2. Candidate Search
+            const candidates = Array.from(scope.querySelectorAll(descriptor.tag));
+            // 3. Scoring
+            let bestMatch = null;
+            let highestScore = 0;
+            candidates.forEach((candidate) => {
+                let score = 0;
+                const text = this.normalizeText(candidate.textContent || "");
+                // Exact Text Match (Hash check is faster proxy for full string compare, but let's check hash first)
+                if (this.hashCode(text) === descriptor.textHash) {
+                    score += 50;
+                }
+                else if (text.startsWith(descriptor.textSnippet)) {
+                    // Fuzzy Text Match (Snippet) - +30 score
+                    score += 30;
+                }
+                // Structural Match (Index)
+                // We need to re-calculate index of this candidate to compare with descriptor.index
+                // The descriptor.index is relative to the *found* parentId container.
+                // So we must compare index within the scope we are searching.
+                const siblings = Array.from(scope.querySelectorAll(descriptor.tag));
+                const index = siblings.indexOf(candidate);
+                if (index === descriptor.index) {
+                    score += 10;
+                }
+                if (score > highestScore) {
+                    highestScore = score;
+                    bestMatch = candidate;
+                }
+            });
+            // 4. Winner
+            if (highestScore > 30) {
+                return bestMatch;
+            }
+            return null;
+        }
+    }
+
+    const SHARE_MODE_STYLE_ID = 'cv-share-mode-styles';
+    const FLOATING_ACTION_BAR_ID = 'cv-floating-action-bar';
+    const HOVER_HELPER_ID = 'cv-hover-helper';
+    const HIGHLIGHT_TARGET_CLASS = 'cv-highlight-target';
+    const SELECTED_CLASS = 'cv-share-selected';
+    /**
+     * CSS styles to be injected during Share Mode.
+     */
+    const SHARE_MODE_STYLES = `
+  body.cv-share-mode {
+    cursor: default;
+  }
+
+  /* Highlight outlines */
+  .${HIGHLIGHT_TARGET_CLASS} {
+    outline: 2px dashed #0078D4 !important;
+    outline-offset: 2px;
+    cursor: crosshair;
+  }
+
+  .${SELECTED_CLASS} {
+    outline: 3px solid #005a9e !important;
+    outline-offset: 2px;
+    background-color: rgba(0, 120, 212, 0.05);
+  }
+
+  /* Floating Action Bar */
+  #${FLOATING_ACTION_BAR_ID} {
+    position: fixed;
+    bottom: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    background-color: #2c2c2c;
+    color: #f1f1f1;
+    border-radius: 8px;
+    padding: 12px 20px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    z-index: 99999;
+    font-family: system-ui, -apple-system, sans-serif;
+    font-size: 14px;
+    border: 1px solid #4a4a4a;
+  }
+
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button {
+    background-color: #0078D4;
+    color: white;
+    border: none;
+    padding: 8px 14px;
+    border-radius: 5px;
+    cursor: pointer;
+    font-weight: 500;
+    transition: background-color 0.2s;
+  }
+  
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button:hover {
+    background-color: #005a9e;
+  }
+
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.clear {
+    background-color: #5a5a5a;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.clear:hover {
+    background-color: #4a4a4a;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.clear:hover {
+    background-color: #4a4a4a;
+  }
+
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.preview {
+    background-color: #106ebe;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.preview:hover {
+    background-color: #005a9e;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.exit {
+    background-color: #d13438;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.exit:hover {
+    background-color: #a42628;
+  }
+
+  /* Hover Helper (Smart Label & Level Up) */
+  #${HOVER_HELPER_ID} {
+    position: fixed;
+    z-index: 99999;
+    background-color: #333;
+    color: white;
+    padding: 4px 8px;
+    border-radius: 4px;
+    font-size: 12px;
+    font-family: monospace;
+    display: none;
+    pointer-events: auto; /* Allow clicking buttons inside */
+    align-items: center;
+    gap: 8px;
+    box-shadow: 0 2px 5px rgba(0,0,0,0.2);
+  }
+
+  #${HOVER_HELPER_ID} button {
+    background: #555;
+    border: none;
+    color: white;
+    border-radius: 3px;
+    cursor: pointer;
+    padding: 2px 6px;
+    font-size: 14px;
+    line-height: 1;
+  }
+  #${HOVER_HELPER_ID} button:hover {
+    background: #777;
+  }
+
+`;
+
+    const CV_CUSTOM_ELEMENTS = 'cv-tabgroup, cv-toggle';
+    const SHAREABLE_SELECTOR = 'div, p, blockquote, pre, li, h1, h2, h3, h4, h5, h6, [data-share], ' + CV_CUSTOM_ELEMENTS;
+    /**
+     * Manages the "Share Mode" for creating custom focus links.
+     * Implementing Robust Granular Sharing with "Innermost Wins" and "Level Up" UI.
+     */
+    class ShareManager {
+        isActive = false;
+        selectedElements = new Set();
+        floatingBarEl = null;
+        helperEl = null;
+        currentHoverTarget = null;
+        excludedTags;
+        excludedIds;
+        boundHandleHover;
+        boundHandleClick;
+        boundHandleKeydown;
+        constructor(options) {
+            this.excludedTags = new Set(options.excludedTags.map(t => t.toUpperCase()));
+            this.excludedIds = new Set(options.excludedIds);
+            this.boundHandleHover = this.handleHover.bind(this);
+            this.boundHandleClick = this.handleClick.bind(this);
+            this.boundHandleKeydown = this.handleKeydown.bind(this);
+        }
+        listeners = [];
+        addStateChangeListener(listener) {
+            this.listeners.push(listener);
+        }
+        removeStateChangeListener(listener) {
+            this.listeners = this.listeners.filter(l => l !== listener);
+        }
+        notifyListeners() {
+            this.listeners.forEach(listener => listener(this.isActive));
+        }
+        toggleShareMode() {
+            this.isActive = !this.isActive;
+            if (this.isActive) {
+                this.activate();
+            }
+            else {
+                this.cleanup();
+            }
+            this.notifyListeners();
+        }
+        /**
+         * Activates the share mode.
+         * Injects styles, creates floating bar, and helper element.
+         * Adds event listeners for hover and click.
+         */
+        activate() {
+            this.injectStyles();
+            this.createFloatingBar();
+            this.helperEl = this.createHelperPopover();
+            // Event Listeners
+            document.addEventListener('mouseover', this.boundHandleHover, true);
+            document.addEventListener('click', this.boundHandleClick, true);
+            document.addEventListener('keydown', this.boundHandleKeydown, true);
+        }
+        injectStyles() {
+            const styleElement = document.createElement('style');
+            styleElement.id = SHARE_MODE_STYLE_ID;
+            styleElement.innerHTML = SHARE_MODE_STYLES;
+            document.head.appendChild(styleElement);
+        }
+        /**
+         * Creates the hover helper element that shows up when hovering over a shareable element.
+         */
+        createHelperPopover() {
+            const div = document.createElement('div');
+            div.id = HOVER_HELPER_ID;
+            div.innerHTML = `
+      <span id="cv-helper-tag">TAG</span>
+      <button id="cv-helper-select-btn" title="Select This Element">✓</button>
+      <button id="cv-helper-up-btn" title="Select Parent">↰</button>
+    `;
+            document.body.appendChild(div);
+            // Select parent button
+            div.querySelector('#cv-helper-up-btn')?.addEventListener('click', (e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                this.handleSelectParent();
+            });
+            // Select element button
+            div.querySelector('#cv-helper-select-btn')?.addEventListener('click', (e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                if (this.currentHoverTarget) {
+                    this.toggleSelection(this.currentHoverTarget);
+                }
+            });
+            return div;
+        }
+        /**
+         * Handles mouse hover events.
+         *
+         * This function is called when the user hovers over an element.
+         * It checks if the element is shareable and highlights it.
+         * If a parent element is already selected, it highlights the parent instead,
+         * allowing the helper to remain visible for the selected parent.
+         *
+         * @param e The mouse event triggered by the hover.
+         */
+        handleHover(e) {
+            if (!this.isActive)
+                return;
+            // Check if we are hovering over the helper itself
+            if (this.helperEl && this.helperEl.contains(e.target)) {
+                return;
+            }
+            const target = e.target;
+            // Exclude by Tag or ID
+            const upperTag = target.tagName.toUpperCase();
+            if (this.excludedTags.has(upperTag) || (target.id && this.excludedIds.has(target.id))) {
+                return;
+            }
+            // Check closest excluded (for nested elements in excluded regions)
+            let ancestor = target.parentElement;
+            while (ancestor) {
+                if (this.excludedTags.has(ancestor.tagName.toUpperCase()) || (ancestor.id && this.excludedIds.has(ancestor.id))) {
+                    return;
+                }
+                ancestor = ancestor.parentElement;
+            }
+            // Find closest shareable parent element
+            const shareablePart = target.closest(SHAREABLE_SELECTOR);
+            if (!shareablePart) {
+                this.clearHover();
+                return;
+            }
+            // Cast to HTMLElement
+            const finalTarget = shareablePart;
+            // Check if any ancestor is already selected. If so, do NOT highlight this child.
+            // Instead, highlight (or keep highlighted) the SELECTED PARENT so the user can see the helper for it.
+            let parent = finalTarget.parentElement;
+            let selectedAncestor = null;
+            // Loop outwards until we find a selected parent or reach the top
+            while (parent) {
+                if (this.selectedElements.has(parent)) {
+                    selectedAncestor = parent;
+                    break;
+                }
+                parent = parent.parentElement;
+            }
+            if (selectedAncestor) {
+                // If we are hovering deep inside a selected block, show the helper for that block
+                this.setNewHoverTarget(selectedAncestor);
+                return;
+            }
+            // stop bubbling to parent
+            // when element found for highlight
+            e.stopPropagation();
+            // If we are already on this target, do nothing (and keep it selected/highlighted)
+            if (this.currentHoverTarget === finalTarget)
+                return;
+            // Highlight
+            this.setNewHoverTarget(finalTarget);
+        }
+        setNewHoverTarget(target) {
+            if (this.currentHoverTarget) {
+                this.currentHoverTarget.classList.remove(HIGHLIGHT_TARGET_CLASS);
+            }
+            this.currentHoverTarget = target;
+            this.currentHoverTarget.classList.add(HIGHLIGHT_TARGET_CLASS);
+            this.positionHelper(target);
+        }
+        positionHelper(target) {
+            if (!this.helperEl)
+                return;
+            const rect = target.getBoundingClientRect();
+            const tagLabel = this.helperEl.querySelector('#cv-helper-tag');
+            const upBtn = this.helperEl.querySelector('#cv-helper-up-btn');
+            if (tagLabel)
+                tagLabel.textContent = target.tagName;
+            // Position at top-right of the element
+            // Prevent going off-screen
+            let top = rect.top - 20;
+            if (top < 0)
+                top = rect.top + 10; // Flip down if too close to top
+            let left = rect.right - 80;
+            if (left < 0)
+                left = 10;
+            this.helperEl.style.display = 'flex';
+            this.helperEl.style.top = `${top}px`;
+            this.helperEl.style.left = `${left}px`;
+            // Update Select Button State (Tick or Cross)
+            const selectBtn = this.helperEl.querySelector('#cv-helper-select-btn');
+            if (selectBtn) {
+                if (this.selectedElements.has(target)) {
+                    selectBtn.textContent = '✕';
+                    selectBtn.title = 'Deselect This Element';
+                    selectBtn.style.backgroundColor = '#d13438'; // Reddish
+                }
+                else {
+                    selectBtn.textContent = '✓';
+                    selectBtn.title = 'Select This Element';
+                    selectBtn.style.backgroundColor = ''; // Reset
+                }
+            }
+            // Ancestry Check
+            const parent = target.parentElement;
+            const parentIsShareable = parent && parent.matches(SHAREABLE_SELECTOR);
+            if (parentIsShareable) {
+                upBtn.style.display = 'inline-block';
+            }
+            else {
+                upBtn.style.display = 'none';
+            }
+        }
+        handleSelectParent() {
+            if (this.currentHoverTarget && this.currentHoverTarget.parentElement) {
+                const parent = this.currentHoverTarget.parentElement;
+                if (parent.matches(SHAREABLE_SELECTOR)) {
+                    this.setNewHoverTarget(parent);
+                }
+            }
+        }
+        handleClick(e) {
+            if (!this.isActive)
+                return;
+            // If clicking helper
+            if (this.helperEl && this.helperEl.contains(e.target))
+                return;
+            // If clicking floating bar
+            if (this.floatingBarEl && this.floatingBarEl.contains(e.target))
+                return;
+            e.preventDefault();
+            e.stopPropagation();
+            if (this.currentHoverTarget) {
+                this.toggleSelection(this.currentHoverTarget);
+            }
+        }
+        handleKeydown(e) {
+            if (!this.isActive)
+                return;
+            if (e.key === 'Escape') {
+                e.preventDefault();
+                e.stopPropagation();
+                this.toggleShareMode();
+            }
+        }
+        /**
+         * Toggles the selection state of a given HTML element.
+         * Implements selection logic:
+         * - If an ancestor of the element is already selected, the click is ignored.
+         * - If the element being selected is a parent of already selected elements, those children are deselected.
+         * @param el The HTMLElement to toggle selection for.
+         */
+        toggleSelection(el) {
+            if (this.selectedElements.has(el)) {
+                this.selectedElements.delete(el);
+                el.classList.remove(SELECTED_CLASS);
+            }
+            else {
+                // Selection Logic
+                // Scenario A: Selecting a Parent -> Remove children selected while selecting parent
+                // Scenario B: Selecting a Child -> Ignore if ancestor selected (or handle)
+                // B. Check if any ancestor is already selected, return if any (Scenario B)
+                let parent = el.parentElement;
+                while (parent) {
+                    if (this.selectedElements.has(parent)) {
+                        // Ancestor is selected. Ignore click.
+                        return;
+                    }
+                    parent = parent.parentElement;
+                }
+                // A. Check if any children are selected (Scenario A)
+                // We must iterate over currently selected elements
+                const toRemove = [];
+                this.selectedElements.forEach(selected => {
+                    if (el.contains(selected) && el !== selected) {
+                        toRemove.push(selected);
+                    }
+                });
+                toRemove.forEach(child => {
+                    this.selectedElements.delete(child);
+                    child.classList.remove(SELECTED_CLASS);
+                });
+                // Add new selection
+                this.selectedElements.add(el);
+                el.classList.add(SELECTED_CLASS);
+            }
+            this.updateFloatingBarCount();
+        }
+        createFloatingBar() {
+            const bar = document.createElement('div');
+            bar.id = FLOATING_ACTION_BAR_ID;
+            bar.innerHTML = `
+      <span id="cv-selected-count">0 items selected</span>
+      <button class="cv-action-button clear">Clear All</button>
+      <button class="cv-action-button preview">Preview</button>
+      <button class="cv-action-button generate">Generate Link</button>
+      <button class="cv-action-button exit">Exit</button>
+    `;
+            document.body.appendChild(bar);
+            this.floatingBarEl = bar;
+            bar.querySelector('.clear')?.addEventListener('click', () => this.clearAll());
+            bar.querySelector('.preview')?.addEventListener('click', () => this.previewLink());
+            bar.querySelector('.generate')?.addEventListener('click', () => this.generateLink());
+            bar.querySelector('.exit')?.addEventListener('click', () => this.toggleShareMode());
+        }
+        updateFloatingBarCount() {
+            if (this.floatingBarEl) {
+                const countElement = this.floatingBarEl.querySelector('#cv-selected-count');
+                if (countElement) {
+                    const count = this.selectedElements.size;
+                    countElement.textContent = `${count} item${count === 1 ? '' : 's'} selected`;
+                }
+            }
+        }
+        clearAll() {
+            this.selectedElements.forEach(el => el.classList.remove('cv-share-selected'));
+            this.selectedElements.clear();
+            this.updateFloatingBarCount();
+        }
+        getShareUrl() {
+            if (this.selectedElements.size === 0) {
+                return null;
+            }
+            const descriptors = Array.from(this.selectedElements).map(el => AnchorEngine.createDescriptor(el));
+            const serialized = AnchorEngine.serialize(descriptors);
+            const url = new URL(window.location.href);
+            url.searchParams.set('cv-focus', serialized);
+            return url;
+        }
+        async generateLink() {
+            const url = this.getShareUrl();
+            if (!url) {
+                ToastManager.show('Please select at least one item.');
+                return;
+            }
+            try {
+                await navigator.clipboard.writeText(url.toString());
+                ToastManager.show('Link copied to clipboard!');
+            }
+            catch (e) {
+                console.error('Clipboard failed', e);
+                ToastManager.show('Failed to copy link.');
+            }
+        }
+        previewLink() {
+            const url = this.getShareUrl();
+            if (!url) {
+                ToastManager.show('Please select at least one item.');
+                return;
+            }
+            window.open(url.toString(), '_blank');
+        }
+        clearHover() {
+            if (this.currentHoverTarget) {
+                this.currentHoverTarget.classList.remove(HIGHLIGHT_TARGET_CLASS);
+                this.currentHoverTarget = null;
+            }
+            if (this.helperEl) {
+                this.helperEl.style.display = 'none';
+            }
+        }
+        cleanup() {
+            document.body.classList.remove('cv-share-mode');
+            this.clearAll();
+            const style = document.getElementById(SHARE_MODE_STYLE_ID);
+            if (style)
+                document.head.removeChild(style);
+            if (this.floatingBarEl) {
+                document.body.removeChild(this.floatingBarEl);
+                this.floatingBarEl = null;
+            }
+            if (this.helperEl) {
+                document.body.removeChild(this.helperEl);
+                this.helperEl = null;
+            }
+            if (this.currentHoverTarget) {
+                this.currentHoverTarget.classList.remove(HIGHLIGHT_TARGET_CLASS);
+                this.currentHoverTarget = null;
+            }
+            document.removeEventListener('mouseover', this.boundHandleHover, true);
+            document.removeEventListener('click', this.boundHandleClick, true);
+            document.removeEventListener('keydown', this.boundHandleKeydown, true);
+            this.isActive = false;
+        }
+    }
+
+    const SHARE_BUTTON_ID = 'cv-share-button';
+    const SHARE_BUTTON_STYLES = `
+  #${SHARE_BUTTON_ID} {
+    position: fixed;
+    bottom: 20px;
+    right: 100px;
+    width: 50px;
+    height: 50px;
+    border-radius: 50%;
+    background-color: #007bff; /* Primary Blue */
+    color: white;
+    border: none;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0 1px 3px rgba(0, 0, 0, 0.08); /* Drop shadow */
+    z-index: 9998; /* Below modals (9999) but above content */
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: opacity 0.3s ease, transform 0.3s ease, background-color 0.2s;
+    opacity: 1;
+    transform: scale(1);
+    padding: 0;
+    margin: 0;
+  }
+
+  #${SHARE_BUTTON_ID}:hover {
+    background-color: #0056b3; /* Darker blue on hover */
+    transform: scale(1.05);
+  }
+
+  #${SHARE_BUTTON_ID}:active {
+    transform: scale(0.95);
+  }
+
+  #${SHARE_BUTTON_ID}.cv-hidden {
+    opacity: 0;
+    pointer-events: none;
+    transform: scale(0.8);
+  }
+
+  @media print {
+    #${SHARE_BUTTON_ID} {
+      display: none !important;
+    }
+  }
+
+  #${SHARE_BUTTON_ID} svg {
+    width: 24px;
+    height: 24px;
+    fill: currentColor;
+  }
+`;
+
+    class ShareButton {
+        shareManager;
+        button = null;
+        boundHandleClick;
+        constructor(shareManager) {
+            this.shareManager = shareManager;
+            this.boundHandleClick = () => this.shareManager.toggleShareMode();
+        }
+        init() {
+            if (this.button)
+                return;
+            this.injectStyles();
+            this.button = this.createButton();
+            document.body.appendChild(this.button);
+            // Subscribe to share manager state changes
+            this.shareManager.addStateChangeListener((isActive) => {
+                this.setShareModeActive(isActive);
+            });
+        }
+        destroy() {
+            if (this.button) {
+                this.button.remove();
+                this.button = null;
+            }
+        }
+        createButton() {
+            const btn = document.createElement('button');
+            btn.id = SHARE_BUTTON_ID;
+            btn.setAttribute('aria-label', 'Share specific sections');
+            btn.title = 'Select sections to share';
+            // Using the link icon from utils, ensuring it's white via CSS currentColor
+            btn.innerHTML = getShareIcon();
+            btn.addEventListener('click', this.boundHandleClick);
+            return btn;
+        }
+        injectStyles() {
+            if (!document.getElementById('cv-share-button-styles')) {
+                const style = document.createElement('style');
+                style.id = 'cv-share-button-styles';
+                style.textContent = SHARE_BUTTON_STYLES;
+                document.head.appendChild(style);
+            }
+        }
+        setShareModeActive(isActive) {
+            if (!this.button)
+                return;
+            if (isActive) {
+                this.button.classList.add('cv-hidden');
+            }
+            else {
+                this.button.classList.remove('cv-hidden');
+            }
+        }
+    }
+
+    const FOCUS_MODE_STYLE_ID = 'cv-focus-mode-styles';
+    const BODY_FOCUS_CLASS = 'cv-focus-mode';
+    const HIDDEN_CLASS = 'cv-focus-hidden';
+    const FOCUSED_CLASS = 'cv-focused-element';
+    const DIVIDER_CLASS = 'cv-context-divider';
+    const EXIT_BANNER_ID = 'cv-exit-focus-banner';
+    const styles = `
+  body.${BODY_FOCUS_CLASS} {
+     /* e.g. potentially hide scrollbars or adjust layout */
+  }
+
+  .${HIDDEN_CLASS} {
+    display: none !important;
+  }
+
+  .${FOCUSED_CLASS} {
+    /* No visual style for focused elements, just logic class for now. Can add borders for debugging*/
+  }
+
+  .${DIVIDER_CLASS} {
+    padding: 12px;
+    margin: 16px 0;
+    background-color: #f8f8f8;
+    border-top: 1px dashed #ccc;
+    border-bottom: 1px dashed #ccc;
+    color: #555;
+    text-align: center;
+    cursor: pointer;
+    font-family: system-ui, sans-serif;
+    font-size: 13px;
+    transition: background-color 0.2s;
+  }
+  .${DIVIDER_CLASS}:hover {
+    background-color: #e8e8e8;
+    color: #333;
+  }
+
+  #${EXIT_BANNER_ID} {
+    position: sticky;
+    top: 0;
+    left: 0;
+    right: 0;
+    background-color: #0078D4;
+    color: white;
+    padding: 10px 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 16px;
+    z-index: 100000;
+    font-family: system-ui, sans-serif;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+  }
+
+  #${EXIT_BANNER_ID} button {
+    background: white;
+    color: #0078D4;
+    border: none;
+    padding: 4px 12px;
+    border-radius: 4px;
+    cursor: pointer;
+    font-weight: 600;
+  }
+  #${EXIT_BANNER_ID} button:hover {
+    background: #f0f0f0;
+  }
+`;
+    const FOCUS_MODE_STYLES = styles;
+
+    /**
+     * Manages the "Focus Mode" (Presentation View).
+     * Parses the URL for robust anchors, resolves them, hides irrelevant content, and inserts context dividers.
+     */
+    const FOCUS_PARAM = 'cv-focus';
+    class FocusManager {
+        rootEl;
+        hiddenElements = new Set();
+        dividers = [];
+        exitBanner = null;
+        excludedTags;
+        excludedIds;
+        constructor(rootEl, options) {
+            this.rootEl = rootEl;
+            this.excludedTags = new Set(options.excludedTags.map(t => t.toUpperCase()));
+            this.excludedIds = new Set(options.excludedIds);
+        }
+        /**
+         * Initializes the Focus Manager. Checks URL for focus parameter.
+         */
+        init() {
+            this.handleUrlChange();
+        }
+        handleUrlChange() {
+            const urlParams = new URLSearchParams(window.location.search);
+            const encodedDescriptors = urlParams.get(FOCUS_PARAM);
+            if (encodedDescriptors) {
+                this.applyFocusMode(encodedDescriptors);
+            }
+            else {
+                // encoding missing, ensure we exit focus mode if active
+                if (document.body.classList.contains(BODY_FOCUS_CLASS)) {
+                    this.exitFocusMode();
+                }
+            }
+        }
+        /**
+         * Applies Focus Mode based on encoded descriptors.
+         */
+        applyFocusMode(encodedDescriptors) {
+            const descriptors = AnchorEngine.deserialize(encodedDescriptors);
+            if (!descriptors || descriptors.length === 0)
+                return;
+            // Resolve anchors to DOM elements
+            const targets = [];
+            descriptors.forEach(desc => {
+                const el = AnchorEngine.resolve(this.rootEl, desc);
+                if (el) {
+                    targets.push(el);
+                }
+            });
+            if (targets.length === 0) {
+                ToastManager.show("Some shared sections could not be found.");
+                return;
+            }
+            if (targets.length < descriptors.length) {
+                ToastManager.show("Some shared sections could not be found.");
+            }
+            this.injectStyles();
+            document.body.classList.add(BODY_FOCUS_CLASS);
+            this.renderFocusedView(targets);
+            this.showExitBanner();
+        }
+        injectStyles() {
+            if (document.getElementById(FOCUS_MODE_STYLE_ID))
+                return;
+            const style = document.createElement('style');
+            style.id = FOCUS_MODE_STYLE_ID;
+            style.textContent = FOCUS_MODE_STYLES;
+            document.head.appendChild(style);
+        }
+        /**
+         * Hides irrelevant content and adds dividers.
+         */
+        renderFocusedView(targets) {
+            // 1. Mark targets
+            targets.forEach(t => t.classList.add(FOCUSED_CLASS));
+            // 2. We need to hide siblings of targets (and their ancestors up to root generally, 
+            // but "siblings between focused zones" suggests we are mostly looking at a flat list or specific nesting).
+            //
+            // "All sibling elements between the focused zones are collapsed and hidden."
+            // "If a user selects a parent element, all of its child elements must be visible."
+            //
+            // Algorithm:
+            // Walk up from each target to finding the common container? 
+            // Or just assume targets are somewhat related.
+            //
+            // Let's implement a robust "Hide Siblings" approach.
+            // For every target, we ensure it is visible.
+            // We look at its siblings. If a sibling is NOT a target AND NOT an ancestor of a target, we hide it.
+            // We need to identify all "Keep Visible" elements (targets + ancestors)
+            const keepVisible = new Set();
+            targets.forEach(t => {
+                let curr = t;
+                while (curr && curr !== document.body && curr !== document.documentElement) {
+                    keepVisible.add(curr);
+                    curr = curr.parentElement;
+                }
+            });
+            // Now iterate through siblings of "Keep Visible" elements?
+            // Actually, we can just walk the tree or iterate siblings of targets/ancestors?
+            //
+            // Improved Algorithm: 
+            // 1. Collect all direct siblings of every element in keepVisible set.
+            // 2. If a sibling is NOT in keepVisible, hide it.
+            // To avoid processing the entire DOM, we start from targets and walk up.
+            keepVisible.forEach(el => {
+                if (el === document.body)
+                    return; // Don't hide siblings of body (scripts etc) unless we are sure.
+                // Actually usually we want to hide siblings of the content container.
+                const parent = el.parentElement;
+                if (!parent)
+                    return;
+                // FIX: "Parent Dominance"
+                // If the parent itself is a target (or we otherwise decided its whole content is meaningful),
+                // then we should NOT hide anything inside it.
+                // We check if 'parent' is one of the explicitly resolved targets.
+                // We can check if it has the FOCUSED_CLASS class, since we added it in step 1.
+                if (parent.classList.contains(FOCUSED_CLASS)) {
+                    return;
+                }
+                // Using children because we want element nodes
+                Array.from(parent.children).forEach(child => {
+                    if (child instanceof HTMLElement && !keepVisible.has(child)) {
+                        this.hideElement(child);
+                    }
+                });
+            });
+            // 3. Insert Dividers
+            // We process each container that has hidden elements
+            const processedContainers = new Set();
+            keepVisible.forEach(el => {
+                const parent = el.parentElement;
+                if (parent && !processedContainers.has(parent)) {
+                    this.insertDividersForContainer(parent);
+                    processedContainers.add(parent);
+                }
+            });
+        }
+        hideElement(el) {
+            if (this.hiddenElements.has(el))
+                return; // Already hidden
+            // Exclude by Tag
+            if (this.excludedTags.has(el.tagName.toUpperCase()))
+                return;
+            // Exclude by ID (if strictly matching)
+            if (el.id && this.excludedIds.has(el.id))
+                return;
+            // Also don't hide things that are aria-hidden
+            if (el.getAttribute('aria-hidden') === 'true')
+                return;
+            // Exclude Toast Notification
+            if (el.classList.contains(TOAST_CLASS))
+                return;
+            // We check if it is already hidden (e.g. by previous focus mode run? No, isActive check handles that)
+            // Just mark it.
+            el.classList.add(HIDDEN_CLASS);
+            this.hiddenElements.add(el);
+        }
+        insertDividersForContainer(container) {
+            const children = Array.from(container.children);
+            let hiddenCount = 0;
+            let hiddenGroupStart = null;
+            children.forEach((child) => {
+                if (child.classList.contains(HIDDEN_CLASS)) {
+                    if (hiddenCount === 0)
+                        hiddenGroupStart = child;
+                    hiddenCount++;
+                }
+                else {
+                    // Found a visible element. Was there a hidden group before this?
+                    if (hiddenCount > 0 && hiddenGroupStart) {
+                        this.createDivider(container, hiddenGroupStart, hiddenCount);
+                        hiddenCount = 0;
+                        hiddenGroupStart = null;
+                    }
+                }
+            });
+            // Trailing hidden group
+            if (hiddenCount > 0 && hiddenGroupStart) {
+                this.createDivider(container, hiddenGroupStart, hiddenCount);
+            }
+        }
+        createDivider(container, insertBeforeEl, count) {
+            const divider = document.createElement('div');
+            divider.className = DIVIDER_CLASS;
+            divider.textContent = `... ${count} section${count > 1 ? 's' : ''} hidden (Click to expand) ...`;
+            divider.onclick = () => this.expandContext(insertBeforeEl, count, divider);
+            container.insertBefore(divider, insertBeforeEl);
+            this.dividers.push(divider);
+        }
+        expandContext(firstHidden, count, divider) {
+            // Divider is inserted BEFORE firstHidden.
+            // So firstHidden is the first element to reveal.
+            let curr = firstHidden;
+            let expanded = 0;
+            while (curr && expanded < count) {
+                if (curr instanceof HTMLElement && curr.classList.contains(HIDDEN_CLASS)) {
+                    curr.classList.remove(HIDDEN_CLASS);
+                    this.hiddenElements.delete(curr);
+                }
+                curr = curr.nextElementSibling;
+                // Note: If nested dividers or other elements exist, they shouldn't count?
+                // "Children" iteration in insertDividers covered direct children.
+                // sibling iteration also covers direct children.
+                // We assume contiguous hidden siblings.
+                expanded++;
+            }
+            divider.remove();
+            const idx = this.dividers.indexOf(divider);
+            if (idx > -1)
+                this.dividers.splice(idx, 1);
+            // If no more hidden elements, remove the banner
+            if (this.hiddenElements.size === 0) {
+                this.removeExitBanner();
+            }
+        }
+        removeExitBanner() {
+            if (this.exitBanner) {
+                this.exitBanner.remove();
+                this.exitBanner = null;
+            }
+        }
+        /**
+         * Override of renderFocusedView with robust logic
+         */
+        // (We use the class method `renderFocusedView` and internal helpers)
+        showExitBanner() {
+            if (document.getElementById(EXIT_BANNER_ID))
+                return;
+            const banner = document.createElement('div');
+            banner.id = EXIT_BANNER_ID;
+            banner.innerHTML = `
+        <span>You are viewing a focused selection.</span>
+        <button id="cv-exit-focus-btn">Show Full Page</button>
+      `;
+            document.body.prepend(banner); // Top of body
+            banner.querySelector('button')?.addEventListener('click', () => this.exitFocusMode());
+            this.exitBanner = banner;
+        }
+        exitFocusMode() {
+            document.body.classList.remove(BODY_FOCUS_CLASS);
+            // Show all hidden elements
+            this.hiddenElements.forEach(el => el.classList.remove(HIDDEN_CLASS));
+            this.hiddenElements.clear();
+            // Remove dividers
+            this.dividers.forEach(d => d.remove());
+            this.dividers = [];
+            // Remove styling from targets
+            const targets = document.querySelectorAll(`.${FOCUSED_CLASS}`);
+            targets.forEach(t => t.classList.remove(FOCUSED_CLASS));
+            // Remove banner
+            this.removeExitBanner();
+            // Update URL
+            const url = new URL(window.location.href);
+            url.searchParams.delete(FOCUS_PARAM);
+            window.history.pushState({}, '', url.toString());
+        }
+    }
+
+    const DEFAULT_EXCLUDED_TAGS = ['HEADER', 'NAV', 'FOOTER', 'SCRIPT', 'STYLE'];
+    const DEFAULT_EXCLUDED_IDS = ['cv-floating-action-bar', 'cv-hover-helper', 'cv-toast-notification'];
+
     const TOGGLE_SELECTOR = "[data-cv-toggle], [data-customviews-toggle], cv-toggle";
     const TABGROUP_SELECTOR = 'cv-tabgroup';
     class CustomViewsCore {
@@ -1390,6 +2587,9 @@ ${TAB_STYLES}
         persistenceManager;
         visibilityManager;
         observer = null;
+        shareManager;
+        shareButton;
+        focusManager;
         componentRegistry = {
             toggles: new Set(),
             tabGroups: new Set(),
@@ -1406,6 +2606,22 @@ ${TAB_STYLES}
             this.visibilityManager = new VisibilityManager();
             this.showUrlEnabled = opt.showUrl ?? false;
             this.lastAppliedState = this.cloneState(this.getComputedDefaultState());
+            // Resolve Exclusions
+            const excludedTags = [...DEFAULT_EXCLUDED_TAGS, ...(this.config.shareExclusions?.tags || [])];
+            const excludedIds = [...DEFAULT_EXCLUDED_IDS, ...(this.config.shareExclusions?.ids || [])];
+            const commonOptions = { excludedTags, excludedIds };
+            this.shareManager = new ShareManager(commonOptions);
+            this.shareButton = new ShareButton(this.shareManager);
+            this.focusManager = new FocusManager(this.rootEl, commonOptions);
+        }
+        getShareManager() {
+            return this.shareManager;
+        }
+        /**
+         * Toggles the share mode on or off.
+         */
+        toggleShareMode() {
+            this.shareManager.toggleShareMode();
         }
         /**
          * Scan the given element for toggles and tab groups, register them
@@ -1438,7 +2654,7 @@ ${TAB_STYLES}
             return newComponentsFound;
         }
         /**
-         * Unscan the given element for toggles and tab groups, de-register them
+         * Unscan the given element for toggles and tab groups, de-register them from registry
          */
         unscan(element) {
             // Unscan for toggles
@@ -1542,8 +2758,11 @@ ${TAB_STYLES}
             // For session history, clicks on back/forward button
             window.addEventListener("popstate", () => {
                 this.loadAndCallApplyState();
+                this.focusManager.handleUrlChange();
             });
             this.loadAndCallApplyState();
+            this.focusManager.init();
+            this.shareButton.init();
             this.initObserver();
         }
         initializeNewComponents() {
@@ -1565,7 +2784,7 @@ ${TAB_STYLES}
                 const currentToggles = this.getCurrentActiveToggles();
                 const newState = {
                     toggles: currentToggles,
-                    tabs: currentTabs
+                    tabs: currentTabs,
                 };
                 // 2. Apply state with scroll anchor information
                 this.applyState(newState, {
@@ -1833,10 +3052,11 @@ ${TAB_STYLES}
     }
 
     /**
-     * Custom Elements for Tab Groups and Tabs
+     * Defines the custom elements used by CustomViews.
      */
     /**
-     * <cv-tab> element - represents a single tab panel
+     * `<cv-tab>`: A custom element representing a single tab panel within a tab group.
+     * Its content is displayed when the corresponding tab is active.
      */
     class CVTab extends HTMLElement {
         connectedCallback() {
@@ -1844,7 +3064,8 @@ ${TAB_STYLES}
         }
     }
     /**
-     * <cv-tabgroup> element - represents a group of tabs
+     * `<cv-tabgroup>`: A custom element that encapsulates a set of tabs (`<cv-tab>`).
+     * It manages the tab navigation and content visibility for the group.
      */
     class CVTabgroup extends HTMLElement {
         connectedCallback() {
@@ -1860,7 +3081,7 @@ ${TAB_STYLES}
         }
     }
     /**
-     * <cv-toggle> element - represents a toggleable content block
+     * `<cv-toggle>`: A custom element for creating a toggleable content block.
      */
     class CVToggle extends HTMLElement {
         connectedCallback() {
@@ -1868,8 +3089,8 @@ ${TAB_STYLES}
         }
     }
     /**
-     * <cv-tab-header> element - represents tab header with rich HTML formatting
-     * Content is extracted and used in the navigation link
+     * `<cv-tab-header>`: A semantic container for a tab's header content.
+     * The content of this element is used to create the navigation link for the tab.
      */
     class CVTabHeader extends HTMLElement {
         connectedCallback() {
@@ -1877,8 +3098,7 @@ ${TAB_STYLES}
         }
     }
     /**
-     * <cv-tab-body> element - represents tab body content
-     * Semantic container for tab panel content
+     * `<cv-tab-body>`: A semantic container for the main content of a tab panel.
      */
     class CVTabBody extends HTMLElement {
         connectedCallback() {
@@ -1886,7 +3106,7 @@ ${TAB_STYLES}
         }
     }
     /**
-     * Register custom elements
+     * Registers all CustomViews custom elements with the CustomElementRegistry.
      */
     function registerCustomElements() {
         // Only register if not already defined
@@ -3310,6 +4530,7 @@ ${TAB_STYLES}
             <span>Copy Shareable URL</span>
             <span class="cv-share-btn-icon">${getCopyIcon()}</span>
           </button>
+
         </footer>
       </div>
     `;