MediaWiki:Gadget-GrAnnotations.js: Difference between revisions

  * gr_annotations.js  —  grantha.io inline Comments + Bookmarks

  * BEHAVIOUR (mirrors Google Docs)

  * ────────────────────────────────

  * 1. User selects text anywhere in mw-content-text.

* 2. A floating action strip (FAB) appears to the right of the selection

*    with two icon buttons: Comment and Bookmark.

  * 3. Clicking Comment:

*    - On submit: wraps the selected text in a yellow highlight span,

*      saves the comment to <PageTitle>/Comments via MW edit API,

*      posts a notification to the admin user talk page,

  *     and adds a card to the Comments tab of the right panel.

*    - Opens a small composer to name the bookmark.

*    - On submit: wraps selected text in a blue highlight span,

*      and adds a card to the Bookmarks tab.

  *   - Clicking a bookmark card scrolls to and flashes that highlight.

* 5. Right panel:

*    - Slides in from the right as an overlay (no layout shift).

  *   - Tab 1: Comments  (loads from /Comments wiki page)

*    - Opens the panel to the correct tab and scrolls to the card.

* On new comment: sends email via MW EmailUser API (action=emailuser).

  * Email contains the comment text and a direct anchor link to the passage.

* Fallback: if admin has no email set, posts to User_talk:ADMIN_USER instead.

* Requires $wgEnableEmail = true and $wgEnableUserEmail = true (MW defaults).

  * • jQuery (loaded by MediaWiki)

* • mw.Api  (MediaWiki core)

  * • gr_annotations.css  (companion stylesheet)

* a gadget in MediaWiki:Gadgets-definition:

*  GrAnnotations[ResourceLoader|default]|gr_annotations.js|gr_annotations.css

   var ADMIN_USER  = 'GranthaGate';

   var CONTENT_SEL = '#mw-content-text';

   var BM_LS_KEY   = 'grantha_bm_'  + ( ( window.mw && mw.config.get( 'wgPageName' ) ) || '' );

   var CMT_LS_KEY  = 'grantha_cmt_' + ( ( window.mw && mw.config.get( 'wgPageName' ) ) || '' );

   var pageTitle   = ( window.mw && mw.config.get( 'wgPageName' ) ) || '';

   var commentsPage = 'Talk:' + pageTitle + '/GrComments';

   var currentUser  = ( window.mw && mw.config.get( 'wgUserName' ) ) || '';

   var userInitial = currentUser ? currentUser.charAt( 0 ).toUpperCase() : '?';

   var _selRange  = null;   // saved Range for wrapping

   var _selText    = '';     // selected text string

   var _selRect    = null;   // bounding rect of selection

   var _comments  = [];     // [{id, anchor, author, ts, quote, text}]

   var _bookmarks  = [];     // [{id, name, quote, anchorHtml, ts}]

   var _cmtLoaded = false;

   var _activeTab = 'comments'; // 'comments' | 'bookmarks'

   function uid() {

    return 'gra_' + Date.now() + '_' + Math.random().toString(36).slice(2,7);

   function nowIso() {

    return new Date().toISOString().replace(/\.\d{3}Z$/,'Z');

  }

   function fmtTs( ts ) {

       var d = new Date( ts );

   function clamp( val, min, max ) { return Math.max(min, Math.min(max, val)); }

   // ── DOM references (populated in boot) ───────────────────────────────

   var $fab, $panel, $backdrop, $panelBody;

   var $cmpComposer, $cmpInput, $cmpSubmit;

   var $tabComments, $tabBookmarks;

   var $paneComments, $paneBookmarks;

 

     // ── Floating action strip ────────────────────────────────────────

       '<div id="gra-fab">',

       '  <button class="gra-fab-btn" id="gra-fab-comment" type="button">',

       '    <span class="gra-icon gra-icon-comment"></span>',

       '    <span class="gra-fab-tooltip">Add comment</span>',

       '  <button class="gra-fab-btn" id="gra-fab-bookmark" type="button">',

       '    <span class="gra-icon gra-icon-bookmark"></span>',

     $( 'body' ).append( $fab );

     // ── Comment composer card ────────────────────────────────────────

     $cmpComposer = $( [

       '<div class="gra-composer" id="gra-cmp-composer">',

       '    <div class="gra-avatar" id="gra-cmp-avatar">' + esc(userInitial) + '</div>',

       '    <div class="gra-composer-name" id="gra-cmp-name">' + esc(currentUser || 'Anonymous') + '</div>',

       '  <textarea class="gra-composer-input" id="gra-cmp-input"',

      '    placeholder="Comment or add others with @…" rows="3"></textarea>',

       '    <button class="gra-btn-cancel" id="gra-cmp-cancel">Cancel</button>',

       '    <button class="gra-btn-submit" id="gra-cmp-submit" disabled>Comment</button>',

     $( 'body' ).append( $cmpComposer );

     // ── Bookmark composer card ────────────────────────────────────────

       '<div class="gra-bm-composer" id="gra-bm-composer">',

       '    <span class="gra-icon gra-icon-bookmark"></span>',

       '  <input class="gra-composer-input" id="gra-bm-input"',

      '    type="text" placeholder="Bookmark name…" autocomplete="off">',

     $( 'body' ).append( $bmComposer );

       '<div id="gra-panel">',

       '    <div></div>',

       '    <button id="gra-panel-close" title="Close panel">✕</button>',

       '    <button class="gra-tab gra-tab-active" id="gra-tab-comments">',

       '      <span class="gra-icon gra-icon-comment"></span> Comments',

       '      <span class="gra-icon gra-icon-bookmark"></span> Bookmarks',

       '    <div class="gra-pane gra-pane-active" id="gra-pane-comments"></div>',

       '    <div class="gra-pane"             id="gra-pane-bookmarks"></div>',

     $( 'body' ).append( $panel );

     $backdrop = $('<div id="gra-backdrop"></div>');

     $( 'body' ).append( $backdrop );

       '<button id="gra-toggle" title="Comments &amp; Bookmarks">',

       '  <span class="gra-icon gra-icon-comment" id="gra-toggle-icon"></span>',

       '  <span id="gra-toggle-badge"></span>',

     $( 'body' ).append( $toggle );

     $toggle.on( 'click', function() {

       if ( $panel.hasClass('gra-panel-open') ) {

        closePanel();

       } else {

        openPanel( _activeTab );

     } );

    // Cache references

    // Set panel title to page name

      .text( pageTitle.replace(/_/g,' ').split('/')[0].slice(0,30) )

     // Disable comment submit when not logged in

     if ( !currentUser ) {

      $cmpSubmit.prop( 'disabled', true );

      $cmpComposer.find( '.gra-composer-actions' )

        .prepend( '<a href="' + esc( mw ? mw.util.getUrl('Special:UserLogin') : '/wiki/Special:UserLogin' ) +

                  '" style="font-size:11px;color:#999;margin-right:auto">Log in to comment</a>' );

   // FLOATING ACTION STRIP — position & show/hide

   function showFab( rect ) {

     if ( !rect ) return;

    // FAB uses position:fixed — coords are viewport-relative (no scroll offset needed).

    // Place strip to the right of the selection; if it would go off-screen, place to the left.

     var fabW = 46; var fabH = 84;

     var top  = rect.top + ( rect.height / 2 ) - ( fabH / 2 );

 

     if ( left + fabW > window.innerWidth - 8 ) {

      left = rect.left - fabW - 10;

     top = clamp( top, 8, window.innerHeight - fabH - 8 );

     left = clamp( left, 8, window.innerWidth - fabW - 8 );

 

     $fab.css({ top: top + 'px', left: left + 'px' }).addClass('gra-fab-visible');

   function hideFab() {

    $fab.removeClass('gra-fab-visible');

  }

   // SELECTION HANDLING

   function captureSelection() {

     var sel = window.getSelection();

    var range    = sel.getRangeAt(0);

     var text    = sel.toString().trim();

    var contentEl = document.querySelector( CONTENT_SEL );

     if ( !contentEl ) return false;

     var startEl = range.commonAncestorContainer;

    if ( startEl.nodeType === 3 ) startEl = startEl.parentNode;

    _selText  = text;

     _selRange = range.cloneRange();

     _selRect  = range.getBoundingClientRect();

    return true;

   }

   // COMPOSER POSITIONING

   function positionComposer( $el ) {

     if ( !_selRect ) return;

     // position:fixed — viewport coords only

     if ( left + composerW > window.innerWidth - 8 ) {

      left = window.innerWidth - composerW - 8;

     left = Math.max( left, 8 );

     if ( top + 160 > window.innerHeight ) {

      top = _selRect.top - 170;

     top = Math.max( top, 8 );

     $el.css({ top: top + 'px', left: left + 'px' });

   // WRAP SELECTION IN HIGHLIGHT SPAN

   function wrapSelection( id, cssClass ) {

     if ( !_selRange ) return null;

       _selRange.surroundContents( span );

     } catch ( e ) {

         var frag = _selRange.extractContents();

         var span2 = document.createElement('span');

         span2.className = cssClass;

         span2.setAttribute('data-gra-id', id);

         span2.appendChild( frag );

         _selRange.insertNode( span2 );

         return span2;

   // COMMENT FLOW

   function openCommentComposer() {

     hideFab();

     // Keep selection alive — blur the textarea briefly then refocus

     positionComposer( $cmpComposer );

     $cmpComposer.addClass('gra-composer-visible');

     $cmpInput.val('').focus();

   function closeCommentComposer() {

     $cmpComposer.removeClass('gra-composer-visible');

     $cmpInput.val('');

    $cmpSubmit.prop('disabled', true);

     _selRange = null;

    _selText = '';

    _selRect = null;

   function submitComment() {

     var text  = $cmpInput.val().trim();

    if ( !text || !currentUser ) return;

     var id    = uid();

    var ts    = nowIso();

     var quote = _selText.slice(0, 120) + ( _selText.length > 120 ? '…' : '' );

     // Wrap text in highlight span

     var span = wrapSelection( id, 'gra-comment-highlight' );

    if ( span ) span.setAttribute('data-gra-quote', quote);

     var entry = { id:id, author:currentUser, ts:ts, quote:quote, text:text };

     _comments.push( entry );

    persistCommentHighlight( id, quote );

     // Persist to wiki

     saveCommentToWiki( id, quote, text, ts );

     notifyAdmin( _activeId || '', quote, text, ts );

     // Update panel

    renderCommentCards();

    closeCommentComposer();

    openPanel('comments');

   function saveCommentToWiki( id, quote, text, ts ) {

     if ( !window.mw ) return;

    api.get({

      action:'query', prop:'revisions', titles:commentsPage,

    }).then(function(data){

      var existing = '';

      if (page.revisions && page.revisions[0]) {

        existing = rev.slots ? rev.slots.main.content : rev['*'] || '';

                + '| quote     = ' + quote.replace(/\n/g,' ') + '\n'

                + '| text     = ' + text.replace(/\n/g,' ')  + '\n'

      var updated = (existing.trim() ? existing.trim() + '\n\n' : '') + entry;

      api.postWithEditToken({

        action:'edit', title:commentsPage, text:updated,

        summary:'New comment by ' + currentUser + ' on [[' + pageTitle + ']] (stored off-page)',

      }).catch(function(){});

     }).catch(function(){});

   function notifyAdmin( anchorId, quote, commentText, ts ) {

     /* Send a real email to the admin via MW's built-in EmailUser API.

    *  1. The admin account (ADMIN_USER) has a confirmed email address set

    *  2. $wgEnableEmail and $wgEnableUserEmail are true in LocalSettings.php

    *      (both are true by default in MW).

    if ( !window.mw || !ADMIN_USER ) return;

    /* Build a deep-link URL with the anchor ID so the admin can jump

    * directly to the highlighted passage with one click. */

    var articlePath = ( mw.config.get('wgArticlePath') || '/wiki/$1' )

     var pageDisplay = pageTitle.replace( /_/g, ' ' );

     var subject    = '[Grantha] New comment on "' + pageDisplay + '"';

     var body        = 'A new comment has been posted on ' + pageDisplay + '.

                    + 'Posted by : ' + ( currentUser || 'Anonymous' ) + '

'

                    + 'Time      : ' + ts + '

'

                    + 'Passage   : "' + quote + '"

                    + 'Comment   :

 

 

                    + ( mw.config.get('wgArticlePath') || '/wiki/$1' )

                        .replace( '$1', 'Talk:' + pageTitle + '/GrComments' )

 

    new mw.Api().post({

      token:    mw.user.tokens.get( 'csrfToken' ),

     }).catch(function(){

      if ( !currentUser ) return;

      var adminTalk = 'User_talk:' + ADMIN_USER;

      var wikimsg = '== New comment on [[' + pageDisplay + ']] ==

                  + '; By: ' + ( currentUser || 'Anonymous' ) + '

                  + '; Passage: //' + quote + '//

 

                  + commentText.slice(0,500)

                  + ( commentText.length > 500 ? '

…' : '' )

 

[[User:Chandrashekars|Chandrashekars]] ([[User talk:Chandrashekars|talk]]) 10:47, 24 April 2026 (UTC)';

      new mw.Api().postWithEditToken({

        action:'edit', title:adminTalk, section:'new',

        sectiontitle:'Comment on ' + pageDisplay,

        text:wikimsg,

        bot:0,

      }).catch(function(){});

     });

   function loadComments( cb ) {

    if ( _cmtLoaded ) { if (cb) cb(); return; }

     if ( !window.mw ) { _cmtLoaded=true; if(cb)cb(); return; }

    new mw.Api().get({

      rvprop:'content', rvslots:'main', formatversion:2,

    }).then(function(data){

      var page = (data.query.pages||[])[0]||{};

        wt = rev.slots ? rev.slots.main.content : rev['*'] || '';

      }

    }).catch(function(){ _cmtLoaded=true; if(cb)cb(); });

 

   function parseCommentsWt( wt ) {

     var out = [];

    var re = /\{\{GrComment\s*\n([\s\S]*?)\}\}/g;

    var m;

    while ((m = re.exec(wt)) !== null) {

      var block = m[1];

      var lr = /\|\s*([\w_]+)\s*=\s*([\s\S]*?)(?=\n\||\n\}\}|$)/g;

        f[lm[1].trim()] = lm[2].trim();

      }

      if (f.id) out.push({

    }

     hideFab();

     positionComposer( $bmComposer );

     $bmInput.val('').focus();

     _selRange = null;

    _selText = '';

    _selRect = null;

     var name  = $bmInput.val().trim() || ( 'Bookmark ' + (_bookmarks.length+1) );

     var quote = _selText.slice(0,120) + (_selText.length>120?'…':'');

 

     var span = wrapSelection( id, 'gra-bookmark-highlight' );

     if ( span ) {

      span.setAttribute('data-gra-id', id);

      span.setAttribute('data-gra-name', name);

    }

 

     var entry = { id:id, name:name, quote:quote, ts:ts };

    _bookmarks.push( entry );

   function deleteBookmark( id ) {

     var span = document.querySelector('[data-gra-id="' + id + '"].gra-bookmark-highlight');

       var parent = span.parentNode;

       while (span.firstChild) parent.insertBefore(span.firstChild, span);

       parent.removeChild(span);

     persistBookmarks();

    renderBookmarkCards();

     try {

      var raw = localStorage.getItem(BM_LS_KEY);

      if (raw) _bookmarks = JSON.parse(raw) || [];

    } catch(e){ _bookmarks = []; }

   // PANEL — open / close / tabs

   function openPanel( tab ) {

     switchTab( _activeTab );

 

   function switchTab( tab ) {

     $tabComments.toggleClass('gra-tab-active', tab==='comments');

     $paneComments.toggleClass('gra-pane-active', tab==='comments');

     if (tab==='comments') {

      loadComments(function(){ renderCommentCards(); });

     } else {

      renderBookmarkCards();

   function renderCommentCards() {

     if ( _comments.length === 0 ) {

       $paneComments.html('<div class="gra-empty-state">No comments yet.<br>Select text and click 💬 to add one.</div>');

     _comments.slice().reverse().forEach(function(c){

       html += '<div class="gra-comment-card" data-gra-id="' + esc(c.id) + '">'

             + '<div class="gra-avatar">' + esc((c.author||'?').charAt(0).toUpperCase()) + '</div>'

             + (c.ts ? '<div class="gra-card-ts">' + esc(fmtTs(c.ts)) + '</div>' : '')

             + (c.quote ? '<div class="gra-card-quote">' + esc(c.quote) + '</div>' : '')

             + '<div class="gra-card-text">' + esc(c.text) + '</div>'

     $paneComments.html(html);

     if ( _bookmarks.length === 0 ) {

       $paneBookmarks.html('<div class="gra-empty-state">No bookmarks yet.<br>Select text and click 🔖 to save a bookmark.</div>');

       html += '<div class="gra-bookmark-card" data-gra-id="' + esc(b.id) + '">'

             + '<span class="gra-icon gra-icon-bookmark"></span>'

             + '<div class="gra-bookmark-name">' + esc(b.name) + '</div>'

             + (b.quote ? '<div class="gra-bookmark-quote">' + esc(b.quote) + '</div>' : '')

             + '<button class="gra-bookmark-del" data-del-id="' + esc(b.id) + '" title="Remove bookmark">×</button>'

   function scrollToHighlight( id ) {

     var el = document.querySelector('[data-gra-id="' + id + '"]');

     el.scrollIntoView({ behavior:'smooth', block:'center' });

     // ── Selection → show FAB ──────────────────────────────────────

     $( document ).on('mouseup keyup', function(e){

       // Small delay so selection is committed

       setTimeout(function(){

        if ( $cmpComposer.hasClass('gra-composer-visible') ) return;

        if ( $bmComposer.hasClass('gra-composer-visible') ) return;

        if ( captureSelection() ) {

          showFab( _selRect );

         } else {

          hideFab();

         }

       }, 20);

     // ── Click outside → hide FAB ──────────────────────────────────

     $( document ).on('mousedown', function(e){

       var $t = $(e.target);

       if ( !$t.closest('#gra-fab').length &&

          !$t.closest('.gra-composer').length &&

          !$t.closest('.gra-bm-composer').length ) {

        hideFab();

       }

     // ── FAB: Comment ──────────────────────────────────────────────

     $( '#gra-fab-comment' ).on('click', function(e){

       e.preventDefault();

       e.stopPropagation();

       if ( !captureSelection() ) return;

       openCommentComposer();

     // ── FAB: Bookmark ─────────────────────────────────────────────

     $( '#gra-fab-bookmark' ).on('click', function(e){

       e.preventDefault();

       e.stopPropagation();

       if ( !captureSelection() ) return;

     // ── Comment composer ──────────────────────────────────────────

     $cmpInput.on('input', function(){

       $cmpSubmit.prop('disabled', !$(this).val().trim() || !currentUser);

     $( '#gra-cmp-cancel' ).on('click', function(){

       closeCommentComposer();

      hideFab();

     $cmpSubmit.on('click', submitComment);

     $cmpInput.on('keydown', function(e){

       // Ctrl+Enter or Cmd+Enter submits

       if ((e.ctrlKey||e.metaKey) && e.key==='Enter') { submitComment(); }

       if (e.key==='Escape') { closeCommentComposer(); hideFab(); }

     $( '#gra-bm-cancel' ).on('click', function(){

      closeBookmarkComposer();

    });

       if (e.key==='Escape'){ closeBookmarkComposer(); hideFab(); }

     // ── Panel close ───────────────────────────────────────────────

     $( '#gra-panel-close' ).on('click', closePanel);

     $backdrop.on('click', closePanel);

 

     // ── Tab switching ─────────────────────────────────────────────

     $tabComments.on('click', function(){ switchTab('comments'); });

     $paneComments.on('click', '.gra-comment-card', function(){

       if (id) scrollToHighlight(id);

       if (id) scrollToHighlight(id);

     $( CONTENT_SEL ).on('click', '.gra-comment-highlight', function(){

       openPanel('comments');

         var $card = $paneComments.find('[data-gra-id="'+id+'"]');

           $card[0].scrollIntoView({behavior:'smooth',block:'nearest'});

 

     $( CONTENT_SEL ).on('click', '.gra-bookmark-highlight', function(){

         if ($card.length) $card[0].scrollIntoView({behavior:'smooth',block:'nearest'});

     $( document ).on('keydown', function(e){

       if (e.key==='Escape'){

        if ($cmpComposer.hasClass('gra-composer-visible')) { closeCommentComposer(); hideFab(); }

        else if ($bmComposer.hasClass('gra-composer-visible')) { closeBookmarkComposer(); hideFab(); }

        else closePanel();

   // RESTORE BOOKMARK HIGHLIGHTS from localStorage on page load

 

   function persistCommentHighlight( id, quote ) {

       var stored = JSON.parse( localStorage.getItem( CMT_LS_KEY ) || '[]' );

       // Deduplicate

      stored = stored.filter( function(h){ return h.id !== id; } );

       stored.push( { id: id, quote: quote } );

       localStorage.setItem( CMT_LS_KEY, JSON.stringify( stored ) );