@internetarchive/collection-browser 4.7.0 → 4.8.0

package/.claude/worktrees/WEBDEV-8677-bump-field-parsers/src/tiles/hover/hover-pane-controller.ts

@@ -1,638 +0,0 @@
-import type { SortParam } from '@internetarchive/search-service';
-import {
-  html,
-  HTMLTemplateResult,
-  nothing,
-  ReactiveController,
-  ReactiveControllerHost,
-} from 'lit';
-import type { TileModel } from '../../models';
-import type { CollectionTitles } from '../../data-source/models';
-import { msg } from '@lit/localize';
-
-type HoverPaneState = 'hidden' | 'shown' | 'fading-out';
-
-// the anchor point of the hover pane
-// can be either the mouse cursor or near the host element
-// in the case of mouse navigation, we want it to follow the cursor
-// in the case of keyboard navigation, we want it to appear near the host element
-type HoverPanePositionAnchor = 'host' | 'cursor';
-
-export interface HoverPaneProperties {
-  model?: TileModel;
-  baseNavigationUrl?: string;
-  baseImageUrl?: string;
-  loggedIn: boolean;
-  suppressBlurring: boolean;
-  sortParam: SortParam | null;
-  collectionTitles?: CollectionTitles;
-}
-
-export interface HoverPaneControllerOptions {
-  offsetX?: number;
-  offsetY?: number;
-  enableLongPress?: boolean;
-  showDelay?: number;
-  hideDelay?: number;
-  longPressDelay?: number;
-  mobileBreakpoint?: number;
-}
-
-/** A common interface for providing a hover pane element. */
-export interface HoverPaneProviderInterface {
-  /** Returns the provider's currently rendered hover pane element. */
-  getHoverPane(): HTMLElement | undefined;
-  /** Returns properties that should be passed to the hover pane. */
-  getHoverPaneProps(): HoverPaneProperties;
-  /** When user has keyboard navigated out of more info, we want the host to get focus */
-  acquireFocus(): void;
-  /** When user has keyboard navigated out of more info, we want the host to lose focus */
-  releaseFocus(): void;
-}
-
-export interface ToggleHoverPaneOptions {
-  coords: { x: number; y: number };
-  enableTouchBackdrop?: boolean;
-}
-
-/**
- * An interface for interacting with hover pane controllers (e.g.,
- * to retrieve their current hover pane template).
- */
-export interface HoverPaneControllerInterface extends ReactiveController {
-  /**
-   * Returns the hover pane template to render based on this controller's
-   * current state. The returned template may be `nothing` if the hover
-   * pane should not currently be rendered.
-   */
-  getTemplate(): HTMLTemplateResult | typeof nothing;
-
-  /**
-   * Requests to manually toggle the state of the hover pane.
-   * If the hover pane is already shown, it will begin fading out and then
-   * subsequently be hidden and removed. If the hover pane is already fading
-   * out or hidden, it will fade back in and be shown.
-   */
-  toggleHoverPane(options: ToggleHoverPaneOptions): void;
-}
-
-const clamp = (val: number, min = -Infinity, max = Infinity) =>
-  Math.max(min, Math.min(val, max));
-
-export class HoverPaneController implements HoverPaneControllerInterface {
-  /**
-   * The hover pane element attached to this controller's host.
-   */
-  private hoverPane?: HTMLElement;
-
-  /**
-   * The properties to be passed to the hover pane element
-   */
-  private hoverPaneProps?: HoverPaneProperties;
-
-  /**
-   * The breakpoint (in pixels) below which the mobile interface should be used.
-   */
-  private mobileBreakpoint?: number = 600;
-
-  /**
-   * The number of horizontal pixels the hover pane should be offset from the
-   * pointer position.
-   */
-  private offsetX: number = -10;
-
-  /**
-   * The number of vertical pixels the hover pane should be offset from the
-   * pointer position.
-   */
-  private offsetY: number = 15;
-
-  /**
-   * The delay between the mouse idling within the host element and when the hover
-   * pane should begin fading in (in milliseconds).
-   */
-  private showDelay: number = 300;
-
-  /**
-   * The delay between when the mouse leaves the host element and when the hover
-   * pane should begin fading out (in milliseconds).
-   */
-  private hideDelay: number = 100;
-
-  /**
-   * The delay between when a touch event begins on the host element and when the
-   * hover pane should begin fading in (in milliseconds).
-   */
-  private longPressDelay: number = 600;
-
-  /**
-   * Whether long press interactions should cause the hover pane to appear (when
-   * below the mobile breakpoint).
-   */
-  private enableLongPress: boolean = false;
-
-  /**
-   * Used to control the current state of this provider's hover pane.
-   *  - `'hidden'` => The hover pane is not present at all.
-   *  - `'shown'` => The hover pane is either fading in or fully visible.
-   *  - `'fading-out'` => The hover pane is fading out and about to be removed.
-   */
-  private hoverPaneState: HoverPaneState = 'hidden';
-
-  /** The timer ID for showing the hover pane */
-  private showTimer?: number;
-
-  /** The timer ID for hiding the hover pane */
-  private hideTimer?: number;
-
-  /** The timer ID for recognizing a long press event */
-  private longPressTimer?: number;
-
-  /**
-   * Whether the touch backdrop should currently be rendered irrespective of other touch
-   * interactions being enabled.
-   */
-  private forceTouchBackdrop: boolean = false;
-
-  /** A record of the last mouse position on the host element, for positioning the hover pane */
-  private lastPointerClientPos = { x: 0, y: 0 };
-
-  /**
-   * A flag to track whether the host element is being clicked by a pointer device, so that we
-   * don't trigger unnecessary keyboard focus behaviors on click. This is needed, e.g., to prevent
-   * the hover pane from appearing immediately at its `host` positioning on click, which can
-   * obstruct the host element itself (due to the ordering of events fired).
-   */
-  private clicking = false;
-
-  constructor(
-    /** The host element to which this controller should attach listeners */
-    private readonly host: ReactiveControllerHost &
-      HoverPaneProviderInterface &
-      HTMLElement,
-    /** Options for adjusting the hover pane behavior (offsets, delays, etc.) */
-    options: HoverPaneControllerOptions = {},
-  ) {
-    this.mobileBreakpoint = options.mobileBreakpoint ?? this.mobileBreakpoint;
-    this.offsetX = options.offsetX ?? this.offsetX;
-    this.offsetY = options.offsetY ?? this.offsetY;
-    this.showDelay = options.showDelay ?? this.showDelay;
-    this.hideDelay = options.hideDelay ?? this.hideDelay;
-    this.longPressDelay = options.longPressDelay ?? this.longPressDelay;
-    this.enableLongPress = options.enableLongPress ?? this.enableLongPress;
-
-    this.host.addController(this);
-  }
-
-  hostConnected(): void {
-    this.attachListeners();
-  }
-
-  hostDisconnected(): void {
-    this.detachListeners();
-  }
-
-  hostUpdated(): void {
-    this.hoverPane = this.host.getHoverPane();
-    this.hoverPaneProps = this.host.getHoverPaneProps();
-  }
-
-  /** @inheritdoc */
-  getTemplate(): HTMLTemplateResult | typeof nothing {
-    this.hoverPaneProps = this.host.getHoverPaneProps();
-
-    return this.shouldRenderHoverPane
-      ? html`
-          ${this.touchBackdropTemplate}
-          <tile-hover-pane
-            popover
-            tabindex="-1"
-            aria-describedby="tile-hover-pane-aria-description"
-            .model=${this.hoverPaneProps?.model}
-            .baseNavigationUrl=${this.hoverPaneProps?.baseNavigationUrl}
-            .baseImageUrl=${this.hoverPaneProps?.baseImageUrl}
-            .loggedIn=${this.hoverPaneProps?.loggedIn}
-            .suppressBlurring=${this.hoverPaneProps?.suppressBlurring}
-            .sortParam=${this.hoverPaneProps?.sortParam}
-            .collectionTitles=${this.hoverPaneProps?.collectionTitles}
-            .mobileBreakpoint=${this.mobileBreakpoint}
-            .currentWidth=${window.innerWidth}
-          ></tile-hover-pane>
-          <div id="tile-hover-pane-aria-description" class="sr-only">
-            ${msg('Press Up Arrow to exit item detail preview')}
-          </div>
-        `
-      : nothing;
-  }
-
-  /** @inheritdoc */
-  toggleHoverPane(options: ToggleHoverPaneOptions): void {
-    if (this.hoverPaneState !== 'hidden') {
-      this.fadeOutHoverPane();
-      this.forceTouchBackdrop = false;
-    } else {
-      this.lastPointerClientPos = options.coords;
-      this.forceTouchBackdrop = options.enableTouchBackdrop ?? false;
-      this.showHoverPane();
-    }
-  }
-
-  /**
-   * Produces a template for the invisible touch capture backdrop that
-   * is used to cancel the hover pane on touch devices. We want any
-   * touch interaction on the backdrop to remove the hover pane, and
-   * we don't want to bubble up mouse events that would otherwise
-   * affect the state of the hover pane (e.g., fading it back in).
-   */
-  private get touchBackdropTemplate(): HTMLTemplateResult | typeof nothing {
-    return this.showTouchBackdrop
-      ? html`<div
-          id="touch-backdrop"
-          @touchstart=${this.handleBackdropInteraction}
-          @touchmove=${this.handleBackdropInteraction}
-          @touchend=${this.handleBackdropInteraction}
-          @touchcancel=${this.handleBackdropInteraction}
-          @mouseenter=${(e: MouseEvent) => e.stopPropagation()}
-          @mousemove=${(e: MouseEvent) => e.stopPropagation()}
-          @mouseleave=${(e: MouseEvent) => e.stopPropagation()}
-        ></div>`
-      : nothing;
-  }
-
-  private get showTouchBackdrop(): boolean {
-    return (
-      (this.isTouchEnabled && this.enableLongPress) || this.forceTouchBackdrop
-    );
-  }
-
-  /** Whether to use the mobile layout */
-  private get isMobileView(): boolean {
-    return !!this.mobileBreakpoint && window.innerWidth < this.mobileBreakpoint;
-  }
-
-  private get isHoverEnabled(): boolean {
-    return window.matchMedia('(hover: hover)').matches;
-  }
-
-  private get isTouchEnabled(): boolean {
-    return (
-      'ontouchstart' in window &&
-      window.matchMedia('(any-pointer: coarse)').matches
-    );
-  }
-
-  /** Whether this controller should currently render its hover pane. */
-  private get shouldRenderHoverPane(): boolean {
-    return this.hoverPaneState !== 'hidden';
-  }
-
-  /**
-   * Returns the desired top/left offsets (in pixels) for this tile's hover pane.
-   * The desired offsets balance positioning the hover pane under the primary pointer
-   * while preventing it from flowing outside the viewport. The returned offsets are
-   * relative to the viewport, intended to position the pane as a popover element.
-   *
-   * These offsets are only valid if the hover pane is already rendered with its
-   * correct width and height. If the hover pane is not present, the returned offsets
-   * will simply represent the current pointer position.
-   */
-  private makePaneDesiredOffsets(anchor: HoverPanePositionAnchor): {
-    top: number;
-    left: number;
-  } {
-    // Try to find offsets for the hover pane that:
-    //  (a) cause it to lie entirely within the viewport, and
-    //  (b) to the extent possible, minimize the distance between the
-    //      nearest corner of the hover pane and the mouse/host element position
-    //      (with some additional offsets applied after the fact).
-
-    let [left, top] = [0, 0];
-    switch (anchor) {
-      case 'host':
-        const hostRect = this.host.getBoundingClientRect();
-        // slight inset from host top left corner
-        left = hostRect.left + 20;
-        top = hostRect.top + 30;
-        break;
-      case 'cursor':
-        left = this.lastPointerClientPos.x;
-        top = this.lastPointerClientPos.y;
-        break;
-    }
-
-    // Flip the hover pane according to which quadrant of the viewport the coordinates are in.
-    // (Similar to how Wikipedia's link hover panes work)
-    const flipHorizontal = left > window.innerWidth / 2;
-    const flipVertical = top > window.innerHeight / 2;
-
-    const hoverPaneRect = this.hoverPane?.getBoundingClientRect();
-    if (hoverPaneRect) {
-      // If we need to flip the hover pane, do so by subtracting its width/height from left/top
-      if (flipHorizontal) {
-        left -= hoverPaneRect.width;
-      }
-      if (flipVertical) {
-        top -= hoverPaneRect.height;
-      }
-
-      // Apply desired offsets from the target position
-      left += (flipHorizontal ? -1 : 1) * this.offsetX;
-      top += (flipVertical ? -1 : 1) * this.offsetY;
-
-      // On mobile view, shunt the hover pane to avoid overflowing the viewport
-      if (this.isMobileView) {
-        left = clamp(left, 20, window.innerWidth - hoverPaneRect.width - 20);
-        top = clamp(top, 20, window.innerHeight - hoverPaneRect.height - 20);
-      }
-    }
-
-    left += window.scrollX;
-    top += window.scrollY;
-
-    return { left, top };
-  }
-
-  /**
-   * Adds to the host element all the listeners necessary to make the
-   * hover pane functional.
-   */
-  private attachListeners(): void {
-    // keyboard navigation listeners
-    this.host.addEventListener('focus', this.handleFocus);
-    this.host.addEventListener('blur', this.handleBlur);
-    this.host.addEventListener('pointerdown', this.handlePointerDown);
-    this.host.addEventListener('keyup', this.handleKeyUp);
-    this.host.addEventListener('keydown', this.handleKeyDown);
-
-    if (this.isHoverEnabled) {
-      this.host.addEventListener('mouseenter', this.handleMouseEnter);
-      this.host.addEventListener('mousemove', this.handleMouseMove);
-      this.host.addEventListener('mouseleave', this.handleMouseLeave);
-    }
-
-    if (this.isTouchEnabled && this.enableLongPress) {
-      this.host.addEventListener('touchstart', this.handleTouchStart);
-      this.host.addEventListener('touchmove', this.handleLongPressCancel);
-      this.host.addEventListener('touchend', this.handleLongPressCancel);
-      this.host.addEventListener('touchcancel', this.handleLongPressCancel);
-      this.host.addEventListener('contextmenu', this.handleContextMenu);
-    }
-  }
-
-  /**
-   * Removes all the hover pane listeners from the host element.
-   */
-  private detachListeners(): void {
-    this.host.removeEventListener('mouseenter', this.handleMouseEnter);
-    this.host.removeEventListener('mousemove', this.handleMouseMove);
-    this.host.removeEventListener('mouseleave', this.handleMouseLeave);
-    this.host.removeEventListener('touchstart', this.handleTouchStart);
-    this.host.removeEventListener('touchmove', this.handleLongPressCancel);
-    this.host.removeEventListener('touchend', this.handleLongPressCancel);
-    this.host.removeEventListener('touchcancel', this.handleLongPressCancel);
-    this.host.removeEventListener('contextmenu', this.handleContextMenu);
-
-    // keyboard navigation listeners
-    this.host.removeEventListener('focus', this.handleFocus);
-    this.host.removeEventListener('blur', this.handleBlur);
-    this.host.removeEventListener('keyup', this.handleKeyUp);
-    this.host.removeEventListener('keydown', this.handleKeyDown);
-  }
-
-  private handleFocus = (): void => {
-    if (!this.clicking && this.hoverPaneState === 'hidden') {
-      this.showHoverPane({
-        anchor: 'host',
-      });
-    }
-    this.clicking = false;
-  };
-
-  private handleBlur = (): void => {
-    if (this.hoverPaneState !== 'hidden') {
-      this.fadeOutHoverPane();
-    }
-  };
-
-  private handlePointerDown = (): void => {
-    this.clicking = true;
-  };
-
-  private handleKeyDown = (e: KeyboardEvent): void => {
-    if (
-      (e.key === 'ArrowDown' || e.key === 'ArrowUp') &&
-      this.hoverPaneState !== 'hidden'
-    ) {
-      e.preventDefault();
-    }
-  };
-
-  private handleKeyUp = (e: KeyboardEvent): void => {
-    if (this.hoverPaneState === 'hidden' || !this.hoverPane) return;
-    if (e.key === 'ArrowDown') {
-      this.hoverPane.tabIndex = 1;
-      this.hoverPane.focus();
-    }
-
-    const isArrowUp = e.key === 'ArrowUp';
-    const isEscape = e.key === 'Escape' || e.key === 'Esc';
-
-    if (isEscape) {
-      this.fadeOutHoverPane();
-    }
-    if (isArrowUp || isEscape) {
-      this.hoverPane.tabIndex = -1;
-      this.host.acquireFocus();
-    }
-  };
-
-  /**
-   * Handler for the mouseenter event on the host element.
-   */
-  // NB: Arrow function so 'this' remains bound to the controller
-  private handleMouseEnter = (e: MouseEvent): void => {
-    // Delegate to the mousemove handler, as they are currently processed identically
-    this.handleMouseMove(e);
-  };
-
-  /**
-   * Handler for the mousemove event on the host element.
-   * Aborts any pending hide/fade-out for the hover pane, and restarts the
-   * timer to show it.
-   */
-  // NB: Arrow function so 'this' remains bound to the controller
-  private handleMouseMove = (e: MouseEvent): void => {
-    // The mouse is within the tile, so abort any pending removal of the hover pane
-    clearTimeout(this.hideTimer);
-
-    // If the hover pane is currently fading out, just make it fade back in where it is
-    if (this.hoverPaneState === 'fading-out') {
-      this.hoverPaneState = 'shown';
-      this.hoverPane?.classList.add('fade-in');
-    }
-
-    // Restart the timer to show the hover pane anytime the mouse moves within the tile
-    if (this.hoverPaneState === 'hidden') {
-      this.restartShowHoverPaneTimer();
-      this.lastPointerClientPos = { x: e.clientX, y: e.clientY };
-    }
-  };
-
-  /**
-   * Handler for the mouseleave event on the host element.
-   * Hides the hover pane if present, and aborts the timer for showing it.
-   */
-  // NB: Arrow function so 'this' remains bound to the controller
-  private handleMouseLeave = (): void => {
-    this.host.releaseFocus();
-
-    // Abort any timer to show the hover pane, as the mouse has left the tile
-    clearTimeout(this.showTimer);
-
-    // Hide the hover pane if it's already been shown
-    if (this.hoverPaneState !== 'hidden') {
-      this.hideTimer = window.setTimeout(() => {
-        this.fadeOutHoverPane();
-      }, this.hideDelay);
-    }
-  };
-
-  /**
-   * Handler for the touchstart event on the host element.
-   * Begins the timer for recognizing a long press event.
-   */
-  // NB: Arrow function so 'this' remains bound to the controller
-  private handleTouchStart = (e: TouchEvent): void => {
-    clearTimeout(this.longPressTimer);
-
-    if (e.touches.length === 1) {
-      this.longPressTimer = window.setTimeout(() => {
-        if (this.hoverPaneState === 'hidden') {
-          this.showHoverPane();
-        }
-      }, this.longPressDelay);
-
-      this.lastPointerClientPos = {
-        x: e.touches[0].clientX,
-        y: e.touches[0].clientY,
-      };
-    }
-  };
-
-  /**
-   * Handler for events that should cancel a pending long press event
-   * (touchmove, touchend, touchcancel). Aborts the timer for recognizing
-   * a long press.
-   */
-  // NB: Arrow function so 'this' remains bound to the controller
-  private handleLongPressCancel = (): void => {
-    clearTimeout(this.longPressTimer);
-  };
-
-  /**
-   * Handler for the contextmenu event, which should be suppressed during
-   * mobile long-press events on the host element.
-   */
-  // NB: Arrow function so 'this' remains bound to the controller
-  private handleContextMenu = (e: Event): void => {
-    e.preventDefault();
-  };
-
-  /**
-   * Immediately causes the hover pane to begin fading out, if it is present.
-   */
-  // NB: Arrow function so 'this' remains bound to the controller
-  private handleBackdropInteraction = (e: Event): void => {
-    if (this.hoverPaneState !== 'hidden') {
-      this.fadeOutHoverPane();
-    }
-    e.preventDefault();
-    e.stopPropagation();
-  };
-
-  /**
-   * Aborts and restarts the timer for showing the hover pane.
-   */
-  private restartShowHoverPaneTimer(): void {
-    clearTimeout(this.showTimer);
-    this.showTimer = window.setTimeout(() => {
-      this.host.acquireFocus();
-      this.showHoverPane();
-    }, this.showDelay);
-  }
-
-  /**
-   * Causes this tile's hover pane to be rendered, positioned, and made visible.
-   */
-  private async showHoverPane(
-    options: {
-      anchor: HoverPanePositionAnchor;
-    } = {
-      anchor: 'cursor',
-    },
-  ): Promise<void> {
-    this.hoverPaneState = 'shown';
-    this.host.requestUpdate();
-
-    // Wait for the state update to render the hover pane
-    await this.host.updateComplete;
-
-    // Ensure the hover pane element is still in the document before showing,
-    // as it might have been removed by the previous update.
-    if (!this.hoverPane?.isConnected) return;
-
-    if (this.hoverPane && !this.hoverPane.matches(':popover-open')) {
-      this.hoverPane.showPopover?.();
-    }
-    // Pane sizes aren't accurate until the pane's full descendant tree has
-    // rendered. The next animation frame guarantees that to be true, but
-    // frames are skipped when the page is not visible, so fall back to a
-    // short timer as a backstop in such cases.
-    await Promise.race([
-      new Promise(resolve => {
-        requestAnimationFrame(resolve);
-      }),
-      new Promise(resolve => {
-        setTimeout(resolve, 50);
-      }),
-    ]);
-
-    // Apply the correct positioning to the hover pane
-    this.repositionHoverPane(options.anchor);
-
-    // The hover pane is initially not visible (to avoid it shifting around
-    // while being positioned). Since it now has the correct positioning, we
-    // can make it visible and begin its fade-in animation.
-    this.hoverPane?.classList.add('visible', 'fade-in');
-  }
-
-  /**
-   * Causes this tile's hover pane to begin fading out and starts
-   * the timer for it to be removed.
-   */
-  private fadeOutHoverPane(): void {
-    this.hoverPaneState = 'fading-out';
-    this.hoverPane?.classList.remove('fade-in');
-
-    clearTimeout(this.hideTimer);
-    this.hideTimer = window.setTimeout(() => {
-      this.hoverPaneState = 'hidden';
-      if (this.hoverPane) {
-        this.hoverPane.tabIndex = -1;
-      }
-      this.host.requestUpdate();
-    }, 100);
-  }
-
-  /**
-   * Positions the hover pane with the correct offsets.
-   */
-  private repositionHoverPane(anchor: HoverPanePositionAnchor): void {
-    if (!this.hoverPane) return;
-
-    const { top, left } = this.makePaneDesiredOffsets(anchor);
-
-    this.hoverPane.style.top = `${top}px`;
-    this.hoverPane.style.left = `${left}px`;
-  }
-}