sphinx-filter-tabs 0.8.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

filter_tabs/renderer.py

@@ -0,0 +1,261 @@
+# filter_tabs/renderer.py
+"""
+Renders the HTML and fallback output for the filter-tabs directive.
+Consolidated version including parsing utilities and content type inference.
+"""
+
+from __future__ import annotations
+
+import copy
+from docutils import nodes
+from sphinx.util import logging
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+# Import models from extension.py (after consolidation)
+from .extension import TabData, FilterTabsConfig, IDGenerator
+from .extension import ContainerNode, FieldsetNode, LegendNode, RadioInputNode, LabelNode, PanelNode
+
+if TYPE_CHECKING:
+    from sphinx.environment import BuildEnvironment
+    from docutils.parsers.rst import Directive
+
+logger = logging.getLogger(__name__)
+
+# Constants
+SFT_CONTAINER = "sft-container"
+SFT_FIELDSET = "sft-fieldset"
+SFT_LEGEND = "sft-legend"
+SFT_RADIO_GROUP = "sft-radio-group"
+SFT_CONTENT = "sft-content"
+SFT_PANEL = "sft-panel"
+
+
+# =============================================================================
+# Content Type Inference Utilities (moved from parsers.py)
+# =============================================================================
+
+class ContentTypeInferrer:
+    """
+    Infers the type of content based on tab names to generate meaningful legends.
+    """
+    PATTERNS = [
+        (['python', 'javascript', 'java', 'c++', 'rust', 'go', 'ruby', 'php'], 'programming language'),
+        (['windows', 'mac', 'macos', 'linux', 'ubuntu', 'debian', 'fedora'], 'operating system'),
+        (['pip', 'conda', 'npm', 'yarn', 'cargo', 'gem', 'composer'], 'package manager'),
+        (['cli', 'gui', 'terminal', 'command', 'console', 'graphical'], 'interface'),
+        (['development', 'staging', 'production', 'test', 'local'], 'environment'),
+        (['source', 'binary', 'docker', 'manual', 'automatic'], 'installation method'),
+    ]
+    
+    @classmethod
+    def infer_type(cls, tab_names: List[str]) -> str:
+        """
+        Infer content type from a list of tab names.
+        
+        Args:
+            tab_names: List of tab names to analyze
+            
+        Returns:
+            Inferred content type string (e.g., 'programming language', 'operating system')
+        """
+        lower_names = [name.lower() for name in tab_names]
+        
+        # First pass: exact matches
+        for keywords, content_type in cls.PATTERNS:
+            if any(name in keywords for name in lower_names):
+                return content_type
+        
+        # Second pass: substring matches
+        for keywords, content_type in cls.PATTERNS:
+            for name in lower_names:
+                if any(keyword in name for keyword in keywords):
+                    return content_type
+        
+        # Default fallback
+        return 'option'
+
+
+# =============================================================================
+# Main Renderer Class
+# =============================================================================
+
+class FilterTabsRenderer:
+    """
+    Renders filter tabs with a focus on accessibility and browser compatibility.
+    Consolidated version with integrated content type inference.
+    """
+
+    def __init__(self, directive: Directive, tab_data: List[TabData], general_content: List[nodes.Node], custom_legend: Optional[str] = None):
+        self.directive = directive
+        self.env: BuildEnvironment = directive.state.document.settings.env
+        self.app = self.env.app
+        self.tab_data = tab_data
+        self.general_content = general_content
+        self.custom_legend = custom_legend
+        
+        # 1. Load configuration first
+        self.config = FilterTabsConfig.from_sphinx_config(self.app.config)
+        
+        # 2. Safely initialize the counter on the environment if it doesn't exist
+        if not hasattr(self.env, 'filter_tabs_counter'):
+            self.env.filter_tabs_counter = 0
+            
+        # 3. Increment the counter for this new tab group
+        self.env.filter_tabs_counter += 1
+        
+        # 4. Generate the unique group ID and the ID generator instance
+        self.group_id = f"filter-group-{self.env.filter_tabs_counter}"
+        self.id_gen = IDGenerator(self.group_id)
+        
+        # 5. Perform debug logging now that config and group_id are set
+        if self.config.debug_mode:
+            logger.info(f"Initialized new tab group with id: '{self.group_id}'")
+
+    def render_html(self) -> List[nodes.Node]:
+        """Render HTML with a browser-compatible CSS approach."""
+        if self.config.debug_mode:
+            logger.info(f"Rendering filter-tabs group {self.group_id}")
+
+        css_node = self._generate_compatible_css()
+
+        container_attrs = self._get_container_attributes()
+        container = ContainerNode(**container_attrs)
+
+        fieldset = self._create_fieldset()
+        container.children = [fieldset]
+        
+        return [css_node, container]
+
+    def render_fallback(self) -> List[nodes.Node]:
+        """Render for non-HTML builders (e.g., LaTeX)."""
+        output_nodes: List[nodes.Node] = []
+        
+        if self.general_content:
+            output_nodes.extend(copy.deepcopy(self.general_content))
+        
+        for tab in self.tab_data:
+            admonition = nodes.admonition()
+            admonition += nodes.title(text=tab.name)
+            admonition.extend(copy.deepcopy(tab.content))
+            output_nodes.append(admonition)
+        
+        return output_nodes
+
+    def _get_container_attributes(self) -> Dict[str, Any]:
+        """Get container attributes, including the style for custom properties."""
+        return {
+            'classes': [SFT_CONTAINER],
+            'role': 'region',
+            'aria-labelledby': self.id_gen.legend_id(),
+            'style': self.config.to_css_properties()
+        }
+
+    def _generate_compatible_css(self) -> nodes.raw:
+        """Generate CSS using sibling selectors to show/hide panels."""
+        css_rules = []
+        for i, tab in enumerate(self.tab_data):
+            radio_id = self.id_gen.radio_id(i)
+            panel_id = self.id_gen.panel_id(i)
+            css_rules.append(
+                f"#{radio_id}:checked ~ .{SFT_CONTENT} #{panel_id} {{ display: block; }}"
+            )
+        
+        css_content = "\n".join(css_rules)
+        return nodes.raw(text=f"<style>\n{css_content}\n</style>", format='html')
+
+    def _create_fieldset(self) -> FieldsetNode:
+        """Create the main fieldset containing the legend, radio buttons, and panels."""
+        fieldset = FieldsetNode(role="radiogroup")
+        
+        fieldset += self._create_legend()
+        
+        radio_group = ContainerNode(classes=[SFT_RADIO_GROUP])
+        self._populate_radio_group(radio_group)
+        
+        content_area = ContainerNode(classes=[SFT_CONTENT])
+        self._populate_content_area(content_area)
+        
+        # This is the fix: place the content_area inside the radio_group.
+        radio_group += content_area
+        
+        fieldset += radio_group
+        
+        return fieldset
+
+    def _create_legend(self) -> LegendNode:
+        """Create a meaningful, visible legend for the tab group."""
+        legend = LegendNode(classes=[SFT_LEGEND], ids=[self.id_gen.legend_id()])
+        
+        # Use the custom legend if it exists
+        if self.custom_legend:
+            legend_text = self.custom_legend
+        else:
+            # Fallback to the auto-generated legend using content type inference
+            tab_names = [tab.name for tab in self.tab_data]
+            content_type = ContentTypeInferrer.infer_type(tab_names)
+            legend_text = f"Choose {content_type}: {', '.join(tab_names)}"
+        
+        legend += nodes.Text(legend_text)
+        return legend
+
+    def _populate_radio_group(self, radio_group: ContainerNode) -> None:
+        """Create and add all radio buttons and labels to the radio group container."""
+        default_index = next((i for i, tab in enumerate(self.tab_data) if tab.is_default), 0)
+     
+        for i, tab in enumerate(self.tab_data):
+            radio_group += self._create_radio_button(i, tab, is_checked=(i == default_index))
+            radio_group += self._create_label(i, tab)
+            radio_group += self._create_screen_reader_description(i, tab)
+
+    def _create_radio_button(self, index: int, tab: TabData, is_checked: bool) -> RadioInputNode:
+        """Create a single radio button input."""
+        radio = RadioInputNode(
+            classes=['sr-only'],
+            type='radio',
+            name=self.group_id,
+            ids=[self.id_gen.radio_id(index)],
+            **{'aria-describedby': self.id_gen.desc_id(index)}
+        )
+        if tab.aria_label:
+            radio['aria-label'] = tab.aria_label
+        if is_checked:
+            radio['checked'] = 'checked'
+        return radio
+
+    def _create_label(self, index: int, tab: TabData) -> LabelNode:
+        """Create a label for a radio button."""
+        label = LabelNode(for_id=self.id_gen.radio_id(index))
+        label += nodes.Text(tab.name)
+        return label
+
+    def _create_screen_reader_description(self, index: int, tab: TabData) -> ContainerNode:
+        """Create the hidden description for screen readers."""
+        desc_text = f"Show content for {tab.name}"
+        description_node = ContainerNode(classes=['sr-only'], ids=[self.id_gen.desc_id(index)])
+        description_node += nodes.Text(desc_text)
+        return description_node
+
+    def _populate_content_area(self, content_area: ContainerNode) -> None:
+        """Create and add all general and tab-specific content panels."""
+        if self.general_content:
+            general_panel = PanelNode(classes=[SFT_PANEL], **{'data-filter': 'General'})
+            general_panel.extend(copy.deepcopy(self.general_content))
+            content_area += general_panel
+        
+        for i, tab in enumerate(self.tab_data):
+            content_area += self._create_tab_panel(i, tab)
+
+    def _create_tab_panel(self, index: int, tab: TabData) -> PanelNode:
+        """Create a single content panel for a tab."""
+        panel_attrs = {
+            'classes': [SFT_PANEL],
+            'ids': [self.id_gen.panel_id(index)],
+            'role': 'region',
+            'aria-labelledby': self.id_gen.radio_id(index),
+            'tabindex': '0',
+            'data-tab': tab.name.lower().replace(' ', '-')
+        }
+        panel = PanelNode(**panel_attrs)
+        panel.extend(copy.deepcopy(tab.content))
+        return panel
+    

filter_tabs/static/filter_tabs.css

@@ -1,92 +1,136 @@
-/* Sphinx Filter Tabs -- Static Stylesheet */
-/* This file provides the structural and base theme styles for the component. */
+/* Sphinx Filter Tabs - Simplified Accessibility-First Stylesheet */
 
-/* Main container for the tab component */
+/* Main container */
 .sft-container {
     border: 1px solid #e0e0e0;
-    /* THEME: The border-radius is controlled by a CSS variable from conf.py. */
     border-radius: var(--sft-border-radius, 8px);
     overflow: hidden;
     margin: 1.5em 0;
+    background: white;
 }
 
-/* The <fieldset> provides semantic grouping for accessibility. */
-.sft-fieldset { border: none; padding: 0; margin: 0; }
+/* Semantic structure */
+.sft-fieldset {
+    border: none;
+    padding: 0;
+    margin: 0;
+}
 
-/* The <legend> is visually hidden but essential for screen reader users. */
-.sft-legend { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+/* Visible, meaningful legend */
+.sft-legend {
+    background: #f8f9fa;
+    padding: 12px 20px;
+    margin: 0;
+    font-weight: 600;
+    color: #495057;
+    border-bottom: 1px solid #e0e0e0;
+    width: 100%;
+    font-size: 0.95em;
+}
 
-/* The <input type="radio"> buttons are the functional core.
-   They are hidden accessibly, not with display:none, so they remain
-   focusable for keyboard users. */
-.sft-tab-bar > input[type="radio"] {
-    position: absolute;
+/* Radio group container */
+.sft-radio-group {
+    display: flex;
+    flex-wrap: wrap;
+    background: #f8f9fa;
+    border-bottom: 1px solid #e0e0e0;
+    padding: 0 10px;
+}
+
+/* Hidden radio buttons (accessible to screen readers) */
+.sft-radio-group input[type="radio"] {
     width: 1px;
     height: 1px;
-    padding: 0;
-    margin: -1px;
-    overflow: hidden;
-    clip: rect(0, 0, 0, 0);
-    white-space: nowrap;
-    border: 0;
+    opacity: 0.01;
+    position: absolute;
+    z-index: -1;
+    margin: 0;
 }
 
-/* The tab bar containing the clickable labels. */
-.sft-tab-bar { 
-    display: flex; 
-    flex-wrap: wrap; 
-    /* THEME: The background color is controlled by a CSS variable. */
-    background-color: var(--sft-tab-background, #f0f0f0); 
-    border-bottom: 1px solid #e0e0e0; 
-    padding: 0 10px; 
-}
-.sft-tab-bar > label { 
-    padding: 12px 18px; 
-    cursor: pointer; 
-    transition: border-color 0.2s ease-in-out, color 0.2s ease-in-out; 
-    border-bottom: 3px solid transparent; 
-    color: #555; 
-    font-weight: 500; 
-    /* THEME: The font size is controlled by a CSS variable. */
-    font-size: var(--sft-font-size, 1em); 
-    line-height: 1.5; 
-}
-
-/* THEME: The active tab label is highlighted using a CSS variable for the color. */
-.sft-tab-bar > input[type="radio"]:checked + label {
+/* Tab labels */
+.sft-radio-group label {
+    display: block;
+    padding: 12px 18px;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    border-bottom: 3px solid transparent;
+    color: #6c757d;
+    font-weight: 500;
+    font-size: var(--sft-tab-font-size, 1em);
+    position: relative;
+    background: transparent;
+}
+
+/* Active tab styling */
+.sft-radio-group input[type="radio"]:checked + label {
+    color: var(--sft-tab-highlight-color, #007bff);
     border-bottom-color: var(--sft-tab-highlight-color, #007bff);
-    color: #000;
+    background: white;
+    font-weight: 600;
 }
 
-/* Add a clear, visible focus ring for keyboard navigation. */
-.sft-tab-bar > input[type="radio"]:focus + label {
-    box-shadow: 0 0 0 3px rgba(66, 153, 225, 0.6);
-    border-radius: 5px;
-    outline: none;
+/* Focus styling for keyboard navigation */
+.sft-radio-group input[type="radio"]:focus + label {
+    outline: 2px solid var(--sft-tab-highlight-color, #007bff);
+    outline-offset: 2px;
+    box-shadow: 0 0 0 4px rgba(0, 123, 255, 0.25);
+    z-index: 1;
 }
 
-/* The container for all content panels. */
-.sft-content { padding: 20px; }
+/* Hover effects */
+.sft-radio-group label:hover {
+    color: #495057;
+    background: rgba(0, 123, 255, 0.05);
+}
 
-/* By default, hide all tab-specific panels. The dynamic CSS will show the active one. */
-.sft-content > .sft-panel {
+/* Content area */
+.sft-content {
+    padding: 20px;
+    flex-basis: 100%; /* Add this line */
+}
+
+/* Panels - hidden by default */
+.sft-panel {
     display: none;
+    outline: none;
+}
+
+/* Focus styling for panels */
+.sft-panel:focus {
+    outline: 2px solid var(--sft-tab-highlight-color, #007bff);
+    outline-offset: -2px;
+    border-radius: 4px;
 }
 
-/* Always show the "General" panel, as it has no radio button to control it. */
-.sft-content > .sft-panel[data-filter="General"] {
+/* General content panel - always visible */
+.sft-panel[data-filter="General"] {
     display: block;
+    margin-bottom: 20px;
+    padding-bottom: 20px;
+    border-bottom: 1px solid #eee;
 }
 
+/* Screen reader only content */
+.sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+}
 
-/* Styles for collapsible sections */
+/* Collapsible sections */
 .collapsible-section {
     border: 1px solid #e0e0e0;
-    /* THEME: The accent color is controlled by a CSS variable. */
     border-left: 4px solid var(--sft-collapsible-accent-color, #17a2b8);
     border-radius: 4px;
     margin-top: 1em;
 }
+
 .collapsible-section summary {
     display: block;
     cursor: pointer;
@@ -94,14 +138,47 @@
     font-weight: bold;
     background-color: #f9f9f9;
     outline: none;
+    list-style: none;
 }
+
 .collapsible-section summary::-webkit-details-marker {
     display: none;
 }
-.collapsible-section summary {
-    list-style: none;
+
+.collapsible-section[open] > summary { 
+    border-bottom: 1px solid #e0e0e0; 
+}
+
+.custom-arrow { 
+    display: inline-block; 
+    width: 1em; 
+    margin-right: 8px; 
+    transition: transform 0.2s; 
+}
+
+.collapsible-section[open] > summary .custom-arrow { 
+    transform: rotate(90deg); 
+}
+
+.collapsible-content { 
+    padding: 15px; 
+}
+
+/* High contrast mode support */
+@media (prefers-contrast: high) {
+    .sft-radio-group input[type="radio"]:checked + label {
+        border-bottom-width: 4px;
+    }
+    
+    .sft-radio-group input[type="radio"]:focus + label {
+        box-shadow: 0 0 0 4px rgba(0, 0, 0, 0.8);
+    }
+}
+
+/* Reduced motion preferences */
+@media (prefers-reduced-motion: reduce) {
+    .sft-radio-group label,
+    .custom-arrow {
+        transition: none;
+    }
 }
-.collapsible-section[open] > summary { border-bottom: 1px solid #e0e0e0; }
-.custom-arrow { display: inline-block; width: 1em; margin-right: 8px; transition: transform 0.2s; }
-.collapsible-section[open] > summary .custom-arrow { transform: rotate(90deg); }
-.collapsible-content { padding: 15px; }

filter_tabs/static/filter_tabs.js

@@ -0,0 +1,160 @@
+// Progressive enhancement for keyboard navigation and accessibility.
+// This file ensures proper keyboard navigation and focus management,
+// while maintaining a CSS-only fallback.
+
+(function() {
+    'use strict';
+    
+    // Only enhance if the extension's HTML is present on the page.
+    if (!document.querySelector('.sft-container')) return;
+    
+    /**
+     * Moves focus to the content panel associated with a given radio button.
+     * This improves accessibility by directing screen reader users to the new content.
+     * @param {HTMLInputElement} radio The radio button that was selected.
+     */
+    function focusOnPanel(radio) {
+        if (!radio.checked) return;
+        
+        // Derive the panel's ID from the radio button's ID.
+        // e.g., 'filter-group-1-radio-0' becomes 'filter-group-1-panel-0'
+        const panelId = radio.id.replace('-radio-', '-panel-');
+        const panel = document.getElementById(panelId);
+        
+        if (panel) {
+            panel.focus();
+        }
+    }
+
+    /**
+     * Creates or updates a live region to announce tab changes to screen readers.
+     * @param {string} tabName The name of the selected tab.
+     */
+    function announceTabChange(tabName) {
+        // Create or find the live region for screen reader announcements.
+        let liveRegion = document.getElementById('tab-live-region');
+        if (!liveRegion) {
+            liveRegion = document.createElement('div');
+            liveRegion.id = 'tab-live-region';
+            liveRegion.setAttribute('role', 'status');
+            liveRegion.setAttribute('aria-live', 'polite');
+            liveRegion.setAttribute('aria-atomic', 'true');
+            // Hide the element visually but keep it accessible.
+            liveRegion.style.position = 'absolute';
+            liveRegion.style.left = '-10000px';
+            liveRegion.style.width = '1px';
+            liveRegion.style.height = '1px';
+            liveRegion.style.overflow = 'hidden';
+            document.body.appendChild(liveRegion);
+        }
+        
+        // Update the announcement text.
+        liveRegion.textContent = `${tabName} tab selected`;
+        
+        // Clear the announcement after a short delay to prevent clutter.
+        setTimeout(() => {
+            liveRegion.textContent = '';
+        }, 1000);
+    }
+
+    /**
+     * Initializes keyboard navigation for all filter-tab components on the page.
+     */
+    function initTabKeyboardNavigation() {
+        const containers = document.querySelectorAll('.sft-container');
+        
+        containers.forEach(container => {
+            const tabBar = container.querySelector('.sft-radio-group');
+            if (!tabBar) return;
+            
+            const radios = tabBar.querySelectorAll('input[type="radio"]');
+            const labels = tabBar.querySelectorAll('label');
+            
+            if (radios.length === 0 || labels.length === 0) return;
+            
+            // Make labels focusable to act as keyboard navigation targets.
+            labels.forEach(label => {
+                if (!label.hasAttribute('tabindex')) {
+                    label.setAttribute('tabindex', '0');
+                }
+            });
+
+            // Handle keyboard navigation on the tab labels.
+            labels.forEach((label, index) => {
+                label.addEventListener('keydown', (event) => {
+                    let targetIndex = index;
+                    let handled = false;
+                    
+                    switch (event.key) {
+                        case 'ArrowRight':
+                            event.preventDefault();
+                            targetIndex = (index + 1) % labels.length;
+                            handled = true;
+                            break;
+                            
+                        case 'ArrowLeft':
+                            event.preventDefault();
+                            targetIndex = (index - 1 + labels.length) % labels.length;
+                            handled = true;
+                            break;
+                            
+                        case 'Home':
+                            event.preventDefault();
+                            targetIndex = 0;
+                            handled = true;
+                            break;
+                            
+                        case 'End':
+                            event.preventDefault();
+                            targetIndex = labels.length - 1;
+                            handled = true;
+                            break;
+                            
+                        case 'Enter':
+                        case ' ':
+                            // Activate the associated radio button on Enter/Space.
+                            event.preventDefault();
+                            if (radios[index]) {
+                                radios[index].checked = true;
+                                radios[index].dispatchEvent(new Event('change', { bubbles: true }));
+                            }
+                            return;
+                            
+                        default:
+                            return;
+                    }
+                    
+                    if (handled) {
+                        // Move focus to the target label and activate its radio button.
+                        labels[targetIndex].focus();
+                        if (radios[targetIndex]) {
+                            radios[targetIndex].checked = true;
+                            radios[targetIndex].dispatchEvent(new Event('change', { bubbles: true }));
+                        }
+                    }
+                });
+            });
+            
+            // Add listeners for announcements and focus management.
+            radios.forEach((radio, index) => {
+                radio.addEventListener('change', () => {
+                    if (radio.checked) {
+                        // Announce the change to screen readers.
+                        if (labels[index]) {
+                            announceTabChange(labels[index].textContent.trim());
+                        }
+                        // Move focus to the newly visible panel.
+                        focusOnPanel(radio);
+                    }
+                });
+            });
+        });
+    }
+    
+    // Initialize the script once the DOM is ready.
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', initTabKeyboardNavigation);
+    } else {
+        initTabKeyboardNavigation();
+    }
+})();