@customviews-js/customviews 1.2.0 → 1.3.0

package/dist/custom-views.core.esm.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.
  */
@@ -154,7 +154,9 @@ class URLStateManager {
         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 {
@@ -168,6 +170,10 @@ class URLStateManager {
             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;
@@ -189,7 +195,9 @@ class URLStateManager {
         }
     }
     /**
-     * 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 {
@@ -228,6 +236,10 @@ class URLStateManager {
                     }
                 }
             }
+            // Reconstruct Focus
+            if (Array.isArray(compact.f)) {
+                state.focus = compact.f;
+            }
             return state;
         }
         catch (error) {
@@ -412,6 +424,12 @@ function getPinIcon(isPinned = false) {
     </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';
@@ -1376,6 +1394,1185 @@ function injectCoreStyles() {
     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 {
@@ -1384,6 +2581,9 @@ class CustomViewsCore {
     persistenceManager;
     visibilityManager;
     observer = null;
+    shareManager;
+    shareButton;
+    focusManager;
     componentRegistry = {
         toggles: new Set(),
         tabGroups: new Set(),
@@ -1400,6 +2600,22 @@ class CustomViewsCore {
         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
@@ -1432,7 +2648,7 @@ class CustomViewsCore {
         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
@@ -1536,8 +2752,11 @@ class CustomViewsCore {
         // 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() {
@@ -1559,7 +2778,7 @@ class CustomViewsCore {
             const currentToggles = this.getCurrentActiveToggles();
             const newState = {
                 toggles: currentToggles,
-                tabs: currentTabs
+                tabs: currentTabs,
             };
             // 2. Apply state with scroll anchor information
             this.applyState(newState, {
@@ -1827,10 +3046,11 @@ function prependBaseUrl(path, baseUrl) {
 }
 
 /**
- * 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() {
@@ -1838,7 +3058,8 @@ class CVTab extends HTMLElement {
     }
 }
 /**
- * <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() {
@@ -1854,7 +3075,7 @@ class CVTabgroup extends HTMLElement {
     }
 }
 /**
- * <cv-toggle> element - represents a toggleable content block
+ * `<cv-toggle>`: A custom element for creating a toggleable content block.
  */
 class CVToggle extends HTMLElement {
     connectedCallback() {
@@ -1862,8 +3083,8 @@ class CVToggle extends HTMLElement {
     }
 }
 /**
- * <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() {
@@ -1871,8 +3092,7 @@ class CVTabHeader extends HTMLElement {
     }
 }
 /**
- * <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() {
@@ -1880,7 +3100,7 @@ class CVTabBody extends HTMLElement {
     }
 }
 /**
- * Register custom elements
+ * Registers all CustomViews custom elements with the CustomElementRegistry.
  */
 function registerCustomElements() {
     // Only register if not already defined
@@ -3304,6 +4524,7 @@ class CustomViewsWidget {
             <span>Copy Shareable URL</span>
             <span class="cv-share-btn-icon">${getCopyIcon()}</span>
           </button>
+
         </footer>
       </div>
     `;