add context menu for opening docs

samizdatco · Jul 9, 2026 · Jul 9, 2026 · Jul 9, 2026 · Jul 9, 2026 · Jul 9, 2026
commit a94fec77e4fe10fa770a97366d21bebd2981690e
diff --git a/app/Resources/ui/js/editor.js b/app/Resources/ui/js/editor.js
@@ -54,6 +54,13 @@ var Editor = function(elt){
             ed.hoverTooltip.setDataProvider(that._sampleHover)
             ed.hoverTooltip.addToEditor(ed)
 
+            // keep the native side informed of which documented symbol (if any) is
+            // under the pointer and/or text cursor, so the right-click context menu
+            // can offer a "View Documentation" item
+            that._docTarget = {mouse: null, caret: null}
+            ed.on("changeSelection", that._trackDocTarget)
+            ed.on("nativecontextmenu", that._trackDocTarget)
+
             // configure the buffer
             sess = ed.getSession()
             sess.setMode("ace/mode/plotdevice");
@@ -115,10 +122,25 @@ var Editor = function(elt){
 
         _isBindingTarget:function(token){
             // spot locations where a term is being used as a kwarg (or other assignment), so we can
-            // exclude it from the usage-sample tooltip (since it would only coincidentally share
-            // the name of a documented function in that case)
+            // exclude it from the usage-sample tooltip and doc-target tracking (since it would only
+            // coincidentally share the name of a documented function in that case)
             return !!token && (token.type === "variable.parameter" || token.type === "variable.assignment")
         },
+        _trackDocTarget:function(e){
+            // find the symbol currently under the mouse (if e is defined) or the insertion point (if not)
+            let coords = e?.domEvent
+            let pos = coords ? ed.renderer.screenToTextCoordinates(coords.clientX, coords.clientY) : ed.getCursorPosition()
+            var token = sess.getTokenAt(pos.row, pos.column)
+            var word = token && token.value
+
+            // if there's documentation for it (and it's changed since the last event), relay it to the pyobjc side
+            var url = (!that._isBindingTarget(token) && word && PLOTDEVICE_SYMBOL_DOCS[word]) || null
+            let inputType = coords ? "mouse" : "caret"
+            if (url !== that._docTarget[inputType]?.url){
+                that._docTarget[inputType] = url ? {word, url} : null
+                app.setDocTarget(that._docTarget)
+            }
+        },
         _sampleHover:function(e, editor){
             var pos = e.getDocumentPosition()
             var token = sess.getTokenAt(pos.row, pos.column)
@@ -141,7 +163,7 @@ var Editor = function(elt){
                     more.className = "ace_symbol-doc-more"
                     more.style.color = getComputedStyle(dom).color
                     var moreText = document.createElement("span")
-                    moreText.textContent = "read more…"
+                    moreText.textContent = "view documentation…"
                     more.appendChild(moreText)
                     more.addEventListener("click", function(){ app.openDoc(url) })
                     tooltip.appendChild(more)

diff --git a/plotdevice/gui/editor.py b/plotdevice/gui/editor.py
@@ -14,6 +14,13 @@
 def args(*jsargs):
     return ', '.join([json.dumps(v, ensure_ascii=False) for v in jsargs])
 
+def menu_index_of(menu, identifier):
+    # NSMenu has no indexOfItemWithIdentifier_ in this AppKit/PyObjC version; search manually
+    for i, item in enumerate(menu.itemArray()):
+        if item.identifier() == identifier:
+            return i
+    return -1
+
 class DraggyWebView(WKWebView):
     def draggingEntered_(self, sender):
         pb = sender.draggingPasteboard()
@@ -51,21 +58,35 @@ def willOpenMenu_withEvent_(self, menu, event):
         for item in list(menu.itemArray()):
             if item.identifier() not in keep:
                 menu.removeItem_(item)
-        inspect = menu.indexOfItemWithIdentifier_('WKMenuItemIdentifierInspectElement')
-        if inspect > 0:
+
+        # read _doc_target to get the tokens currently targeted by the mouse and caret
+        # then choose which one to offer a View Docs menu item for based on the event type
+        targets = getattr(self.owner, '_doc_target', None) or {}
+ if event.type() == NSEventTypeKeyDown else 'mouse')
+        if target:
+            idx = menu_index_of(menu, 'WKMenuItemIdentifierInspectElement')
+            idx = idx if idx >= 0 else menu.numberOfItems()
+            if menu.numberOfItems() > 0:
+                menu.insertItem_atIndex_(NSMenuItem.separatorItem(), idx)
+                idx += 1
+            prefix = u"View Documentation: "
+            title = prefix + target['word']
+            base_font = NSFont.menuFontOfSize_(0)
+            mono_font = NSFont.monospacedSystemFontOfSize_weight_(base_font.pointSize(), -0.8)
+            attr_title = NSMutableAttributedString.alloc().initWithString_attributes_(title, {"NSFont":base_font})
+            attr_title.addAttribute_value_range_("NSFont", mono_font, (len(prefix), len(target['word'])))
+            doc = NSMenuItem.alloc().initWithTitle_action_keyEquivalent_(title, "viewDocumentation:", "")
+            doc.setAttributedTitle_(attr_title)
+            doc.setTarget_(self)
+            doc.setRepresentedObject_(target['url'])
+            menu.insertItem_atIndex_(doc, idx)
+
+        inspect = menu_index_of(menu, 'WKMenuItemIdentifierInspectElement')
+        if inspect >= 0:
             menu.insertItem_atIndex_(NSMenuItem.separatorItem(), inspect)
 
-        # TODO: once a doc viewer exists, add a lookup-ref menu item pointing to it:
-        # word = self.js('editor.selected')
-        # _ns = ['curveto', 'TEXT', 'BezierPath', ...]
-        # def ref_url(proc):
-        #     if proc in _ns:
-        #         return proc
-        # if ref_url(word):
-        #     doc = NSMenuItem.alloc().initWithTitle_action_keyEquivalent_(u"Documentation for ‘%s()’"%word, "copy:", "")
-        #     sep = NSMenuItem.separatorItem()
-        #     items.insert(0, sep)
-        #     items.insert(0, doc)
+    def viewDocumentation_(self, sender):
+        self.owner.openDoc(sender.representedObject())
 
 
 class EditorView(NSView):
@@ -89,6 +110,7 @@ def awakeFromNib(self):
         ucc.addUserScript_(shim)
 
         self.webview = DraggyWebView.alloc().initWithFrame_configuration_(self.bounds(), config)
+        self.webview.owner = self
         if dev and self.webview.respondsToSelector_('setInspectable:'):
             self.webview.setInspectable_(True)
         self.webview.setValue_forKey_(False, 'drawsBackground')
@@ -159,7 +181,7 @@ def webViewWebContentProcessDidTerminate_(self, sender):
     def userContentController_didReceiveScriptMessage_(self, ucc, msg):
         body = msg.body()
         fn, fnargs = body['fn'], list(body.get('args', []))
-        if fn in ('sync_edits', 'flash_menu', 'setSearchPasteboard', 'cancelRun', 'loadPrefs', 'openDoc'):
+        if fn in ('sync_edits', 'flash_menu', 'setSearchPasteboard', 'cancelRun', 'loadPrefs', 'openDoc', 'setDocTarget'):
             getattr(self, fn)(*fnargs)
 
     def resizeSubviewsWithOldSize_(self, oldSize):
@@ -333,6 +355,10 @@ def loadPrefs(self):
     def openDoc(self, url):
         NSWorkspace.sharedWorkspace().openURL_(NSURL.URLWithString_(url))
 
+    @objc.python_method
+    def setDocTarget(self, target):
+        self._doc_target = target
+
     def cancelRun(self):
         # catch command-period even when the editor is first responder
         mm=NSApp().mainMenu()

diff --git a/plotdevice/lib/cocoa.py b/plotdevice/lib/cocoa.py
@@ -31,7 +31,7 @@
                    NSChangeRedone, NSChangeUndone, NSClipView, NSClosePathBezierPathElement, NSColor, NSColorSpace, \
                    NSCommandKeyMask, NSCompositeCopy, NSCompositeSourceOver, NSContentsCellMask, NSCriticalAlertStyle, NSCursor, \
                    NSCurveToBezierPathElement, NSDeviceCMYKColorSpace, NSDeviceIndependentModifierFlagsMask, NSDeviceRGBColorSpace, NSDocument, \
-                   NSDocumentController, NSDragOperationCopy, NSFindPboard, NSFixedPitchFontMask, NSFocusRingTypeExterior, NSFont, \
+                   NSDocumentController, NSDragOperationCopy, NSEventTypeKeyDown, NSFindPboard, NSFixedPitchFontMask, NSFocusRingTypeExterior, NSFont, \
                    NSFontDescriptor, NSFontManager, NSForegroundColorAttributeName, NSGIFFileType, NSGradient, \
                    NSGraphicsContext, NSGraphiteControlTint, NSImage, NSImageCacheNever, NSImageCompressionFactor, \
                    NSImageInterpolationHigh, NSItalicFontMask, NSJPEGFileType, NSJustifiedTextAlignment, \