Support right mouse button and preventing default context menu

Author: axelboc

apps/storybook/.storybook/preview.ts

@@ -12,7 +12,7 @@ const preview: Preview = {
         order: [
           'Getting started',
           'Utilities',
-          'Context',
+          'Contexts',
           'Customization',
           'Visualizations',
           ['LineVis'],

apps/storybook/src/Context.mdx apps/storybook/src/Contexts.mdxapps/storybook/src/Context.mdx renamed to apps/storybook/src/Contexts.mdx

@@ -1,4 +1,4 @@
-## Context
+## VisCanvasContext
 
 Children of `VisCanvas` have access to `VisCanvasContext`, which provides helpful utilities, notably to convert points between coordinate spaces (data, world, HTML).
 It also exposes the size and ratio of the canvas and of the visualization, as well as the axis configs passed to `VisCanvas`.
@@ -40,3 +40,19 @@ const { visSize, dataToWorld, worldToData } = useVisCanvasContext();
 | `r3fRoot`    | React Three Fiber container rendered inside `canvasArea` that wraps the `canvas` element    |
 
 > These tables are not exhaustive. Please consider any undocumented property as experimental or meant for internal use only.
+
+## InteractionsContext
+
+Children of `VisCanvas` also have access to `InteractionsContext`, which provides low-level utilities for coordinating mouse interactivity on the canvas.
+However, thanks to the `useInteraction` hook, which allows registering new interactions, there's little need to access `InteractionsContext` directly.
+
+The only utility you may need is `getInteractions`, which allows accessing all registered interactions that are currently enabled. If you pass mouse button(s)
+and/or modifier key(s) to it, it can filter the interactions and return only those that are compatible. Note that `getInteractions` only works
+when called inside an event handler, not during render.
+
+```ts
+getInteractions: (
+  button?: InteractionConfig['button'],
+  modifierKey?: InteractionConfig['modifierKey'],
+) => Interaction[];
+```

apps/storybook/src/Pan.stories.tsx

@@ -1,4 +1,11 @@
-import { MouseButton, Pan, ResetZoomButton, VisCanvas, Zoom } from '@h5web/lib';
+import {
+  MouseButton,
+  Pan,
+  PreventDefaultContextMenu,
+  ResetZoomButton,
+  VisCanvas,
+  Zoom,
+} from '@h5web/lib';
 import { type Meta, type StoryObj } from '@storybook/react';
 
 import FillHeight from './decorators/FillHeight';
@@ -19,9 +26,13 @@ const meta = {
     button: {
       control: {
         type: 'inline-check',
-        labels: { [MouseButton.Left]: 'Left', [MouseButton.Middle]: 'Middle' },
+        labels: {
+          [MouseButton.Left]: 'Left',
+          [MouseButton.Middle]: 'Middle',
+          [MouseButton.Right]: 'Right',
+        },
       },
-      options: [MouseButton.Left, MouseButton.Middle],
+      options: [MouseButton.Left, MouseButton.Middle, MouseButton.Right],
     },
     modifierKey: {
       control: { type: 'inline-check' },
@@ -43,6 +54,7 @@ export const Default = {
         <Pan {...args} />
         <Zoom />
         <ResetZoomButton />
+        <PreventDefaultContextMenu />
       </VisCanvas>
     );
   },
@@ -69,6 +81,13 @@ export const MiddleButton = {
   },
 } satisfies Story;
 
+export const RightButton = {
+  ...Default,
+  args: {
+    button: [MouseButton.Right],
+  },
+} satisfies Story;
+
 export const TwoButtons = {
   ...Default,
   args: {

apps/storybook/src/PreventDefaultContextMenu.stories.tsx

@@ -0,0 +1,70 @@
+import {
+  FloatingControl,
+  MouseButton,
+  Pan,
+  PreventDefaultContextMenu,
+  VisCanvas,
+  Zoom,
+} from '@h5web/lib';
+import { useToggle } from '@react-hookz/web';
+import { type Meta, type StoryObj } from '@storybook/react';
+
+import FillHeight from './decorators/FillHeight';
+
+const meta = {
+  title: 'Building Blocks/Interactions/PreventDefaultContextMenu',
+  component: PreventDefaultContextMenu,
+  decorators: [FillHeight],
+  parameters: { layout: 'fullscreen' },
+  args: {
+    when: undefined,
+  },
+  argTypes: {
+    when: {
+      control: { type: 'inline-check' },
+      options: ['when-needed', 'always', 'never'],
+    },
+  },
+} satisfies Meta<typeof PreventDefaultContextMenu>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const WhenNeeded = {
+  render: (args) => {
+    const [withRightBtn, toggleRightBtn] = useToggle(false);
+
+    return (
+      <VisCanvas
+        title={`Panning with ${withRightBtn ? 'right' : 'left'} mouse button`}
+        abscissaConfig={{ visDomain: [-10, 0], showGrid: true }}
+        ordinateConfig={{ visDomain: [50, 100], showGrid: true }}
+      >
+        <PreventDefaultContextMenu {...args} />
+
+        <Pan button={withRightBtn ? MouseButton.Right : MouseButton.Left} />
+        <Zoom />
+
+        <FloatingControl>
+          <button type="button" onClick={() => toggleRightBtn()}>
+            Pan with {withRightBtn ? 'left' : 'right'} button
+          </button>
+        </FloatingControl>
+      </VisCanvas>
+    );
+  },
+} satisfies Story;
+
+export const Always = {
+  ...WhenNeeded,
+  args: {
+    when: 'always',
+  },
+} satisfies Story;
+
+export const Never = {
+  ...WhenNeeded,
+  args: {
+    when: 'never',
+  },
+} satisfies Story;

packages/lib/src/index.ts

@@ -72,6 +72,7 @@ export { default as SelectToZoom } from './interactions/SelectToZoom';
 export { default as AxialSelectToZoom } from './interactions/AxialSelectToZoom';
 export { default as SelectionTool } from './interactions/SelectionTool';
 export { default as AxialSelectionTool } from './interactions/AxialSelectionTool';
+export { default as PreventDefaultContextMenu } from './interactions/PreventDefaultContextMenu';
 export type { PanProps } from './interactions/Pan';
 export type { ZoomProps } from './interactions/Zoom';
 export type { XAxisZoomProps } from './interactions/XAxisZoom';
@@ -81,6 +82,7 @@ export type { SelectToZoomProps } from './interactions/SelectToZoom';
 export type { AxialSelectionToolProps } from './interactions/AxialSelectionTool';
 export type { AxialSelectToZoomProps } from './interactions/AxialSelectToZoom';
 export type { DefaultInteractionsConfig } from './interactions/DefaultInteractions';
+export type { PreventDefaultContextMenuProps } from './interactions/PreventDefaultContextMenu';
 
 // SVG
 export { default as SvgElement } from './interactions/svg/SvgElement';
@@ -92,9 +94,11 @@ export type { SvgLineProps } from './interactions/svg/SvgLine';
 export type { SvgRectProps } from './interactions/svg/SvgRect';
 export type { SvgCircleProps } from './interactions/svg/SvgCircle';
 
-// Context
+// Contexts
 export { useVisCanvasContext } from './vis/shared/VisCanvasProvider';
+export { useInteractionsContext } from './interactions/InteractionsProvider';
 export type { VisCanvasContextValue } from './vis/shared/VisCanvasProvider';
+export type { InteractionsContextValue } from './interactions/InteractionsProvider';
 
 // Utilities
 export { toTypedNdArray } from '@h5web/shared/vis-utils';

packages/lib/src/interactions/DefaultInteractions.tsx

@@ -8,6 +8,7 @@ import Zoom, { type ZoomProps } from '../interactions/Zoom';
 import AxialSelectToZoom, {
   type AxialSelectToZoomProps,
 } from './AxialSelectToZoom';
+import PreventDefaultContextMenu from './PreventDefaultContextMenu';
 
 export interface DefaultInteractionsConfig {
   pan?: PanProps | false;
@@ -51,6 +52,8 @@ function DefaultInteractions(props: DefaultInteractionsConfig) {
           {...interactions.ySelectToZoom}
         />
       )}
+
+      <PreventDefaultContextMenu />
     </>
   );
 }

packages/lib/src/interactions/InteractionsProvider.tsx

@@ -1,3 +1,4 @@
+import { castArray } from '@h5web/shared/vis-utils';
 import {
   createContext,
   type ReactNode,
@@ -12,6 +13,10 @@ import { type InteractionConfig } from './models';
 export interface InteractionsContextValue {
   registerInteraction: (id: string, config: InteractionConfig) => void;
   unregisterInteraction: (id: string) => void;
+  getInteractions: (
+    button?: InteractionConfig['button'],
+    modifierKey?: InteractionConfig['modifierKey'],
+  ) => Interaction[];
   shouldInteract: (id: string, event: MouseEvent) => boolean;
 }
 
@@ -27,7 +32,7 @@ function InteractionsProvider(props: { children: ReactNode }) {
   const [interactionMap] = useState(new Map<string, Interaction>());
 
   const registerInteraction = useCallback(
-    (id: string, config: InteractionConfig) => {
+    (id: string, config: InteractionConfig): void => {
       if (interactionMap.has(id)) {
         console.warn(`An interaction with ID "${id}" is already registered.`); // eslint-disable-line no-console
       } else {
@@ -38,14 +43,41 @@ function InteractionsProvider(props: { children: ReactNode }) {
   );
 
   const unregisterInteraction = useCallback(
-    (id: string) => {
+    (id: string): void => {
       interactionMap.delete(id);
     },
     [interactionMap],
   );
 
+  const getInteractions = useCallback(
+    (
+      button?: InteractionConfig['button'],
+      modifierKey?: InteractionConfig['modifierKey'],
+    ): Interaction[] => {
+      const interactions = [...interactionMap.values()].filter(
+        (inter) => inter.isEnabled,
+      );
+
+      if (button === undefined) {
+        return interactions;
+      }
+
+      const buttons = button === 'Wheel' ? button : castArray(button);
+      const modifierKeys = modifierKey ? castArray(modifierKey) : [];
+
+      return interactions.filter(
+        (inter) =>
+          (buttons === 'Wheel'
+            ? inter.isWheel
+            : buttons.some((b) => inter.buttons.includes(b))) &&
+          modifierKeys.every((k) => inter.modifierKeys.includes(k)),
+      );
+    },
+    [interactionMap],
+  );
+
   const shouldInteract = useCallback(
-    (interactionId: string, event: MouseEvent | WheelEvent) => {
+    (interactionId: string, event: MouseEvent | WheelEvent): boolean => {
       const registeredInteractions = [...interactionMap.values()];
       if (!interactionMap.has(interactionId)) {
         throw new Error(`Interaction ${interactionId} is not registered`);
@@ -78,6 +110,7 @@ function InteractionsProvider(props: { children: ReactNode }) {
       value={{
         registerInteraction,
         unregisterInteraction,
+        getInteractions,
         shouldInteract,
       }}
     >

packages/lib/src/interactions/PreventDefaultContextMenu.tsx

@@ -0,0 +1,30 @@
+import { useEventListener } from '@react-hookz/web';
+import { useThree } from '@react-three/fiber';
+
+import { useInteractionsContext } from './InteractionsProvider';
+import { MouseButton } from './models';
+
+interface Props {
+  when?: 'as-needed' | 'always' | 'never';
+}
+
+function PreventDefaultContextMenu(props: Props) {
+  const { when = 'as-needed' } = props;
+  const { getInteractions } = useInteractionsContext();
+
+  const { domElement } = useThree((state) => state.gl);
+
+  useEventListener(domElement, 'contextmenu', (evt: PointerEvent) => {
+    if (
+      when === 'always' ||
+      (when === 'as-needed' && getInteractions(MouseButton.Right).length > 0)
+    ) {
+      evt.preventDefault();
+    }
+  });
+
+  return null;
+}
+
+export { type Props as PreventDefaultContextMenuProps };
+export default PreventDefaultContextMenu;

packages/lib/src/interactions/models.ts

@@ -5,6 +5,7 @@ export type ModifierKey = 'Alt' | 'Control' | 'Shift';
 export enum MouseButton {
   'Left' = 0,
   'Middle' = 1,
+  'Right' = 2,
 }
 
 export type Rect = [start: Vector3, end: Vector3];