ABC - Accurate 🖇️ Bi-directional 🖱️ Cursor-level linking system

Plugs and Libraries
14

Thank you for providing the schema that uses reverse arrows in the same color.

My original plan was to treat :soon_arrow: as the forward counterpart of :back_arrow:, but the added label “SOON” failed to evoke the sense of “Forth”.

After adopting :right_arrow: (instead of :soon_arrow:), I found the outcome unexpectedly successful: using differently colored arrows for forward and reverse directions significantly strengthens their visual contrast.

Thus, by coincidence, this evolved into one of my guiding design philosophies.
In the language of physics: asymmetry matters ;).
More precisely, logo pairs should form an asymmetric ∞ loop:

l[1] r[2]
F l — B r
X
B l — F r

or ◻ loop:

F[3] B[4]
F l — B r
| |
F r — B l

wherein,

F = For(ward/th)
B = Back(ward)
l = label
r = reference

Below are two more refined versions; the final one may well be definitive.

This first version is already distilled to its essence; it seems impossible to reduce it any further (aside from removing the icons as well -_-||).

image
image195×181 4.81 KB

function getSelectedText()
  local sel = editor.getSelection()
  if not sel or sel.from == sel.to then return nil end
  local text = editor.getText()
  return text:sub(sel.from + 1, sel.to)
end

function setSelectedText(newText)
  local sel = editor.getSelection()
  if not sel or sel.from == sel.to then return nil end
  editor.replaceRange(sel.from, sel.to, newText)
end

function usrPrompt(hinText, iniText)
  local iniText = iniText or ""
  local input = editor.prompt(hinText, iniText)
  if not input then
    editor.flashNotification("Cancelled", "warn")
  end
  return input
end

local suffixFlabel = "➡️"
local suffixBlabel = "🔙"

-- =========== Forth Anchor + Back Refs ==================

local function tableBack(Flabel)
  local aspiringPageBack = Flabel .. suffixBlabel
  return query[[
    from index.tag "link"
    where toPage and toPage:find(aspiringPageBack, 1, true)
    order by _.thBlabel
    select {ref=_.ref, thBlabel=_.thBlabel}
  ]]
end

function backRefs(Flabel)
  local str = template.each(tableBack(Flabel), template.new[==[​[[${_.ref}|${_.thBlabel}]]​]==])
  if #str == 0 then return "No BackRef" end
  return str
end

command.define {
  name = "Insert: ForthAnchor + BackRefs",
  key = "Ctrl-,",
  run = function()
    local iniText = getSelectedText()
    -- local Flabel = usrPrompt('Enter: label (to be Referred)', iniText)
    local Flabel
    if iniText and iniText ~= "" then
      Flabel = iniText
    else
      Flabel = usrPrompt('Enter: label (to be Referred)', '')
    end
    if not Flabel then return end
    local aspiringPageForth = Flabel .. suffixFlabel
    local forthAnchor = "[[" .. aspiringPageForth .. "||^|" .. suffixBlabel .. "]]"
    local backRefs = '${backRefs("' .. Flabel .. '")}'
    local fullText = forthAnchor .. backRefs
    if iniText and iniText ~= "" then
      setSelectedText("") -- Delete selected iniText
    end
    editor.insertAtPos(fullText, editor.getCursor(), true)
    editor.copyToClipboard(Flabel)
  end
}

-- =========== Back Anchor + Forth Ref ==================

local function tableForth(Flabel)
  local aspiringPageForth = Flabel .. suffixFlabel
  return query[[
    from index.tag "link"
    where toPage == aspiringPageForth
    select {ref=_.ref}
  ]]
end

function forthRef(Flabel, thBlabelNum)
  local str = template.each(tableForth(Flabel), template.new("[[${_.ref}|​" .. thBlabelNum .. "​]]"))
  if #str == 0 then return "No such Anchor" end
  return str
end

command.define {
  name = "Insert: BackAnchor + ForthRef",
  key = "Ctrl-.",
  run = function()
    local alias = getSelectedText()
    local iniText = js.window.navigator.clipboard.readText()
    -- local Flabel = usrPrompt('Jump to: label', iniText)
    local Flabel
    if iniText and iniText ~= "" then
      Flabel = iniText
    else
      Flabel = usrPrompt('Jump to: label', '')
    end
    if not Flabel then return end
    local thBlabelNum = #tableBack(Flabel) + 1
    local aspiringPageBack = Flabel .. suffixBlabel .. thBlabelNum
    local backAnchor = "[[" .. aspiringPageBack .. "||^|" .. suffixFlabel .. "]]"
    local forthRef = '${forthRef("' .. Flabel .. '",' .. thBlabelNum .. ')}'
    local fullText = backAnchor .. forthRef
    if alias and alias ~= "" then
      setSelectedText("") -- Delete selected alias
    else
      alias = ''
    end
    editor.insertAtPos(fullText, editor.getCursor(), true)
    editor.insertAtCursor(alias, false) -- scrollIntoView?
  end
}

index.defineTag {
  name = "link",
  metatable = {
    __index = function(self, attr)
      if attr == "thBlabel" then
        return tonumber(string.match(self.toPage, ".+" .. suffixBlabel .. "([0-9]+)"))
      end
    end
  }
}

The following second version builds upon the minimal form by adding siblings: it allows users to jump directly to other backward labels — those referencing the same forward label — without first navigating to the forward label itself, thereby eliminating yet another click.

image
image263×189 10.1 KB

function getSelectedText()
  local sel = editor.getSelection()
  if not sel or sel.from == sel.to then return nil end
  local text = editor.getText()
  return text:sub(sel.from + 1, sel.to)
end

function setSelectedText(newText)
  local sel = editor.getSelection()
  if not sel or sel.from == sel.to then return nil end
  editor.replaceRange(sel.from, sel.to, newText)
end

function usrPrompt(hinText, iniText)
  local iniText = iniText or ""
  local input = editor.prompt(hinText, iniText)
  if not input then
    editor.flashNotification("Cancelled", "warn")
  end
  return input
end

local suffixFlabel = "➡️"
local suffixBlabel = "🔙"
local siblings = "🧑‍🤝‍🧑"

-- =========== Forth Anchor + Back Refs ==================

local function tableBack(Flabel)
  local aspiringPageBack = Flabel .. suffixBlabel
  return query[[
    from index.tag "link"
    where toPage and toPage:find(aspiringPageBack, 1, true)
    order by _.thBlabel
    select {ref=_.ref, thBlabel=_.thBlabel}
  ]]
end

function backRefs(Flabel)
  local str = template.each(tableBack(Flabel), template.new[==[​[[${_.ref}|${_.thBlabel}]]​]==])
  if #str == 0 then return "No BackRef" end
  return str
end

command.define {
  name = "Insert: ForthAnchor + BackRefs",
  key = "Ctrl-,",
  run = function()
    local iniText = getSelectedText()
    -- local Flabel = usrPrompt('Enter: label (to be Referred)', iniText)
    local Flabel
    if iniText and iniText ~= "" then
      Flabel = iniText
    else
      Flabel = usrPrompt('Enter: label (to be Referred)', '')
    end
    if not Flabel then return end
    local aspiringPageForth = Flabel .. suffixFlabel
    local forthAnchor = "[[" .. aspiringPageForth .. "||^|" .. suffixBlabel .. "]]"
    local backRefs = '${backRefs("' .. Flabel .. '")}'
    local fullText = forthAnchor .. backRefs
    if iniText and iniText ~= "" then
      setSelectedText("") -- Delete selected iniText
    end
    editor.insertAtPos(fullText, editor.getCursor(), true)
    editor.copyToClipboard(Flabel)
  end
}

-- =========== Back Anchor + Forth Ref ==================

local function tableBack_noSelf(Flabel, thBlabelNum)
  local aspiringPageBack = Flabel .. suffixBlabel
  return query[[
    from index.tag "link"
    where toPage and toPage:find(aspiringPageBack, 1, true) and thBlabelNum ~= _.thBlabel
    order by _.thBlabel
    select {ref=_.ref, thBlabel=_.thBlabel}
  ]]
end

function backRefs_noSelf(Flabel, thBlabelNum)
  local str = template.each(tableBack_noSelf(Flabel, thBlabelNum), template.new[==[​[[${_.ref}|${_.thBlabel}]]​]==])
  if #str == 0 then return "No Sibling" end
  return str
end

local function tableForth(Flabel)
  local aspiringPageForth = Flabel .. suffixFlabel
  return query[[
    from index.tag "link"
    where toPage == aspiringPageForth
    select {ref=_.ref}
  ]]
end

function forthRef(Flabel, thBlabelNum)
  local str = template.each(tableForth(Flabel), template.new("[[${_.ref}|​" .. thBlabelNum .. "​]]"))
  if #str == 0 then return "No such Anchor" end
  return str
end

command.define {
  name = "Insert: BackAnchor + ForthRef",
  key = "Ctrl-.",
  run = function()
    local alias = getSelectedText()
    local iniText = js.window.navigator.clipboard.readText()
    -- local Flabel = usrPrompt('Jump to: label', iniText)
    local Flabel
    if iniText and iniText ~= "" then
      Flabel = iniText
    else
      Flabel = usrPrompt('Jump to: label', '')
    end
    if not Flabel then return end
    local thBlabelNum = #tableBack(Flabel) + 1
    local aspiringPageBack = Flabel .. suffixBlabel .. thBlabelNum
    local backAnchor = "[[" .. aspiringPageBack .. "||^|" .. suffixFlabel .. "]]"
    local forthRef = '${forthRef("' .. Flabel .. '",' .. thBlabelNum .. ')}'
    local backRefs_noSelf = '${backRefs_noSelf("' .. Flabel .. '",' .. thBlabelNum .. ')}'
    local fullText = backAnchor .. forthRef .. siblings .. backRefs_noSelf
    if alias and alias ~= "" then
      setSelectedText("") -- Delete selected alias
    else
      alias = ''
    end
    editor.insertAtPos(fullText, editor.getCursor(), true)
    editor.insertAtCursor(alias, false) -- scrollIntoView?
  end
}

index.defineTag {
  name = "link",
  metatable = {
    __index = function(self, attr)
      if attr == "thBlabel" then
        return tonumber(string.match(self.toPage, ".+" .. suffixBlabel .. "([0-9]+)"))
      end
    end
  }
}

  1. label ↩︎

  2. reference ↩︎

  3. For(ward/th) ↩︎

  4. Back(ward) ↩︎

3 Likes