feat: support using provided func to generate references URL

BREAKING CHANGE: You must provide a getReferencesURL function.

Author: sqs

src/HoverOverlay.tsx

@@ -7,10 +7,8 @@ import * as React from 'react'
 import { MarkedString, MarkupContent, MarkupKind } from 'vscode-languageserver-types'
 import { asError, ErrorLike, isErrorLike } from './errors'
 import { highlightCodeSafe, renderMarkdown, toNativeEvent } from './helpers'
-import { HoveredTokenContext } from './hoverifier'
 import { HoveredToken } from './token_position'
 import { HoverMerged, LOADING } from './types'
-import { toPrettyBlobURL } from './url'
 
 /** The component used to render a link */
 export type LinkComponent = React.ComponentType<{ to: string } & React.HTMLAttributes<HTMLElement>>
@@ -31,7 +29,10 @@ const ButtonOrLink: React.StatelessComponent<
     )
 }
 
-export interface HoverOverlayProps {
+/**
+ * @template C Extra context for the hovered token.
+ */
+export interface HoverOverlayProps<C = {}> {
     /** What to show as contents */
     hoverOrError?: typeof LOADING | HoverMerged | null | ErrorLike // TODO disallow null and undefined
 
@@ -44,6 +45,13 @@ export interface HoverOverlayProps {
      */
     definitionURLOrError?: typeof LOADING | { jumpURL: string } | null | ErrorLike
 
+    /**
+     * The URL to navigate to to view references.
+     * If loaded, is set as the href of the find-references button.
+     * If undefined or null, the button is disabled.
+     */
+    referencesURL?: string | null
+
     /** The position of the tooltip (assigned to `style`) */
     overlayPosition?: { left: number; top: number }
 
@@ -54,7 +62,7 @@ export interface HoverOverlayProps {
      * The hovered token (position and word).
      * Used for the Find References buttons and for error messages
      */
-    hoveredToken?: HoveredToken & HoveredTokenContext
+    hoveredToken?: HoveredToken & C
 
     /** Whether to show the close button for the hover overlay */
     showCloseButton: boolean
@@ -81,8 +89,9 @@ export const isJumpURL = (val: any): val is { jumpURL: string } =>
 const transformMouseEvent = (handler: (event: MouseEvent) => void) => (event: React.MouseEvent<HTMLElement>) =>
     handler(toNativeEvent(event))
 
-export const HoverOverlay: React.StatelessComponent<HoverOverlayProps> = ({
+export const HoverOverlay: <C>(props: HoverOverlayProps<C>) => React.ReactElement<any> = ({
     definitionURLOrError,
+    referencesURL,
     hoveredToken,
     hoverOrError,
     hoverRef,
@@ -187,24 +196,18 @@ export const HoverOverlay: React.StatelessComponent<HoverOverlayProps> = ({
             >
                 Go to definition {definitionURLOrError === LOADING && <LoadingSpinner className="icon-inline" />}
             </ButtonOrLink>
-            <ButtonOrLink
-                linkComponent={linkComponent}
-                // tslint:disable-next-line:jsx-no-lambda
-                onClick={() => logTelemetryEvent('FindRefsClicked')}
-                to={
-                    hoveredToken &&
-                    toPrettyBlobURL({
-                        repoPath: hoveredToken.repoPath,
-                        rev: hoveredToken.rev,
-                        filePath: hoveredToken.filePath,
-                        position: hoveredToken,
-                        viewState: 'references',
-                    })
-                }
-                className="btn btn-secondary hover-overlay__action e2e-tooltip-find-refs"
-            >
-                Find references
-            </ButtonOrLink>
+            {hoveredToken &&
+                referencesURL && (
+                    <ButtonOrLink
+                        linkComponent={linkComponent}
+                        // tslint:disable-next-line:jsx-no-lambda
+                        onClick={() => logTelemetryEvent('FindRefsClicked')}
+                        to={referencesURL}
+                        className="btn btn-secondary hover-overlay__action e2e-tooltip-find-refs"
+                    >
+                        Find references
+                    </ButtonOrLink>
+                )}
         </div>
         {definitionURLOrError === null ? (
             <div className="alert alert-info hover-overlay__alert-below">

src/hoverifier.test.ts

@@ -134,7 +134,7 @@ describe('Hoverifier', () => {
                 const fetchHover = createStubHoverFetcher({})
                 const fetchJumpURL = createStubJumpURLFetcher('def')
 
-                const adjustPosition: PositionAdjuster = ({ direction, position }) => {
+                const adjustPosition: PositionAdjuster<{}> = ({ direction, position }) => {
                     adjustmentDirections.next(direction)
 
                     return of(position)

src/hoverifier.ts

@@ -43,12 +43,14 @@ import {
     getTokenAtPosition,
     HoveredToken,
 } from './token_position'
-import { EMODENOTFOUND, HoverMerged, LOADING } from './types'
-import { FileSpec, LineOrPositionOrRange, RepoSpec, ResolvedRevSpec, RevSpec } from './url'
+import { EMODENOTFOUND, HoverMerged, LineOrPositionOrRange, LOADING } from './types'
 
 export { HoveredToken }
 
-export interface HoverifierOptions {
+/**
+ * @template C Extra context for the hovered token.
+ */
+export interface HoverifierOptions<C extends object> {
     /**
      * Emit the HoverOverlay element on this after it was rerendered when its content changed and it needs to be repositioned.
      */
@@ -86,17 +88,20 @@ export interface HoverifierOptions {
      */
     logTelemetryEvent?: (event: string, data?: any) => void
 
-    fetchHover: HoverFetcher
-    fetchJumpURL: JumpURLFetcher
+    fetchHover: HoverFetcher<C>
+    fetchJumpURL: JumpURLFetcher<C>
+    getReferencesURL: (hoverToken: HoveredToken & C) => string | null
 }
 
 /**
  * A Hoverifier is a function that hoverifies one code view element in the DOM.
  * It will do very dirty things to it. Only call it if you're into that.
  *
  * There can be multiple code views in the DOM, which will only show a single HoverOverlay if the same Hoverifier was used.
+ *
+ * @template C Extra context for the hovered token.
  */
-export interface Hoverifier {
+export interface Hoverifier<C extends object> {
     /**
      * The current Hover state. You can use this to read the initial state synchronously.
      */
@@ -109,7 +114,7 @@ export interface Hoverifier {
     /**
      * Hoverifies a code view.
      */
-    hoverify(options: HoverifyOptions): Subscription
+    hoverify(options: HoverifyOptions<C>): Subscription
 
     unsubscribe(): void
 }
@@ -139,31 +144,42 @@ export enum AdjustmentDirection {
     ActualToCodeView,
 }
 
-export interface AdjustPositionProps {
+/**
+ * @template C Extra context for the hovered token.
+ */
+export interface AdjustPositionProps<C extends object> {
     /** The code view the token is in. */
     codeView: HTMLElement
     /** The position the token is at. */
-    position: HoveredToken & HoveredTokenContext
+    position: HoveredToken & C
     /** The direction the adjustment should go. */
     direction: AdjustmentDirection
 }
 
 /**
  * Function to adjust positions coming into and out of hoverifier. It can be used to correct the position used in HoverFetcher and
  * JumpURLFetcher requests and the position of th etoken to highlight in the code view. This is useful for code hosts that convert whitespace.
+ *
+ *
+ * @template C Extra context for the hovered token.
  */
-export type PositionAdjuster = (props: AdjustPositionProps) => SubscribableOrPromise<Position>
+export type PositionAdjuster<C extends object> = (props: AdjustPositionProps<C>) => SubscribableOrPromise<Position>
 
 /**
  * HoverifyOptions that need to be included internally with every event
+ *
+ * @template C Extra context for the hovered token.
  */
-export interface EventOptions {
-    resolveContext: ContextResolver
-    adjustPosition?: PositionAdjuster
+export interface EventOptions<C extends object> {
+    resolveContext: ContextResolver<C>
+    adjustPosition?: PositionAdjuster<C>
     dom: DOMFunctions
 }
 
-export interface HoverifyOptions extends EventOptions {
+/**
+ * @template C Extra context for the hovered token.
+ */
+export interface HoverifyOptions<C extends object> extends EventOptions<C> {
     positionEvents: Subscribable<PositionEvent>
 
     /**
@@ -190,9 +206,13 @@ export interface HoverState {
     selectedPosition?: LineOrPositionOrRange
 }
 
-interface InternalHoverifierState {
+/**
+ * @template C Extra context for the hovered token.
+ */
+interface InternalHoverifierState<C extends object> {
     hoverOrError?: typeof LOADING | HoverMerged | null | ErrorLike
     definitionURLOrError?: typeof LOADING | { jumpURL: string } | null | ErrorLike
+    referencesURL?: string | null
 
     hoverOverlayIsFixed: boolean
 
@@ -206,7 +226,7 @@ interface InternalHoverifierState {
     clickedGoToDefinition: false | 'same-tab' | 'new-tab'
 
     /** The currently hovered token */
-    hoveredToken?: HoveredToken & HoveredTokenContext
+    hoveredToken?: HoveredToken & C
 
     mouseIsMoving: boolean
 
@@ -221,13 +241,13 @@ interface InternalHoverifierState {
 /**
  * Returns true if the HoverOverlay component should be rendered according to the given state.
  */
-const shouldRenderOverlay = (state: InternalHoverifierState): boolean =>
+const shouldRenderOverlay = (state: InternalHoverifierState<{}>): boolean =>
     !(!state.hoverOverlayIsFixed && state.mouseIsMoving) && overlayUIHasContent(state)
 
 /**
  * Maps internal HoverifierState to the publicly exposed HoverState
  */
-const internalToExternalState = (internalState: InternalHoverifierState): HoverState => ({
+const internalToExternalState = (internalState: InternalHoverifierState<{}>): HoverState => ({
     selectedPosition: internalState.selectedPosition,
     hoverOverlayProps: shouldRenderOverlay(internalState)
         ? {
@@ -238,6 +258,7 @@ const internalToExternalState = (internalState: InternalHoverifierState): HoverS
                   isJumpURL(internalState.definitionURLOrError) || internalState.clickedGoToDefinition
                       ? internalState.definitionURLOrError
                       : undefined,
+              referencesURL: internalState.referencesURL,
               hoveredToken: internalState.hoveredToken,
               showCloseButton: internalState.hoverOverlayIsFixed,
           }
@@ -250,40 +271,52 @@ export const LOADER_DELAY = 300
 /** The time in ms after the mouse has stopped moving in which to show the tooltip */
 export const TOOLTIP_DISPLAY_DELAY = 100
 
-export type HoverFetcher = (position: HoveredToken & HoveredTokenContext) => SubscribableOrPromise<HoverMerged | null>
-export type JumpURLFetcher = (position: HoveredToken & HoveredTokenContext) => SubscribableOrPromise<string | null>
+/**
+ * @template C Extra context for the hovered token.
+ */
+export type HoverFetcher<C extends object> = (position: HoveredToken & C) => SubscribableOrPromise<HoverMerged | null>
+
+/**
+ * @template C Extra context for the hovered token.
+ */
+export type JumpURLFetcher<C extends object> = (position: HoveredToken & C) => SubscribableOrPromise<string | null>
 
 /**
  * Function responsible for resolving the position of a hovered token
  * and its diff part to a full context including repository, commit ID and file path.
+ *
+ * @template C Extra context for the hovered token.
  */
-export type ContextResolver = (hoveredToken: HoveredToken) => HoveredTokenContext
+export type ContextResolver<C extends object> = (hoveredToken: HoveredToken) => C
 
-export interface HoveredTokenContext extends RepoSpec, RevSpec, FileSpec, ResolvedRevSpec {}
-
-export const createHoverifier = ({
+/**
+ * @template C Extra context for the hovered token.
+ */
+export function createHoverifier<C extends object>({
     goToDefinitionClicks,
     closeButtonClicks,
     hoverOverlayRerenders,
     pushHistory,
     fetchHover,
     fetchJumpURL,
+    getReferencesURL,
     logTelemetryEvent = noop,
-}: HoverifierOptions): Hoverifier => {
+}: HoverifierOptions<C>): Hoverifier<C> {
     // Internal state that is not exposed to the caller
     // Shared between all hoverified code views
-    const container = createObservableStateContainer<InternalHoverifierState>({
+    const container = createObservableStateContainer<InternalHoverifierState<C>>({
         hoverOverlayIsFixed: false,
         clickedGoToDefinition: false,
         definitionURLOrError: undefined,
+        referencesURL: undefined,
         hoveredToken: undefined,
         hoverOrError: undefined,
         hoverOverlayPosition: undefined,
         mouseIsMoving: false,
         selectedPosition: undefined,
     })
 
-    interface MouseEventTrigger extends PositionEvent, EventOptions {}
+    interface MouseEventTrigger extends PositionEvent, EventOptions<C> {}
 
     // These Subjects aggregate all events from all hoverified code views
     const allPositionsFromEvents = new Subject<MouseEventTrigger>()
@@ -295,7 +328,7 @@ export const createHoverifier = ({
     const allCodeMouseOvers = allPositionsFromEvents.pipe(filter(isEventType('mouseover')))
     const allCodeClicks = allPositionsFromEvents.pipe(filter(isEventType('click')))
 
-    const allPositionJumps = new Subject<PositionJump & EventOptions>()
+    const allPositionJumps = new Subject<PositionJump & EventOptions<C>>()
 
     const subscription = new Subscription()
 
@@ -489,6 +522,13 @@ export const createHoverifier = ({
         share()
     )
 
+    /** Emits new referencesURL values. */
+    subscription.add(
+        resolvedPositions
+            .pipe(map(({ position }) => (position ? getReferencesURL(position) : null)))
+            .subscribe(referencesURL => container.update({ referencesURL }))
+    )
+
     /**
      * For every position, emits an Observable with new values for the `hoverOrError` state.
      * This is a higher-order Observable (Observable that emits Observables).
@@ -498,10 +538,10 @@ export const createHoverifier = ({
             eventType: SupportedMouseEvent | 'jump'
             dom: DOMFunctions
             target: HTMLElement
-            adjustPosition?: PositionAdjuster
+            adjustPosition?: PositionAdjuster<C>
             codeView: HTMLElement
             hoverOrError?: typeof LOADING | HoverMerged | Error | null
-            position?: HoveredToken & HoveredTokenContext
+            position?: HoveredToken & C
             part?: DiffPart
         }>
     > = resolvedPositions.pipe(
@@ -611,7 +651,7 @@ export const createHoverifier = ({
         zip(resolvedPositions, hoverObservables)
             .pipe(
                 distinctUntilChanged(([positionA], [positionB]) => isEqual(positionA, positionB)),
-                switchMap(([position, hoverObservable]) => hoverObservable),
+                switchMap(([, hoverObservable]) => hoverObservable),
                 filter(({ hoverOrError }) => HoverMerged.is(hoverOrError))
             )
             .subscribe(() => {
@@ -768,7 +808,7 @@ export const createHoverifier = ({
             map(internalToExternalState),
             distinctUntilChanged((a, b) => isEqual(a, b))
         ),
-        hoverify({ positionEvents, positionJumps = EMPTY, ...eventOptions }: HoverifyOptions): Subscription {
+        hoverify({ positionEvents, positionJumps = EMPTY, ...eventOptions }: HoverifyOptions<C>): Subscription {
             const subscription = new Subscription()
             const eventWithOptions = map((event: PositionEvent) => ({ ...event, ...eventOptions }))
             // Broadcast all events from this code view

src/overlay_position.test.ts

@@ -47,7 +47,7 @@ describe('overlay_position', () => {
                     position: absolute;
                 }
             `
-            document.head.appendChild(style)
+            document.head!.appendChild(style)
 
             relativeElement = document.createElement('div')
             relativeElement.className = 'relative-element'

src/testutils/lsp.ts

@@ -25,7 +25,7 @@ export const createHoverMerged = (hover: Partial<HoverMerged> = {}): HoverMerged
  * @param hover optional values to be passed to createHoverMerged
  * @param delayTime optionally delay the hover fetch
  */
-export function createStubHoverFetcher(hover: Partial<HoverMerged> = {}, delayTime?: number): HoverFetcher {
+export function createStubHoverFetcher(hover: Partial<HoverMerged> = {}, delayTime?: number): HoverFetcher<{}> {
     return () => of(createHoverMerged(hover)).pipe(delay(delayTime || 0))
 }
 
@@ -34,6 +34,6 @@ export function createStubHoverFetcher(hover: Partial<HoverMerged> = {}, delayTi
  * @param jumpURL optional value to emit as the url
  * @param delayTime optionally delay the jump url fetch
  */
-export function createStubJumpURLFetcher(jumpURL = '', delayTime?: number): JumpURLFetcher {
+export function createStubJumpURLFetcher(jumpURL = '', delayTime?: number): JumpURLFetcher<{}> {
     return () => of(jumpURL).pipe(delay(delayTime || 0))
 }