Radicle Patch Detail View: General Info

[gsaslis]

This issue is about the activity view that comes up from the Radicle Patch list items and the highlighted area in the screenshot below.

It contains read-only information:

• a checkout button that invokes rad patch checkout $patch_id,
• a refresh button that reloads the info from the API,
• the author,
• the source and target branches,
• an ordered list of comments and commits - ideally mixed, to reflect the order in which they happened
  • each list item should show author, commit hash, commit message title (or markdown-formatted comment text)
• patch description and comments must support markdown formatting
• an entry when a new revision is pushed, together with the revision description

There is a separate issue about the actions available on this view.

Resources:

• https://www.npmjs.com/package/vue3-markdown-it
• https://github.com/unplugin/unplugin-vue-markdown
• https://shikiji.netlify.app/

[gsaslis]

@maninak please take a look and let me know what you think

[gsaslis]

For context, the gitlab merge request "overview" (from the GitLab Workflow extension) follows a very similar design - perhaps with some parts a bit cleaner overall...

[maninak]

This (as well as multiple other new features) will require a Webview probably using those as components.

The thing is that this practically means that we start adding web-apps to our extension which is a major new tech capability, also affecting build/publishing pipelines etc. Practically everything that isn't a Welcome view like those we already know (with sync, fetch, announce buttons) or TreeView like the Patches View, has to be a Webview

@gsaslis , I suggest we scope that task out as a separate ticket as it adds significantly to the scope of this present one which is already sizeable.

[gsaslis]

@maninak makes sense, thanks for enlightening me here.

You mean creating the issue about adding Webview separately ? Wanna have a go at a description of what that would include?

[maninak]

I created #96 to cover the above

[gsaslis]

I created #96 to cover the above

thanks!

could you also please assign a size bucket ?

[maninak]

@gsaslis How can we know the source and target branches? I can see the base and oid fields inside a revision object but those as far as I've seen only point to a commit hash.

[gsaslis]

@gsaslis How can we know the source and target branches? I can see the base and oid fields inside a revision object but those as far as I've seen only point to a commit hash.

we can't. This information is not provided by the protocol at this point in time. at the moment, the only global branch is the defaultBranch and all patches are targeting that branch.

[maninak]

As agreed, I'll be deferring commit listing in the Activity section to a later task.

[maninak]

In the interest of time, this ended up having plenty of tangential and even non-related changes that I sneaked in while working on the long-standing branch due to the atomic effort it required.

Here's the list of all changes (sit comfortably and grab a snack for good measure):

✨ Highlights

• New Patch detail view

  

🚀 Enhancements

• patch-detail: implement new patch detail webview showing highly dynamic, in-depth information for a specific patch
  • can be opened via a new button "View Patch Details" on each item in the Patches view
  • panel's title shows the patch description in full if it's short, otherwise truncated to the nearest full word fitting the limit
  • the new view's design is purposefully minimal, glanceable, legible, responsive and verbose. It remains familiar to VS Code's native look'n'feel, while also staying true to Radicle's "hacky" vibe. Despite it being a full-fledged custom web-app under the hood, it successfully creates the illusion of it being just another piece of native VS Code UI.
  • view's theme adapts fully and on-the-fly (without reopening of the view) to whichever theme the user configures for his VS Code
  • view has the following main sections:
    • header
    • Patch
    • Revision
    • Activity
  • header section shows the following info:
    • status of the patch (e.g. open, merged, archived, ...)
      • the status badge's background color is a dynamic color mix of the patch status color and the dynamic editor-foreground color inherited from vscode's current theme so as to ensure text contrast reaching at least WCAAG AA level of accessibility at all times while also retaining a relative consistency of the colors across all our UIs and user-selected themes
    • major events like "created", "last updated", "merged" and related info with logic crafting optimal copy for each case (see similar tooltip improvements below)
    • a "Refresh" button that refetches from httpd all data of that patch and updating all views that depend on it
    • a "Check Out" button that checks out the Git branch associated with the Radicle patch shown in the view
      • shown only if the patch is not checked out
    • a "Check Out Default" button that checks out the Git branch marked as default for the Radicle project
      • shown only if the patch is checked out
    • "time-ago" for major patch events gets auto-updated to remain accurate as time goes by
  • Patch section shows the following info:
    • checked-out indicator
      • not shown if the Git branch associated with this Radicle patch is not currently checked out
    • id
      • has on-hover button to copy patch identifier to clipboard
    • revision author(s)
    • labels
      • not shown if empty
    • emoji reactions to the patch
      • if the total count of reactions is 4 or less, then the reacting users' alias/truncated-Nid are shown next to each reaction
      • if the total count of reactions is 5 or more, then the count of users with the same reaction are shown next to each reaction
      • shows, on hover, the Radicle identities behind each reaction in list-ified english copy
      • if the local Radicle identity is included in the reacting users, the reaction gets an additional visual cue
      • if a Radicle identity has already interacted in any other form in the patch, the identity's alias (if available) will be resolved and shown. Otherwise the identity's middle-truncated Nid (Node Identifier) will be shown (author alias is otherwise unavailable in the reaction entity).
    • title
      • supports markdown
    • description
      • supports markdown
  • Revision section shows the following info:
    • a revision selection dropdown located next to the section heading contains all revisions of the current patch as options
      • if a revision is merged it is auto-selected, otherwise it will be the most recently created
      • revisions are sorted as most-recent-top
      • revisions can be quickly browsed by using the up/down buttons while the dropdown is focused
      • revisions can be quickly searched by typing the beginning of a revision id while the dropdown is focused
      • revision are dynamically formatted so that the list can be scannable for a quick overview, while also showing only whatever info is necessary in each scenario, with the following data
        • shortened revision id
        • "mini"-sized "time-ago"
        • state
          • merged
            • suffixed with /<countOfMergedRevisions> if more than one revisions got merged e.g. merged/3
            • not shown if revision isn't merged
          • accepted
            • not shown if the revision doesn't have an accept review
          • rejected
            • not shown if the revision doesn't have a reject review
          • first
            • not shown if the revision isn't the earliest one for this patch or if it has only one revision
          • latest
            • not shown if the revision isn't the most recent one for this patch or if it has only one revision
          • sole
            • not shown if there are more than one revisions
          • not shown if empty
        • author
          • not shown if all revisions are from the same author
      • as the viewport is getting narrower the dropdown will respond by also becoming narrower to always fit within the webview. But when clicked to expand its popover listing the available revision options for selection, those options will always be shown in full, adjusting the scroll state as needed and restoring it when the popover is closed.
    • id
      • has on-hover button to copy revision identifier to clipboard
    • author
    • reviews
      • shows list of Radicle identity aliases who "accepted" and/or "rejected" the selected revision
      • not shown if empty
    • date
      • the full date the selected revision was created, in local timezone
      • shows the full date in standard ISO 8601 format
    • latest commit
      • the head commit of the selected revision
    • based on commit
      • the commit the selected revision is branched off of
    • emoji reactions to the revision
      • same behaviour as described for patch section
    • description
      • supports markdown
      • if the selected revision is the first revision, the description is hidden under an expand-on-click control (to avoid showing the same content twice since it's already shown in the Patch section)
      • not shown if empty
  • Activity section lists various patch-related events that took place across the lifetime of the patch. Each event is preceded by a "mini"-sized "time-ago" and a dedicated icon. A new event entry is listed for:
    • event for patch revision creation
      • if the patch and its first revision have the same id, the copy explicitly points that out, organically also educating the user about this Radicle fact
    • event for review of any revision, with the following data:
      • icon thumbs-up/thumbs-down/person-speaking matching the review verdict (accept/reject/null)
      • verdict of the review
      • a mention that the review was posted with "with code-inlined comments", if applicable
      • comment summary
        • not shown if empty
      • comment body
        • supports markdown
        • hidden under an expand-on-click control
        • not shown if empty
    • event for standalone-comment/discussion posted on a revision, with the following data:
      • icon comment/comment-unresolved, as well as clear textual indication for the latter case
      • whether the post was in reply to another former standalone comment
        • on click:
          • intelligently smooth-scrolls to bring that parent comment into view, if needed
          • shows a "pulse-outline" animation around the parent comment's event in the Activity section
      • comment body
        • supports markdown
        • hidden under an expand-on-click control
          • if the content is longer than 65 characters
          • or if the content is multi-paragraph, breaking among the first 65 chars (with use of double-line-break)
            • when multi-paragraph, only the first line is shown in the expand-on-click control's summary
          • control's summary shows unparsed Markdown
          • control's summary turns down to 50% opacity when expanded to further denote state and visually differentiate possibly duplicate content between summary and details
      • emoji reactions to the comment
        • same behaviour as described for patch section
    • patch merge
      • shown anew each time a different delegate merges the same patch (must happen multiple times for repos with this requirement set)
    • all of the above events also show:
      • shortened revision id
        • shows the revision description on hover, if available
        • on click:
          • selects that revision in the Revision section
          • intelligently smooth-scrolls to bring the Revision-selector control into view if needed
          • shows a "pulse-outline" animation around the Revision-selection control which just got updated
      • event author/initiator alias, or if not available, their truncated Did
        • shows the full Did on hover
  • the Activity an Revision sections come with fine-tuned responsiveness features depending on the webview viewport's width
    • when the viewport is wide they are shown in a 50/50 split two-column layout
    • as the viewport is getting narrower the Revision column gets narrower faster (resulting in e.g. 70/30 split) to prioritize giving the Activity section maximum of the available horizontal real-estate since it not only hosts relatively more important content, but also one that is commonly wrapping around into new lines due to how expansive it can be. Even a few pixels narrower Activity column can result in very quickly stretching it's contents vertically as it wraps around itself.
    • when the viewport becomes less than 640px the columns will collapse in a single one and the two respective sections will get joined in a tabbed layout. State such as the selected revision in the section's dropdown persist across tab switching and column-layout changes
  • Markdown parsing comes with multiple additional features such as

    • code highlighting with an aditional label communicating the language the code is identified and highlighted as

    • task list e.g. - [ ] task to do and - [X] task done

    • SVG

    • emoji e.g. :car: => 🚗

      • emoticons remain untouched e.g. :) => :) instead of it getting converted to 😀, which may not match the author's initial sentiment

    • marked text e.e. ==marked== => <mark>inserted</mark>

    • footnote references e.g.

      Here is a footnote reference,[^1] and another.[^longnote]
      
      [^1]: Here is the footnote.
      [^longnote]: Here's one with multiple blocks.

    • subscript e.g. C~7~H~14~O~2~

    • superscript e.g. x^2^

    • abbreviation e.g. this input:

      *[HTML]: Hyper Text Markup Language
      *[W3C]:  World Wide Web Consortium
      The HTML specification is maintained by the W3C.

      results in:

      <p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>

    • automatic table of contents generation wherever the marker [toc] is placed, based on previously declared headings etc

    • automatic linkification of text such as email URIs

  • patch state remains in sync with all other views
  • where applicable the various data have on-hover indicators hinting that they come with a tooltip which shows additional info such as author's DID, full Id in case it's shortened, or localised time (including the timezone used) in full text in case it's a "time-ago", etc
  • all data coming from Radicle is made visually distinct (and a bit more accessible / easier to read) from miscellaneous UI copy by rendering it using a monotype font
• commands: add new command to check out the current Radicle project's default Git branch
• patch-list: show button to "Check Out Default Git Branch" for the currently checked-out patch on the list
• patch-list: auto-retry fetching list of patches from httpd (with geometric back-off) if an error occured
• patch-list: show the total count of patches and when the list was last updated as a description next to the "Patches" view title
  • "updated-time-ago" gets auto-updated to remain accurate as time goes by or when the list is manually refreshed
  • in case of fetch error no count will be shown
• patch-list: improve patch tooltip with the following
  • show merge revision id and commit hash (if not already shown in revision event's copy) for merged patches
  • show latest revision id and commit hash for patches with more than the initial revision
• patch-list: prioritize patch merge event over latest revision when deriving author and "time-ago" for item's description and order in the list
• patch-list: improve legibility of time when patch events (e.g. created, last updated, merged) happened
  • don't show full dates to make the copy less noisy. The full dates are still available in the new patch detail view.
  • use custom "time-ago" logic producing more informative results with fewer collisions e.g. "35 days ago" instead of "1 month ago" etc
• patch-list: move button for command "Copy Patch Identifier to Clipboard" into patch item's context menu
• patch-list: use smaller dot as separator between data in the description of a patch item
• sidebar: the initial height of the Patches view (e.g. for new projects) will now be 4x that of the CLI Commands view, instead of having the area allocation split 50:50 which resulted in wasted empty space allocated to the later view while the former may have the need for more area to show more content. Subsequent adjustments by the user will be respected and not get overwritten by the initial size.
• onboarding: add the new default path ~/.radicle/bin/rad defined in https://radicle.xyz/install script to the list of watched paths previously defined for the legacy package-manager-based installers
• onboarding: replace current standard views and an error notification shown when the Radicle CLI binary didn't get resolved succesfully, with a new dedicated Welcome View explaining the situation, setting user expectations accordingly and offering to launch the troubleshooting flow via a button.
• onboarding: replace whichever Welcome View ends up randomly beeing shown for a split-second while the extension is acticating with an "Activating extension..." one
• commands: add new command to launch Radicle CLI installation troubleshooter (available only when binary hasn't resolved)

🔥 Performance

• patch-list: only re-render the affected patch item(s) when checking out a(nother) patch (or a non-patch) branch. Previously all patches had to be re-fetched, parsed and all their list items (and their tooltips!) needed to be instantiated and rendered every time a different git branch got checked out.
• app: shorten the amount of time the extension needs to get activated down to about 70% of what it was before

🩹 Fixes

• commands: don't always show empty project list for command radicle.clone command. Now the list will also be shown with the most seeded repos at the top. Addresses regression caused due to a breaking change in Radicle HTTP API (httpd).
• commands: fix radicle.clone command not showing number of users seeding each repo in the list items. Addresses regression caused due to a breaking change in Radicle HTTP API (httpd).
• onboarding: fix regression causing the extension to error out (with informative error message but still...) when the path to the Radicle CLI binary didn't resolve successfully.
• onboarding: re-check if repo is rad-initialized and as a result properly adjust which views are available if starting without a resolved Radicle CLI and then troubleshooting it successfully (e.g. installing it for the first time).

🏡 Chores

• state: rewrite shared state management across the entire extension from simplistic, localised, highly interdependent and brittle, procedural approach to a new declarative, reactive, global, scalable architecture powered by pinia and @vue/reactivity. This enables sharing state across sibling views/entities that was previously too hard, enabling more performant solutions and features that were previously too impractical to tackle, while the code for them can be much more maintainable and less likely to regress in the future.
• httpd: update typings to align with latest Radicle HTTP API endpoint schema updates

📖 Documentation

• readme: fix typos, improve title and intro copy, update milestone link
• contributing: document recommended extensions for development with VS Code in .vscode/extensions.json and add related section in the repo's contribution guide.
• update all references using the now deprecated term "track" to the new term "seed" aross our docs