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

filter_tabs/extension.py

@@ -85,7 +85,7 @@ class FilterTabsRenderer:
         self.temp_blocks: list[nodes.Node] = temp_blocks
 
     def render_html(self) -> list[nodes.Node]:
-        """Constructs the complete docutils node tree for the HTML output."""
+        """Constructs the complete, W3C valid, and ARIA-compliant docutils node tree."""
         # Ensure a unique ID for each filter-tabs instance on a page.
         if not hasattr(self.env, 'filter_tabs_counter'):
             self.env.filter_tabs_counter = 0
@@ -104,67 +104,89 @@ class FilterTabsRenderer:
         }
         style_string = "; ".join([f"{key}: {value}" for key, value in style_vars.items()])
 
-        # If debug mode is on, log the generated ID and styles for easier troubleshooting.
+        # If debug mode is on, log the generated ID and styles.
         if config.filter_tabs_debug_mode:
             logger.info(f"[sphinx-filter-tabs] ID: {group_id}, Styles: '{style_string}'")
 
         # Create the main container node with the inline style for theming.
         container = ContainerNode(classes=[SFT_CONTAINER], style=style_string)
 
-        # Build the semantic structure using fieldset and a hidden legend for accessibility.
+        # Build the semantic structure using fieldset and a hidden legend.
         fieldset = FieldsetNode()
         legend = LegendNode()
         legend += nodes.Text(f"Filter by: {', '.join(self.tab_names)}")
         fieldset += legend
-
-        # Generate the dynamic CSS that handles the core filtering logic.
+        
+        # --- CSS Generation ---
+        # This generates the dynamic CSS that handles the core filtering logic.
         css_rules = []
         for tab_name in self.tab_names:
             radio_id = f"{group_id}-{self._css_escape(tab_name)}"
-            # This CSS rule shows a panel only when its corresponding radio button is checked.
-            # The modern :has() selector makes this possible without any JavaScript.
+            panel_id = f"{radio_id}-panel"
+            # This rule finds the tab bar that contains the checked radio button,
+            # then finds its sibling content area and shows the correct panel inside.
             css_rules.append(
-                f".{SFT_TAB_BAR}:has(#{radio_id}:checked) ~ "
-                f".{SFT_CONTENT} > .{SFT_PANEL}[data-filter='{tab_name}'] {{ display: block; }}"
+                f".{SFT_TAB_BAR}:has(#{radio_id}:checked) ~ .sft-content > #{panel_id} {{ display: block; }}"
             )
-        # Embed the generated CSS directly into the HTML.
-        style_node = nodes.raw(text=f"<style>{''.join(css_rules)}</style>", format="html")
-
-        # Create the tab bar with radio inputs and labels.
+        
+        # Write the dynamic CSS to a temporary file and add it to the build.
+        css_content = ''.join(css_rules)
+        static_dir = Path(self.env.app.outdir) / '_static'
+        static_dir.mkdir(parents=True, exist_ok=True)
+        css_filename = f"dynamic-filter-tabs-{group_id}.css"
+        (static_dir / css_filename).write_text(css_content, encoding='utf-8')
+        self.env.app.add_css_file(css_filename)
+
+        # --- ARIA-Compliant HTML Structure ---
+        # The tab bar container now gets the role="tablist".
         tab_bar = nodes.container(classes=[SFT_TAB_BAR], role='tablist')
-        for tab_name in self.tab_names:
+        fieldset += tab_bar
+
+        # The content area holds all the panels.
+        content_area = nodes.container(classes=[SFT_CONTENT])
+        fieldset += content_area
+
+        # Map tab names to their content blocks for easy lookup.
+        content_map = {block['filter-name']: block.children for block in self.temp_blocks}
+        
+        # 1. Create all radio buttons and labels first and add them to the tab_bar.
+        for i, tab_name in enumerate(self.tab_names):
             radio_id = f"{group_id}-{self._css_escape(tab_name)}"
-            # The radio buttons are functionally necessary but visually hidden.
+            panel_id = f"{radio_id}-panel"
+
+            # The radio button is for state management.
             radio = RadioInputNode(type='radio', name=group_id, ids=[radio_id])
-            if tab_name == self.default_tab:
-                radio['checked'] = 'checked' # Set the default tab.
+            
+            is_default = (self.default_tab == tab_name) or (i == 0 and not self.default_tab)
+            if is_default:
+                radio['checked'] = 'checked'
             tab_bar += radio
 
-            # The labels are the visible, clickable tabs.
-            label = LabelNode(for_id=radio_id, role='tab')
+            # The label is the visible tab. It gets role="tab" and aria-controls.
+            label = LabelNode(for_id=radio_id, role='tab', **{'aria-controls': panel_id})
+            if is_default:
+                label['aria-selected'] = 'true'
             label += nodes.Text(tab_name)
             tab_bar += label
-        fieldset += tab_bar
 
-        # Create the content area where all panels will reside.
-        content_area = nodes.container(classes=[SFT_CONTENT])
-        # Map tab names to their content blocks for easy lookup.
-        content_map = {block['filter-name']: block.children for block in self.temp_blocks}
-        # Ensure we create panels for all declared tabs plus the "General" tab.
-        all_tab_names = self.tab_names + ["General"]
+        # 2. Create all tab panels and add them to the content_area.
+        all_tab_names = ["General"] + self.tab_names
         for tab_name in all_tab_names:
-            panel = PanelNode(classes=[SFT_PANEL], **{'data-filter': tab_name, 'role': 'tabpanel'})
+            # The "General" panel does not correspond to a specific tab control.
+            if tab_name == "General":
+                panel = PanelNode(classes=[SFT_PANEL], **{'data-filter': tab_name})
+            else:
+                radio_id = f"{group_id}-{self._css_escape(tab_name)}"
+                panel_id = f"{radio_id}-panel"
+                # The panel gets role="tabpanel" and is linked back to the label.
+                panel = PanelNode(classes=[SFT_PANEL], ids=[panel_id], role='tabpanel', **{'aria-labelledby': radio_id})
+
             if tab_name in content_map:
-                # Use deepcopy to prevent docutils node mutation bugs. Since the same content
-                # might be referenced or processed multiple times, a deep copy ensures that
-                # each panel gets a completely independent set of nodes.
                 panel.extend(copy.deepcopy(content_map[tab_name]))
             content_area += panel
-        fieldset += content_area
-        container.children = [fieldset]
 
-        # The final structure is the dynamic style block followed by the main container.
-        return [style_node, container]
+        container.children = [fieldset]
+        return [container]
 
     def render_fallback(self) -> list[nodes.Node]:
         """Renders content as a series of simple admonitions for non-HTML builders (e.g., LaTeX/PDF)."""
@@ -226,9 +248,10 @@ class FilterTabsDirective(Directive):
         and delegates the final rendering to the FilterTabsRenderer.
         """
         env = self.state.document.settings.env
-        # Prevent nesting of filter-tabs directives.
-        if hasattr(env, 'sft_context') and env.sft_context:
-            raise self.error("Nesting `filter-tabs` is not supported.")
+        
+        # Remove comments to prevent nesting of filter-tabs directives.
+        #if hasattr(env, 'sft_context') and env.sft_context:
+        #    raise self.error("Nesting `filter-tabs` is not supported.")
 
         # Set a context flag to indicate that we are inside a filter-tabs block.
         if not hasattr(env, 'sft_context'):

filter_tabs/static/filter_tabs.css

@@ -1,7 +1,5 @@
 /* Sphinx Filter Tabs -- Static Stylesheet */
-/* This file provides the structural and base theme styles for the component.
-   The core filtering logic (showing the active panel) is handled by a small,
-   dynamically generated <style> block created by extension.py. */
+/* This file provides the structural and base theme styles for the component. */
 
 /* Main container for the tab component */
 .sft-container {
@@ -18,9 +16,19 @@
 /* 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; }
 
-/* The <input type="radio"> buttons are the functional core, but are not visible. */
+/* 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"] {
-    display: none;
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
 }
 
 /* The tab bar containing the clickable labels. */
@@ -40,32 +48,38 @@
     color: #555; 
     font-weight: 500; 
     /* THEME: The font size is controlled by a CSS variable. */
-    font-size: var(--sft-tab-font-size, 1em); 
+    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.
-   The adjacent sibling selector (+) is robust and efficient. */
+/* THEME: The active tab label is highlighted using a CSS variable for the color. */
 .sft-tab-bar > input[type="radio"]:checked + label {
     border-bottom-color: var(--sft-tab-highlight-color, #007bff);
     color: #000;
 }
 
+/* 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;
+}
+
 /* The container for all content panels. */
 .sft-content { padding: 20px; }
 
-/* By default, hide all tab-specific panels. */
-.sft-container .sft-panel {
+/* By default, hide all tab-specific panels. The dynamic CSS will show the active one. */
+.sft-content > .sft-panel {
     display: none;
 }
-/* The "General" panel, however, is always visible. */
-.sft-container .sft-panel[data-filter="General"] {
+
+/* Always show the "General" panel, as it has no radio button to control it. */
+.sft-content > .sft-panel[data-filter="General"] {
     display: block;
 }
-/* The dynamically generated <style> block handles showing the one active panel. */
 
 
-/* Styles for collapsible sections, matching the golden record. */
+/* Styles for collapsible sections */
 .collapsible-section {
     border: 1px solid #e0e0e0;
     /* THEME: The accent color is controlled by a CSS variable. */
@@ -81,11 +95,9 @@
     background-color: #f9f9f9;
     outline: none;
 }
-/* Hide the default disclosure triangle in browsers like Chrome/Safari. */
 .collapsible-section summary::-webkit-details-marker {
     display: none;
 }
-/* Hide the default disclosure triangle in browsers like Firefox. */
 .collapsible-section summary {
     list-style: none;
 }

{sphinx_filter_tabs-0.6.0.dist-info → sphinx_filter_tabs-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-filter-tabs
-Version: 0.6.0
+Version: 0.8.0
 Summary: A Sphinx extension for accessible, JS-free filterable content tabs.
 Author-email: Aputsiak Niels Janussen <aputsiak+sphinx@gmail.com>
 License: GNU General Public License v3.0
@@ -45,3 +45,19 @@ This extension provides `filter-tabs` and `tab` directives to create user-friend
 You can install this extension using `pip`:
 ```bash
 pip install sphinx-filter-tabs
+```
+
+## Development
+
+1. You can install a local version of the Sphinx with extension using:
+```bash
+./scripts/setup_dev.sh # Initially cleans previous folders in _docs/build  and venv.
+```
+
+Command to enter venv is provided.
+
+2. Once inside virtual environment, you can use following commands:
+```bash
+pytest # Runs test suite on configured version of Sphinx.
+tox # Check across multiple Sphinx versions. Manual install of tox required.
+```

sphinx_filter_tabs-0.8.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+filter_tabs/__init__.py,sha256=VPpIhj4HaLeMX7ai7dZFkUm81ii2ePPGjCd9hsMjsN4,397
+filter_tabs/extension.py,sha256=K7w7iRN72PGVvswDuULBxxxam4zvPF1ZulsAxeHlvz8,20937
+filter_tabs/static/filter_tabs.css,sha256=gXQk2ceyjAj9p3G_k-mrcPdxq0ggIXSMuXHyUE5mPP0,3486
+sphinx_filter_tabs-0.8.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+sphinx_filter_tabs-0.8.0.dist-info/METADATA,sha256=SjLifkJnouYp8U4_te9JgpPtELGgQcaaeXEXoGRSCkU,2705
+sphinx_filter_tabs-0.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sphinx_filter_tabs-0.8.0.dist-info/entry_points.txt,sha256=za_bQcueY8AHyq7XnnjkW9X3C-LsZjeERVQ_ds7jV1A,62
+sphinx_filter_tabs-0.8.0.dist-info/top_level.txt,sha256=K0Iy-6EsYYdvlyXdsJT0SQg-BLDBgT5-Y8ZKy5SNAfc,12
+sphinx_filter_tabs-0.8.0.dist-info/RECORD,,

sphinx_filter_tabs-0.6.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-filter_tabs/__init__.py,sha256=VPpIhj4HaLeMX7ai7dZFkUm81ii2ePPGjCd9hsMjsN4,397
-filter_tabs/extension.py,sha256=ZWq-MCft-RvZtx4xzVyDGXGGtgddh8dZdeHTivIcN34,20204
-filter_tabs/static/filter_tabs.css,sha256=btJoI-Q87e0XUQARwJUhM6RCfg5m2dvxKtfABZ2zRsc,3429
-sphinx_filter_tabs-0.6.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-sphinx_filter_tabs-0.6.0.dist-info/METADATA,sha256=msO5UEdrQPPLpUF3d0aRI-HaO9gqLccVfTbw3bMGtVQ,2264
-sphinx_filter_tabs-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sphinx_filter_tabs-0.6.0.dist-info/entry_points.txt,sha256=za_bQcueY8AHyq7XnnjkW9X3C-LsZjeERVQ_ds7jV1A,62
-sphinx_filter_tabs-0.6.0.dist-info/top_level.txt,sha256=K0Iy-6EsYYdvlyXdsJT0SQg-BLDBgT5-Y8ZKy5SNAfc,12
-sphinx_filter_tabs-0.6.0.dist-info/RECORD,,