panda-editor 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4aceae2a319683face212a6ab1cb17cf0796ac0d0ce5f10ccfe4adaf1ff3a76
-  data.tar.gz: 440839d76811382db14f860ed4529ea6672148a815459c817423ef734bc0a81d
+  metadata.gz: b3b8232a60a069137aa8a04c6611f0583877cf036ba6c62c82bef72584c5216d
+  data.tar.gz: 975f2cb5e0fb8ce6eaa5ae8eb80e3135e1ff44126c102271dd318b148b40b47a
 SHA512:
-  metadata.gz: ab408175021676d37abd0a62b37181cda6830c5e09324056d4bd112bee796bca5a61f5ae3c8dfdc64e9ea5134e55729b16b8343b0a57cb9b78ecb2229104d0cd
-  data.tar.gz: d6142f7cd742a6efb0f3fd810a517361cfcd5446ae8014c1699376a857b65acb388635f40f1063116baa3ab659b2cdac8e60f23c57cb19bacd8ef27287b8b43e
+  metadata.gz: a012d400a6af140737018adb0187ce7e54be0614d1fd833492cebb35d4310aac91eeab2109ab8d08857333226624084d2ada8a567c21ff8ea43fff018ca17c0c
+  data.tar.gz: 8df13bfa16acea6e9e65b22e20ff3e138791648c654090d1134140fa94b1bea7b8d439ef8544a73c9c7ac5ad8066539e9eca1842e8f152d86e3634b65bb71c73

data/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-10-30
+
+### Added
+- Footnote support for academic citations and references
+  - Ruby backend renderer for footnote processing
+  - EditorJS inline tool for footnote insertion
+  - Automatic footnote numbering and deduplication
+  - Collapsible sources section in rendered output
+  - Comprehensive footnote documentation
+
+### Fixed
+- Disabled caching for blocks containing footnotes to ensure accurate rendering
+- Updated test expectations to match footnote behavior
+
+### Changed
+- Applied standardrb code style fixes across codebase
+
 ## [0.2.0] - 2025-08-12
 
 ### Added
@@ -65,5 +82,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - HTML sanitization for security
 - Asset pipeline integration
 
+[0.3.0]: https://github.com/tastybamboo/panda-editor/compare/v0.2.1...v0.3.0
 [0.2.0]: https://github.com/tastybamboo/panda-editor/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/tastybamboo/panda-editor/releases/tag/v0.1.0

data/README.md

@@ -90,6 +90,7 @@ Panda::Editor::Engine.config.custom_renderers['custom'] = CustomBlock
 ## Available Blocks
 
 - **Paragraph**: Standard text content
+  - Supports inline footnotes with automatic numbering
 - **Header**: H1-H6 headings
 - **List**: Ordered and unordered lists
 - **Quote**: Blockquotes with captions
@@ -97,6 +98,106 @@ Panda::Editor::Engine.config.custom_renderers['custom'] = CustomBlock
 - **Image**: Images with captions and styling options
 - **Alert**: Alert/notification boxes
 
+## Footnotes
+
+Panda Editor supports inline footnotes that are automatically collected and rendered in a "Sources/References" section at the end of your content.
+
+### Adding Footnotes to Paragraphs
+
+Footnotes are added to paragraph blocks in your EditorJS JSON:
+
+```json
+{
+  "type": "paragraph",
+  "data": {
+    "text": "Climate change has accelerated significantly since 1980",
+    "footnotes": [
+      {
+        "id": "unique-id-1",
+        "content": "IPCC. (2023). Climate Change 2023: Synthesis Report.",
+        "position": 55
+      }
+    ]
+  }
+}
+```
+
+**Fields:**
+- `id`: Unique identifier for the footnote (allows multiple citations of the same source)
+- `content`: The footnote text/citation
+- `position`: Character position in the text where the footnote marker should appear
+
+### Rendered Output
+
+The renderer will:
+1. Insert superscript footnote markers (`¹`, `²`, etc.) at specified positions
+2. Auto-number footnotes sequentially across the entire document
+3. De-duplicate footnotes with the same `id`
+4. Generate a collapsible "Sources/References" section at the end
+
+Example output:
+
+```html
+<p>Climate change has accelerated significantly since 1980<sup id="fnref:1"><a href="#fn:1" class="footnote">1</a></sup></p>
+
+<!-- Sources section automatically appended -->
+<div class="footnotes-section">
+  <button class="footnotes-header">
+    <h3>Sources/References</h3>
+  </button>
+  <div class="footnotes-content">
+    <ol class="footnotes">
+      <li id="fn:1">
+        <p>
+          IPCC. (2023). Climate Change 2023: Synthesis Report.
+          <a href="#fnref:1" class="footnote-backref">↩</a>
+        </p>
+      </li>
+    </ol>
+  </div>
+</div>
+```
+
+### Frontend Integration
+
+The sources section includes data attributes for integration with JavaScript frameworks like Stimulus:
+
+- `data-footnotes-target="toggle"` - Toggle button
+- `data-footnotes-target="content"` - Collapsible content
+- `data-footnotes-target="chevron"` - Chevron icon for rotation
+
+See [docs/FOOTNOTES.md](docs/FOOTNOTES.md) for detailed implementation examples.
+
+### Auto-linking URLs
+
+Enable automatic URL linking in footnote content:
+
+```ruby
+renderer = Panda::Editor::Renderer.new(@content, autolink_urls: true)
+html = renderer.render
+```
+
+When enabled, plain URLs in footnotes are automatically converted to clickable links:
+
+**Input:**
+```
+Study by Ward et al. (2021). https://doi.org/10.1111/camh.12471
+```
+
+**Output:**
+```html
+Study by Ward et al. (2021). <a href="https://doi.org/10.1111/camh.12471" target="_blank" rel="noopener noreferrer">https://doi.org/10.1111/camh.12471</a>
+```
+
+Features:
+- Opens links in new tab with `target="_blank"`
+- Includes `rel="noopener noreferrer"` for security
+- Won't double-link URLs already in `<a>` tags
+- Supports `http://`, `https://`, `ftp://`, and `www.` URLs
+- Handles multiple URLs in the same footnote
+
+To enable globally for all content using the `Panda::Editor::Content` concern, pass the option in `generate_cached_content`.
+
 ## Configuration
 
 ```ruby

data/app/javascript/panda/editor/application.js

@@ -4,15 +4,23 @@
 import { EditorJSInitializer } from "./editor_js_initializer"
 import { EditorJSConfig } from "./editor_js_config"
 import { RichTextEditor } from "./rich_text_editor"
+import FootnoteTool from "./tools/footnote_tool"
+import ParagraphWithFootnotes from "./tools/paragraph_with_footnotes"
 
 // Export for global access
 window.PandaEditor = {
   EditorJSInitializer,
   EditorJSConfig,
   RichTextEditor,
+  FootnoteTool,
+  ParagraphWithFootnotes,
   VERSION: "0.1.0"
 }
 
+// Make tools available globally for EditorJS
+window.FootnoteTool = FootnoteTool
+window.ParagraphWithFootnotes = ParagraphWithFootnotes
+
 // Auto-initialize on DOMContentLoaded
 document.addEventListener("DOMContentLoaded", () => {
   console.log("[Panda Editor] Loaded v" + window.PandaEditor.VERSION)

data/app/javascript/panda/editor/editor_js_config.js

@@ -185,6 +185,30 @@ export const EDITOR_JS_CSS = `
     margin: 0 !important;
     padding: 0 !important;
   }
+
+  /* Footnote marker styles */
+  .footnote-marker {
+    display: inline-block;
+    color: #3b82f6;
+    font-size: 0.75em;
+    font-weight: 600;
+    vertical-align: super;
+    cursor: pointer;
+    padding: 0 2px;
+    user-select: none;
+    margin-left: 1px;
+  }
+
+  .footnote-marker:hover {
+    color: #2563eb;
+    text-decoration: underline;
+  }
+
+  /* Inline toolbar button for footnote */
+  .ce-inline-tool--footnote svg {
+    width: 17px;
+    height: 17px;
+  }
 `
 
 export const getEditorConfig = (elementId, previousData, doc = document) => {
@@ -230,7 +254,7 @@ export const getEditorConfig = (elementId, previousData, doc = document) => {
         }
       },
       paragraph: {
-        class: win.Paragraph,
+        class: win.ParagraphWithFootnotes || win.Paragraph,
         inlineToolbar: true,
         config: {
           placeholder: 'Start writing or press Tab to add content...'
@@ -276,6 +300,9 @@ export const getEditorConfig = (elementId, previousData, doc = document) => {
             vimeo: true
           }
         }
+      },
+      footnote: {
+        class: win.FootnoteTool
       }
     }
   }

data/app/javascript/panda/editor/editor_js_initializer.js

@@ -211,7 +211,7 @@ export class EditorJSInitializer {
         placeholder: 'Click to start writing...',
         tools: {
           paragraph: {
-            class: win.Paragraph,
+            class: win.ParagraphWithFootnotes || win.Paragraph,
             inlineToolbar: true,
             config: {
               preserveBlank: true,
@@ -242,6 +242,9 @@ export class EditorJSInitializer {
               quotePlaceholder: 'Enter a quote',
               captionPlaceholder: 'Quote\'s author'
             }
+          },
+          footnote: {
+            class: win.FootnoteTool
           }
         },
         onChange: (api, event) => {

data/app/javascript/panda/editor/rich_text_editor.js

@@ -5,6 +5,8 @@ import List from "@editorjs/list"
 import Quote from "@editorjs/quote"
 import Table from "@editorjs/table"
 import NestedList from "@editorjs/nested-list"
+import FootnoteTool from "./tools/footnote_tool"
+import ParagraphWithFootnotes from "./tools/paragraph_with_footnotes"
 
 export default class RichTextEditor {
   constructor(element, iframe) {
@@ -72,7 +74,7 @@ export default class RichTextEditor {
         placeholder: "Click to start writing...",
         tools: {
           paragraph: {
-            class: Paragraph,
+            class: ParagraphWithFootnotes,
             inlineToolbar: true
           },
           header: {
@@ -94,6 +96,9 @@ export default class RichTextEditor {
           table: {
             class: Table,
             inlineToolbar: true
+          },
+          footnote: {
+            class: FootnoteTool
           }
         },
         onChange: () => {

data/app/javascript/panda/editor/tools/footnote_tool.js

@@ -0,0 +1,392 @@
+/**
+ * FootnoteTool - EditorJS Inline Tool for adding footnotes
+ *
+ * This tool allows users to add footnotes to text by:
+ * 1. Selecting text and clicking the footnote button
+ * 2. Entering the citation content in a modal
+ * 3. Automatically generating a unique ID
+ * 4. Storing the footnote data in the paragraph block
+ * 5. Displaying a visual marker (superscript number) in the editor
+ */
+
+export default class FootnoteTool {
+  /**
+   * EditorJS inline tool interface
+   */
+  static get isInline() {
+    return true;
+  }
+
+  static get title() {
+    return 'Footnote';
+  }
+
+  /**
+   * Sanitize config - allow sup tags with our footnote classes
+   */
+  static get sanitize() {
+    return {
+      sup: {
+        class: 'footnote-marker'
+      }
+    };
+  }
+
+  /**
+   * Constructor
+   * @param {object} params - Tool parameters from EditorJS
+   */
+  constructor({ api }) {
+    this.api = api;
+    this.button = null;
+    this.state = false;
+
+    // Store reference to active footnotes for this paragraph
+    this.footnotes = [];
+
+    // CSS classes
+    this.CSS = {
+      button: 'ce-inline-tool',
+      buttonActive: 'ce-inline-tool--active',
+      buttonModifier: 'ce-inline-tool--footnote'
+    };
+
+    // SVG icon for superscript/footnote
+    this.iconSVG = `<svg xmlns="http://www.w3.org/2000/svg" width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <text x="2" y="18" font-size="14" font-weight="bold">fn</text>
+      <text x="12" y="8" font-size="8" font-weight="bold">1</text>
+    </svg>`;
+  }
+
+  /**
+   * Create button for inline toolbar
+   */
+  render() {
+    this.button = document.createElement('button');
+    this.button.type = 'button';
+    this.button.classList.add(this.CSS.button, this.CSS.buttonModifier);
+    this.button.innerHTML = this.iconSVG;
+
+    return this.button;
+  }
+
+  /**
+   * Handle click on the footnote button
+   * @param {Range} range - Selected text range
+   */
+  surround(range) {
+    if (this.state) {
+      // Remove footnote if already exists
+      this.unwrap(range);
+      return;
+    }
+
+    // Get the selected text position within the paragraph
+    const position = this.getCaretPosition(range);
+
+    // Show modal to collect footnote content
+    this.showFootnoteModal((content) => {
+      if (!content || content.trim() === '') {
+        return;
+      }
+
+      // Generate unique ID
+      const footnoteId = this.generateFootnoteId();
+
+      // Wrap selection with marker (stores content in data attribute)
+      this.wrap(range, footnoteId, content.trim());
+    });
+  }
+
+  /**
+   * Wrap selected text with footnote marker
+   * @param {Range} range - Selected text range
+   * @param {string} footnoteId - Unique footnote identifier
+   * @param {string} content - Footnote content/citation
+   */
+  wrap(range, footnoteId, content) {
+    const marker = document.createElement('sup');
+    marker.classList.add('footnote-marker');
+    marker.dataset.footnoteId = footnoteId;
+    marker.dataset.footnoteContent = content; // Store content in data attribute
+    marker.contentEditable = false;
+
+    // Insert marker at the end of selection
+    range.collapse(false); // Collapse to end
+    range.insertNode(marker);
+
+    // Move cursor after marker
+    range.setStartAfter(marker);
+    range.collapse(true);
+
+    // Update selection
+    const selection = window.getSelection();
+    selection.removeAllRanges();
+    selection.addRange(range);
+
+    // Renumber all footnotes in the document
+    setTimeout(() => this.renumberAllFootnotes(), 0);
+  }
+
+  /**
+   * Remove footnote marker
+   * @param {Range} range - Selected text range
+   */
+  unwrap(range) {
+    const marker = this.findMarkerInRange(range);
+    if (marker) {
+      marker.remove();
+
+      // Renumber remaining footnotes
+      setTimeout(() => this.renumberAllFootnotes(), 0);
+    }
+  }
+
+  /**
+   * Check if current selection has a footnote
+   * @param {Range} range - Current selection range
+   */
+  checkState(selection) {
+    if (!selection || !selection.anchorNode) {
+      this.state = false;
+      return false;
+    }
+
+    const marker = this.findMarkerInSelection(selection);
+    this.state = !!marker;
+
+    return this.state;
+  }
+
+  /**
+   * Find footnote marker in current selection
+   * @param {Selection} selection - Current selection
+   * @returns {Element|null} Footnote marker element if found
+   */
+  findMarkerInSelection(selection) {
+    if (!selection.anchorNode) return null;
+
+    let node = selection.anchorNode;
+
+    // Traverse up to find marker
+    while (node && node !== this.api.blocks.getCurrentBlockIndex()) {
+      if (node.nodeType === Node.ELEMENT_NODE &&
+          node.tagName === 'SUP' &&
+          node.classList.contains('footnote-marker')) {
+        return node;
+      }
+      node = node.parentNode;
+    }
+
+    return null;
+  }
+
+  /**
+   * Find footnote marker in a range
+   * @param {Range} range - Selection range
+   * @returns {Element|null} Footnote marker element if found
+   */
+  findMarkerInRange(range) {
+    const container = range.commonAncestorContainer;
+
+    if (container.nodeType === Node.ELEMENT_NODE &&
+        container.classList.contains('footnote-marker')) {
+      return container;
+    }
+
+    const markers = container.querySelectorAll?.('.footnote-marker');
+    return markers?.[0] || null;
+  }
+
+  /**
+   * Get caret position within the paragraph text
+   * @param {Range} range - Current selection range
+   * @returns {number} Character position
+   */
+  getCaretPosition(range) {
+    const block = this.api.blocks.getBlockByIndex(this.api.blocks.getCurrentBlockIndex());
+    const blockElement = block.holder;
+    const contentElement = blockElement.querySelector('.ce-paragraph');
+
+    if (!contentElement) return 0;
+
+    // Create a range from start of content to current position
+    const preCaretRange = range.cloneRange();
+    preCaretRange.selectNodeContents(contentElement);
+    preCaretRange.setEnd(range.endContainer, range.endOffset);
+
+    // Get text content length (position)
+    return preCaretRange.toString().length;
+  }
+
+  /**
+   * Generate a unique footnote ID
+   * @returns {string} Unique identifier
+   */
+  generateFootnoteId() {
+    return `fn-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Renumber all footnotes in the entire document
+   * Scans all blocks and updates footnote marker numbers sequentially
+   */
+  renumberAllFootnotes() {
+    try {
+      const blocksCount = this.api.blocks.getBlocksCount();
+      let footnoteNumber = 0;
+
+      // Scan through all blocks in order
+      for (let i = 0; i < blocksCount; i++) {
+        const block = this.api.blocks.getBlockByIndex(i);
+        if (!block) continue;
+
+        const blockElement = block.holder;
+        const markers = blockElement.querySelectorAll('.footnote-marker');
+
+        // Update each marker in this block
+        markers.forEach(marker => {
+          footnoteNumber++;
+          marker.textContent = footnoteNumber.toString();
+        });
+      }
+
+      console.debug('[Footnote Tool] Renumbered', footnoteNumber, 'footnotes');
+    } catch (error) {
+      console.error('[Footnote Tool] Error renumbering footnotes:', error);
+    }
+  }
+
+
+  /**
+   * Show modal dialog to collect footnote content
+   * @param {Function} onSave - Callback when user saves
+   */
+  showFootnoteModal(onSave) {
+    // Create modal overlay
+    const overlay = document.createElement('div');
+    overlay.className = 'footnote-modal-overlay';
+    overlay.style.cssText = `
+      position: fixed;
+      top: 0;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      background: rgba(0, 0, 0, 0.5);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      z-index: 10000;
+    `;
+
+    // Create modal content
+    const modal = document.createElement('div');
+    modal.className = 'footnote-modal';
+    modal.style.cssText = `
+      background: white;
+      border-radius: 8px;
+      padding: 24px;
+      max-width: 500px;
+      width: 90%;
+      box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+    `;
+
+    modal.innerHTML = `
+      <h3 style="margin: 0 0 16px 0; font-size: 18px; font-weight: 600;">Add Footnote</h3>
+      <div style="margin-bottom: 16px;">
+        <label style="display: block; margin-bottom: 8px; font-size: 14px; font-weight: 500;">
+          Citation Content
+        </label>
+        <textarea
+          class="footnote-content-input"
+          placeholder="Enter citation or reference (e.g., Smith, J. et al. (2023). Study Title. Journal Name.)"
+          style="
+            width: 100%;
+            min-height: 100px;
+            padding: 8px 12px;
+            border: 1px solid #d1d5db;
+            border-radius: 4px;
+            font-size: 14px;
+            font-family: inherit;
+            resize: vertical;
+          "
+        ></textarea>
+        <p style="margin: 8px 0 0 0; font-size: 12px; color: #6b7280;">
+          Tip: You can paste URLs directly - they'll be automatically converted to clickable links.
+        </p>
+      </div>
+      <div style="display: flex; gap: 8px; justify-content: flex-end;">
+        <button class="footnote-cancel-btn" style="
+          padding: 8px 16px;
+          border: 1px solid #d1d5db;
+          border-radius: 4px;
+          background: white;
+          color: #374151;
+          font-size: 14px;
+          font-weight: 500;
+          cursor: pointer;
+        ">Cancel</button>
+        <button class="footnote-save-btn" style="
+          padding: 8px 16px;
+          border: none;
+          border-radius: 4px;
+          background: #3b82f6;
+          color: white;
+          font-size: 14px;
+          font-weight: 500;
+          cursor: pointer;
+        ">Add Footnote</button>
+      </div>
+    `;
+
+    overlay.appendChild(modal);
+    document.body.appendChild(overlay);
+
+    // Get elements
+    const textarea = modal.querySelector('.footnote-content-input');
+    const saveBtn = modal.querySelector('.footnote-save-btn');
+    const cancelBtn = modal.querySelector('.footnote-cancel-btn');
+
+    // Focus textarea
+    setTimeout(() => textarea.focus(), 0);
+
+    // Handle save
+    const handleSave = () => {
+      const content = textarea.value;
+      onSave(content);
+      overlay.remove();
+    };
+
+    // Handle cancel
+    const handleCancel = () => {
+      overlay.remove();
+    };
+
+    // Event listeners
+    saveBtn.addEventListener('click', handleSave);
+    cancelBtn.addEventListener('click', handleCancel);
+    overlay.addEventListener('click', (e) => {
+      if (e.target === overlay) {
+        handleCancel();
+      }
+    });
+
+    // Handle Enter key (with Shift for new line)
+    textarea.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        handleSave();
+      } else if (e.key === 'Escape') {
+        e.preventDefault();
+        handleCancel();
+      }
+    });
+  }
+
+  /**
+   * Optional: Clear tool state
+   */
+  clear() {
+    this.state = false;
+  }
+}