munchboka-edutools 0.2.3__py3-none-any.whl

munchboka_edutools/directives/cas_popup.py

@@ -0,0 +1,428 @@
+"""
+CAS Popup Directive
+===================
+
+A Sphinx directive that creates a button which opens a GeoGebra CAS (Computer Algebra System)
+window in a popup dialog. The dialog can be resized, dragged, and positioned anywhere on the page.
+
+Features:
+- Customizable button text and dialog title
+- Configurable width and height
+- Sidebar layout option for floating the button to the side
+- Scroll-locking when interacting with GeoGebra
+- Responsive resizing
+- Theme-aware styling (light/dark mode)
+
+Dependencies:
+- jQuery UI (for dialog functionality)
+- GeoGebra API (loaded via geogebra-setup.js)
+
+Usage Examples:
+--------------
+
+Basic usage (default 350x500 CAS window):
+```
+.. cas-popup::
+```
+
+Custom size with 600x700 window:
+```
+.. cas-popup:: 600 700
+```
+
+Custom button text and dialog title:
+```
+.. cas-popup:: 400 600 "Open Calculator" "My CAS Window"
+```
+
+Sidebar layout (floating button):
+```
+.. cas-popup:: 350 500 "CAS" "Calculator"
+   :layout: sidebar
+```
+
+Author: Original implementation from matematikk_r1
+"""
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+import uuid
+
+
+class CASPopUpDirective(SphinxDirective):
+    """
+    Directive to create a popup GeoGebra CAS window.
+
+    Arguments:
+        1. width (optional): Width of the CAS window in pixels (default: 350)
+        2. height (optional): Height of the CAS window in pixels (default: 500)
+        3. button_text (optional): Text displayed on the button (default: "Åpne CAS‑vindu")
+        4. dialog_title (optional): Title of the popup dialog (default: "CAS‑vindu")
+
+    Options:
+        :layout: Set to "sidebar" to float the button to the right side of the page
+    """
+
+    required_arguments = 0
+    optional_arguments = 4  # width, height, button text, dialog title
+    final_argument_whitespace = True
+    has_content = False
+    option_spec = {
+        "layout": lambda arg: arg,  # e.g., "sidebar"
+    }
+
+    def run(self):
+        # 1 » parse args -----------------------------------------------------
+        width = int(self.arguments[0]) if len(self.arguments) > 0 else 350
+        height = int(self.arguments[1]) if len(self.arguments) > 1 else 500
+
+        button_text = self.arguments[2] if len(self.arguments) > 2 else "Åpne CAS‑vindu"
+        dialog_title = self.arguments[3] if len(self.arguments) > 3 else "CAS‑vindu"
+
+        # 2 » unique IDs -----------------------------------------------------
+        cid = f"ggb-cas-{uuid.uuid4().hex[:8]}"
+        dialog_id = f"dialog-{cid}"
+        button_id = f"button-{cid}"
+
+        # 3 » layout option --------------------------------------------------
+        layout = self.options.get("layout", "").strip().lower()
+        use_sidebar = layout == "sidebar"
+
+        wrapper_start = '<div class="sidebar-cas">' if use_sidebar else ""
+        wrapper_end = "</div>" if use_sidebar else ""
+
+        # 4 » HTML content ---------------------------------------------------
+        html = f"""
+{wrapper_start}
+<meta name="viewport" content="width=device-width, initial-scale=1">
+
+<button id="{button_id}" class="ggb-cas-button">{button_text}</button>
+<div id="{dialog_id}" title="{dialog_title}" style="display:none;">
+    <div id="{cid}" class="ggb-window"></div>
+</div>
+
+<style>
+.ui-resizable-handle {{ min-width:16px;min-height:16px; }}
+.ui-dialog-content{{padding:0!important;}}
+.ggb-window       {{width:100%!important;height:100%!important;box-sizing:border-box;}}
+.ggb-cas-button   {{margin-top: 1em; margin-bottom: 1em;}}
+/* Ensure CAS dialog appears above jeopardy modal (which has z-index: 9999) */
+.ui-dialog {{
+  z-index: 10000 !important;
+}}
+.ui-widget-overlay {{
+  z-index: 9999 !important;
+}}
+.ggb-reset-btn {{
+  position: absolute;
+  right: 2.5em;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 2em;
+  height: 2em;
+  padding: 0.25em;
+  margin: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  border-radius: 4px;
+  background: transparent;
+  cursor: pointer;
+  transition: background-color 0.2s, opacity 0.2s;
+  opacity: 0.7;
+}}
+.ggb-reset-btn:hover {{
+  opacity: 1;
+  background-color: rgba(0, 0, 0, 0.1);
+}}
+[data-theme="dark"] .ggb-reset-btn:hover,
+html[data-theme="dark"] .ggb-reset-btn:hover {{
+  background-color: rgba(255, 255, 255, 0.1);
+}}
+.ggb-reset-btn svg {{
+  color: inherit;
+}}
+</style>
+
+<script>
+(function() {{
+  $(function() {{
+    let ggbReady = false;
+    const storageKey = 'ggb-cas-state-{cid}';
+
+    function applySize() {{
+      if (!ggbReady) return;
+      const w = $("#{cid}").width(),
+            h = $("#{cid}").height();
+      window.ggbApplet.setSize(Math.round(w), Math.round(h));
+    }}
+
+    function saveState() {{
+      if (!ggbReady || !window.ggbApplet) return;
+      try {{
+        const state = window.ggbApplet.getBase64();
+        localStorage.setItem(storageKey, state);
+        // Update timestamp for this state
+        localStorage.setItem(storageKey + '-timestamp', Date.now().toString());
+      }} catch (e) {{
+        // If quota exceeded, try cleaning up old states and retry
+        if (e.name === 'QuotaExceededError') {{
+          cleanupOldStates();
+          try {{
+            const state = window.ggbApplet.getBase64();
+            localStorage.setItem(storageKey, state);
+            localStorage.setItem(storageKey + '-timestamp', Date.now().toString());
+          }} catch (retryError) {{
+            // Still failed after cleanup - silently give up
+          }}
+        }}
+      }}
+    }}
+
+    function cleanupOldStates() {{
+      try {{
+        // Find all GeoGebra CAS states with timestamps
+        const casStates = [];
+        for (let i = 0; i < localStorage.length; i++) {{
+          const key = localStorage.key(i);
+          if (key && key.startsWith('ggb-cas-state-') && key.endsWith('-timestamp')) {{
+            const stateKey = key.replace('-timestamp', '');
+            const timestamp = parseInt(localStorage.getItem(key) || '0', 10);
+            casStates.push({{ key: stateKey, timestamp: timestamp }});
+          }}
+        }}
+        
+        // Sort by timestamp (oldest first)
+        casStates.sort((a, b) => a.timestamp - b.timestamp);
+        
+        // Delete oldest 25% of states (minimum 1, maximum 10)
+        const numToDelete = Math.max(1, Math.min(10, Math.floor(casStates.length * 0.25)));
+        for (let i = 0; i < numToDelete && i < casStates.length; i++) {{
+          localStorage.removeItem(casStates[i].key);
+          localStorage.removeItem(casStates[i].key + '-timestamp');
+        }}
+      }} catch (e) {{
+        // Cleanup failed - silently continue
+      }}
+    }}
+
+    function restoreState() {{
+      if (!ggbReady || !window.ggbApplet) return;
+      try {{
+        const savedState = localStorage.getItem(storageKey);
+        if (savedState) {{
+          window.ggbApplet.setBase64(savedState);
+          // Re-apply custom toolbar after restoring state to prevent it from being overwritten
+          setTimeout(() => {{
+            if (window.ggbApplet && window.ggbApplet.setCustomToolBar) {{
+              window.ggbApplet.setCustomToolBar("1001 | 1002 | 1007 | 1010 | 6");
+            }}
+          }}, 50);
+        }}
+      }} catch (e) {{
+        // Silently fail if restore fails
+      }}
+    }}
+
+    const $dlg = $("#{dialog_id}").dialog({{
+      autoOpen: false,
+      width: {width+40}, height: {height+80},
+      resizable: true, draggable: true,
+      position: {{ my: "center", at: "center", of: window }},
+      zIndex: 10000,
+      resize: () => window.requestAnimationFrame(applySize),
+      open: function() {{
+        if (!ggbReady) {{
+          new GGBApplet({{
+            appName: "classic", id: "{cid}",
+            width: {width}, height: {height},
+            perspective: "C", language: "nb",
+            showToolBar: true, showAlgebraInput: false,
+            borderRadius: 8, enableRightClick: true, showKeyboardOnFocus: false,
+            customToolBar: "1001 | 1002 | 1007 | 1010 | 6",
+            appletOnLoad: () => {{ 
+              ggbReady = true; 
+              applySize();
+              // Restore state after a short delay to ensure GeoGebra is fully initialized
+              setTimeout(restoreState, 100);
+            }}
+          }}, true).inject("{cid}");
+        }} else {{
+          applySize();
+        }}
+      }},
+      close: function() {{
+        // Save state when dialog is closed
+        saveState();
+      }}
+    }});
+
+    // Add refresh button to title bar
+    const titleBar = $dlg.parent().find('.ui-dialog-titlebar');
+    const refreshBtn = $('<button type="button" class="ggb-reset-btn" title="Start på nytt (slett lagret innhold)"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M13.65 2.35C12.2 0.9 10.21 0 8 0 3.58 0 0.01 3.58 0.01 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L9 7h7V0l-2.35 2.35z" fill="currentColor"/></svg></button>');
+    refreshBtn.on('click', function() {{
+      if (confirm('Er du sikker på at du vil slette lagret innhold og starte på nytt?')) {{
+        try {{
+          localStorage.removeItem(storageKey);
+          localStorage.removeItem(storageKey + '-timestamp');
+          if (ggbReady && window.ggbApplet) {{
+            // Clear the container
+            $("#{cid}").empty();
+            // Reset the flag
+            ggbReady = false;
+            // Recreate the applet from scratch
+            new GGBApplet({{
+              appName: "classic", id: "{cid}",
+              width: {width}, height: {height},
+              perspective: "C", language: "nb",
+              showToolBar: true, showAlgebraInput: false,
+              borderRadius: 8, enableRightClick: true, showKeyboardOnFocus: false,
+              customToolBar: "1001 | 1002 | 1007 | 1010 | 6",
+              appletOnLoad: () => {{ 
+                ggbReady = true; 
+                applySize();
+              }}
+            }}, true).inject("{cid}");
+          }}
+        }} catch (e) {{
+          console.error('Failed to reset:', e);
+        }}
+      }}
+    }});
+    titleBar.append(refreshBtn);
+
+    // Save state when page is unloaded (refresh, navigate away, close tab)
+    $(window).on('beforeunload', function() {{
+      if ($dlg.dialog('isOpen')) {{
+        saveState();
+      }}
+    }});
+
+    // Prevent background scroll when GeoGebra applet is active
+    let scrollLocked = false;
+    let lockedScrollTop = 0;
+    let keyHandler = null;
+    let wheelHandler = null;
+    let scrollHandler = null;
+    
+    function lockScroll() {{
+      if (scrollLocked) return;
+      scrollLocked = true;
+      lockedScrollTop = window.pageYOffset || document.documentElement.scrollTop || 0;
+      
+      // Instead of preventing keys, monitor and restore scroll position
+      scrollHandler = () => {{
+        if (scrollLocked) {{
+          const currentScroll = window.pageYOffset || document.documentElement.scrollTop || 0;
+          if (currentScroll !== lockedScrollTop) {{
+            window.scrollTo(0, lockedScrollTop);
+          }}
+        }}
+      }};
+      
+      // Prevent wheel scrolling on the page background
+      wheelHandler = (e) => {{
+        const dialogElement = e.target.closest('.ui-dialog');
+        if (dialogElement) {{
+          // Allow scrolling within dialog elements that can scroll
+          let target = e.target;
+          while (target && target !== dialogElement) {{
+            const overflow = window.getComputedStyle(target).overflow;
+            if (overflow === 'auto' || overflow === 'scroll') {{
+              return; // Allow internal scrolling
+            }}
+            target = target.parentElement;
+          }}
+          // Prevent page scroll but don't stop the event from reaching GeoGebra
+          if (!e.target.closest('#{cid}')) {{
+            e.preventDefault();
+            e.stopPropagation();
+          }}
+        }}
+      }};
+      
+      // Monitor scroll events to maintain position
+      window.addEventListener('scroll', scrollHandler, {{ passive: true }});
+      document.addEventListener('wheel', wheelHandler, {{ capture: true, passive: false }});
+    }}
+    
+    function unlockScroll() {{
+      if (!scrollLocked) return;
+      scrollLocked = false;
+      
+      if (scrollHandler) {{
+        window.removeEventListener('scroll', scrollHandler);
+        scrollHandler = null;
+      }}
+      if (wheelHandler) {{
+        document.removeEventListener('wheel', wheelHandler, {{ capture: true }});
+        wheelHandler = null;
+      }}
+    }}
+    
+    // Monitor GeoGebra applet focus/interaction to control scroll lock
+    function bindScrollLock() {{
+      const ggbContainer = document.getElementById('{cid}');
+      if (!ggbContainer) {{
+        setTimeout(bindScrollLock, 300);
+        return;
+      }}
+      
+      // Look for the actual GeoGebra canvas/applet elements
+      const ggbApplet = ggbContainer.querySelector('canvas') || 
+                       ggbContainer.querySelector('.ggbApplet') ||
+                       ggbContainer.querySelector('[id^="ggbApplet"]') ||
+                       ggbContainer;
+      
+      if (ggbApplet) {{
+        // Lock scroll when interacting with GeoGebra
+        ggbApplet.addEventListener('mousedown', lockScroll);
+        ggbApplet.addEventListener('focus', lockScroll);
+        ggbApplet.addEventListener('click', lockScroll);
+        
+        // Also monitor the container for any focus events
+        ggbContainer.addEventListener('focusin', lockScroll);
+        ggbContainer.addEventListener('mousedown', lockScroll);
+        
+        // Unlock when clicking outside or losing focus
+        document.addEventListener('click', (e) => {{
+          if (!ggbContainer.contains(e.target) && !e.target.closest('.ui-dialog')) {{
+            unlockScroll();
+          }}
+        }});
+        
+        ggbContainer.addEventListener('focusout', (e) => {{
+          // Small delay to check if focus moved outside the container
+          setTimeout(() => {{
+            if (!ggbContainer.contains(document.activeElement)) {{
+              unlockScroll();
+            }}
+          }}, 100);
+        }});
+      }}
+    }}
+    
+    // Start monitoring after GeoGebra is loaded
+    setTimeout(bindScrollLock, 1000);
+    
+    // Cleanup on dialog close
+    $dlg.on('dialogclose', unlockScroll);
+
+    $("#{button_id}").button()
+      .on("click touchend pointerup", e => {{
+        e.preventDefault();
+        $("#{dialog_id}").dialog("open");
+      }});
+  }});
+}})();
+</script>
+{wrapper_end}
+        """
+        return [nodes.raw("", html, format="html")]
+
+
+def setup(app):
+    """Register the directive with Sphinx."""
+    app.add_directive("cas-popup", CASPopUpDirective)
+    return {"version": "0.1", "parallel_read_safe": True, "parallel_write_safe": True}

munchboka_edutools/directives/clear.py

@@ -0,0 +1,103 @@
+"""
+Clear Directive for Munchboka Edutools
+======================================
+
+This directive inserts a CSS clear:both element to clear floating elements.
+Useful after floated images or other content to ensure proper layout flow.
+
+Usage in MyST Markdown:
+    ```{clear}
+    ```
+
+Purpose:
+    The clear directive is commonly used in web layouts to clear CSS floats.
+    When you have floated elements (like images with float:left or float:right),
+    subsequent content can wrap around them. The clear directive ensures that
+    content after it starts on a new line below all floated elements.
+
+Common Use Cases:
+    - After floating images to prevent text wrapping
+    - Between sections to ensure proper spacing
+    - To reset layout flow after floated elements
+
+Features:
+    - No arguments or options needed
+    - Simply inserts a clearing div
+    - Works with all CSS float properties
+
+Example:
+    ![Floating Image](image.png){.float-left}
+
+    Some text that wraps around the image...
+
+    ```{clear}
+    ```
+
+    This text starts below the image, not wrapped around it.
+
+Author: René Aasen (ported from matematikk_r1)
+Date: November 2025
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+
+class ClearDirective(Directive):
+    """
+    Sphinx directive for clearing CSS floats.
+
+    This directive inserts a div with `clear: both` CSS property,
+    which forces content to start below any floated elements.
+
+    Arguments:
+        None
+
+    Options:
+        None
+
+    Example:
+        After a floated image:
+        ```{clear}
+        ```
+
+        Or between sections:
+        ```{clear}
+        ```
+    """
+
+    has_content = False
+    required_arguments = 0
+    optional_arguments = 0
+
+    def run(self):
+        """
+        Generate the HTML for the clear element.
+
+        Returns:
+            list: List of docutils nodes (raw HTML node with clear div)
+        """
+        html = '<div style="clear: both;"></div>'
+        return [nodes.raw("", html, format="html")]
+
+
+def setup(app):
+    """
+    Setup function to register the directive with Sphinx.
+
+    This function is called automatically by Sphinx when the extension is loaded.
+    It registers the 'clear' directive for use in documentation.
+
+    Args:
+        app: The Sphinx application instance
+
+    Returns:
+        dict: Extension metadata including version and parallel processing flags
+    """
+    app.add_directive("clear", ClearDirective)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

munchboka_edutools/directives/dialogue.py

@@ -0,0 +1,137 @@
+"""
+Dialogue directive for creating conversation-style content.
+
+This directive creates a dialogue between two speakers with chat-bubble styling.
+Each speaker's messages are aligned left or right and styled with different colors.
+
+Usage:
+    ```{dialogue}
+    :name1: Alice
+    :name2: Bob
+    :speaker1: left
+    :speaker2: right
+
+    Alice: Hello! How are you?
+    Bob: I'm great, thanks for asking!
+    Alice: That's wonderful to hear.
+    ```
+
+Options:
+    - name1 (required): Name of the first speaker
+    - name2 (required): Name of the second speaker
+    - speaker1 (required): Alignment for first speaker ("left" or "right")
+    - speaker2 (required): Alignment for second speaker ("left" or "right")
+
+Content:
+    Each line should be in the format: "SpeakerName: Message text"
+    Lines not matching this format are ignored.
+    Messages can contain math notation and will be parsed as normal content.
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx.directives import optional_int
+
+
+class DialogueWrapperNode(nodes.General, nodes.Element):
+    """Container node for the entire dialogue."""
+
+    pass
+
+
+class DialogueEntryNode(nodes.Admonition, nodes.Element):
+    """Node for a single dialogue entry (one message from one speaker)."""
+
+    pass
+
+
+def visit_dialogue_wrapper_node_html(self, node):
+    """Open the dialogue container div."""
+    self.body.append('<div class="dialogue">')
+
+
+def depart_dialogue_wrapper_node_html(self, node):
+    """Close the dialogue container div."""
+    self.body.append("</div>")
+
+
+def visit_dialogue_entry_node_html(self, node):
+    """Open a dialogue entry with speaker name."""
+    self.body.append(f'<div class="dialogue-entry {node["css_class"]}">')
+    self.body.append(f'<div class="speaker-name">{node["speaker_name"]}</div>')
+
+
+def depart_dialogue_entry_node_html(self, node):
+    """Close the dialogue entry div."""
+    self.body.append("</div>")
+
+
+class DialogueDirective(Directive):
+    """
+    Directive for creating dialogue between two speakers.
+
+    Creates chat-bubble styled conversations with left/right alignment.
+    """
+
+    has_content = True
+    required_arguments = 0
+    option_spec = {
+        "name1": directives.unchanged_required,
+        "name2": directives.unchanged_required,
+        "speaker1": lambda s: directives.choice(s, ("left", "right")),
+        "speaker2": lambda s: directives.choice(s, ("left", "right")),
+    }
+
+    def run(self):
+        """Parse dialogue content and create dialogue nodes."""
+        name1 = self.options.get("name1")
+        name2 = self.options.get("name2")
+        class1 = "speaker1" if self.options.get("speaker1") == "left" else "speaker2"
+        class2 = "speaker1" if self.options.get("speaker2") == "left" else "speaker2"
+
+        wrapper_node = DialogueWrapperNode()
+
+        for line in self.content:
+            line = line.strip()
+            if not line or ":" not in line:
+                continue
+
+            speaker_name, message = line.split(":", 1)
+            speaker_name = speaker_name.strip()
+            message = message.strip()
+
+            if speaker_name == name1:
+                css_class = class1
+            elif speaker_name == name2:
+                css_class = class2
+            else:
+                continue
+
+            entry_node = DialogueEntryNode()
+            entry_node["css_class"] = css_class
+            entry_node["speaker_name"] = speaker_name
+
+            # Parse the message line like normal content so math works
+            self.state.nested_parse([message], self.content_offset, entry_node)
+            wrapper_node += entry_node
+
+        return [wrapper_node]
+
+
+def setup(app):
+    """Register the dialogue directive and nodes with Sphinx."""
+    app.add_node(
+        DialogueWrapperNode,
+        html=(visit_dialogue_wrapper_node_html, depart_dialogue_wrapper_node_html),
+    )
+    app.add_node(
+        DialogueEntryNode,
+        html=(visit_dialogue_entry_node_html, depart_dialogue_entry_node_html),
+    )
+    app.add_directive("dialogue", DialogueDirective)
+
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }