Code Documentation for Mantis

Mantis is built on top of Bluefish, and the code for Mantis is integrated into the Bluefish repository. Everything in this folder (bluefish-solid/src/mantis) is a component built for Mantis. The only other code for Mantis is in bluefish-solid/src/bluefish.tsx. That file is where the output SVG gets rendered and most of the logic happens, so the bulk of Mantis' code can be found there.

Using Mantis Components

The process of creating a diagram in Mantis is almost identical to creating a diagram in Bluefish. The only difference is, instead of wrapping the diagram in a <Bluefish></Bluefish> component, you'd wrap it on one of the Mantis component (e.g. <Basic></Basic>, <MultiLens></MultiLens>, etc.).

Mantis components come with additional props. These are the ones that are shared between all of them:

• traversalPattern -- Determines the traversal pattern for the component. You can learn more about how to use Mantis' traversal patterns in the Traversal Patterns section below. The default is Cursor.
• showVoronoi -- This prop is used primarily for debugging. This renders the Voronoi diagram generated by the midpoint of each Bluefish node.
• showHighlighting -- Enables the Dynamic Highlighting feature. Essentially, this attempts to highlight both the current node and those related to it.
• parameterOverrides -- Overrides Mantis' global constants. Can be used to adjust scroll or cursor sensitivity, for instance. More information in the MantisOverrides type spec.

Traversal Patterns

• Bubble: At all times, centers the user's view around the Bluefish node closest to the cursor.
• EdgePan: Mirrors the traditional behavior of screen magnifiers. In other words, it allows the user to move their mouse around, but only moves the screen when the cursor is near its edge.
• Cursor: A more free form traversal pattern. The center of the screen just follows the mouse.

Basic

No additional props.

Mini-Map

No additional props.

Additional controls:

• The red rectangle in the mini-map is draggable.

Multi-Lens

No additional props.

Additional controls:

• c: makes the lens shape circular
• r: makes the lens shape rectangular
• Shift + Click: adds (or deletes) a lens

Split-Screen

Additional props:

• flexDirection: row stacks the two screens horizontally--left and right. column stacks the two screens vertically--top and bottom. default: row

Preview

Additional props:

• diagram (required): the MantisDiagram being traversed.

Additional controls:

• Clicking on a preview arrow automatically navigates the user to the icon the arrow is pointing at.

Auto-Map

Additional props:

• diagram (required): the MantisDiagram being traversed.
• flexDirection: row stacks the two screens horizontally--left and right. column stacks the two screens vertically--top and bottom. default: row

Additional controls:

• a/d: cycles through the auto-map nodes
• w: zooms the automatic view out to see all of the related nodes
• s: zooms the automatic view in to see the selected node
• e: navigates the traveresal/controlled view to the node selected in the automatic view

Docked-Lens

Additional props:

• diagram: the MantisDiagram being traversed.

Controls

Controls shared by all Mantis components:

• Left clicking the screen at any time toggles between a magnified view and an unmagnified view.
• Right clicking the screen at any time automatically zooms into the node that the user clicks on.
• Scrolling (with either the mouse or the trackpad) toggles the zoom/magnification level.
• Shift + Up: zooms in/increases magnification
• Shift + Down: zooms out/decreases magnification
• f: Freeze/Unfreeze the cursor.

Mobile Compatibility

Mantis is not yet compatible with mobile--this functionality is currently in progress. At present, Mantis is responsive to touch events for basic panning and zooming.

Installation Guide

To start, make sure you have pnpm installed. Installation instructions can be found at https://pnpm.io/installation.

After you have installed pnpm, open a new terminal window and navigate to project directory. Run the following command to install all necessary packages and dependencies:

pnpm install

Available Scripts

You can run the following commands inside the project directory:

pnpm start

Runs the app in the development mode. Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.

pnpm storybook

Runs storybook

Making an App.tsx File

When you run pnpm start, it builds and renders the contents of App.tsx. You should create an App.tsx file in /public. This can be done by duplicating the App.template.tsx file in the /public folder and renaming it to App.tsx.