display-ui
Auto-generated from exported functions tagged #api in the source. See
imports and re-exports for how
to import these from a plugin.
BottomRightCornerContext
The one box per display that owns the bottom-right corner.
It lives beside the overlay contract rather than with the chrome that mounts it,
because it is the half of that contract the types cannot carry:
DisplayChromeOverlays.BackgroundProgress is the one state told to render an
in-flow chip with no position and no corner offsets, and this is the box it is
laid out in. A host writing their own display over DisplayChromeBase needs to
be able to build that corner; while this sat one layer up in the LGV plugin, the
rule was a paragraph they could only obey by hand.
Two independent things want that corner and neither could see the other: the
display's own control row (BottomRightIndicators — track sizing, the isoform
notice, the solo chip) and the chrome's background-progress chip
(DisplayChromeOverlays.BackgroundProgress, the status channel for work with no
fetch behind it). Both portal into the same per-track overlay node, and both
used to claim bottom: 2; right: 2 there with their own position: absolute
box — so they simply drew on top of each other, the controls winning on z-index
and the status text disappearing under them.
It has never been reachable: the two displays that render the control row
(alignments, canvas) are not among the four that report a ready-phase status
(clustering, on multi-wiggle / multi-row features / maf / the multi-sample
variant pair). That is the reason to make it structural rather than to leave
it — nothing on either side is aware of the constraint, so the first display to
want both would find the bug, and it presents as a status message that silently
never appears.
BottomRightIndicators already described itself as "the single anchor point for
every bottom-right overlay ... so they lay out as one row instead of each
picking their own position and colliding". This makes that true of the chip too:
the chrome renders the anchor, puts its chip in it, and publishes the node here
so the display's row — rendered several components away, inside the chrome's
body — lands in the same flex box instead of over it.
null outside a chrome (a display an embedder mounts standalone, a unit test,
the SVG export), where BottomRightIndicators keeps its own anchored box. That
fallback is why this can be added without every consumer changing.
// type signature
Context<HTMLElement | null>DisplayUIProvider
Both bring-your-own seams at once: what a display draws that is not data.
There are two contexts underneath because two different things render them — the
chrome around a display draws the status states, the display itself draws its
bottom-right controls — and that split is real at the implementation level,
since DisplayChromeBase takes its overlay set as a prop and never renders a
track control. It is not real for an embedder: nobody wants stock Material
loading scrims with plain corner controls, or the reverse. Every consumer in
this repo mounts the two together.
<DisplayUIProvider>{tracks}</DisplayUIProvider>Both props default to the plain, toolkit-free sets, so the common case — "I do not want Material UI in my app" — needs no arguments and no second import.
overlays is a partial set, merged over the plain one, so replacing a
single state is one entry rather than five:
<DisplayUIProvider overlays={{ ErrorBar: MyErrorBar }}>Partial rather than whole for two reasons. A host writing four of the five
states by hand only ever wanted one of them, and every example of this had
spread plainChromeOverlays in to say so. And a sixth state is a thing
JBrowse can add: with a whole set the host's object goes stale on upgrade — a
compile error if they typecheck, a missing component if they ship JS — while a
partial one keeps working and picks up the new plain default.
Declare that object at module scope if you can. The merge is stable per object
(resolveOverlays), so a constant costs one merge for the life of the app; a
literal written inline in JSX is a new object every render, and this value goes
into a context, so every display beneath re-renders with it.
The contexts themselves still default to undefined, and that stays true. A
display rendering outside any provider — a unit test, the SVG export,
breakpoint-split-view's overlayUtils — keeps JBrowse's own Material look,
because a plain ambient default would degrade those invisibly. Defaulting this
component's props is a different thing: mounting it is a deliberate act, and
the act means "not the Material default". Nothing gets a plain set without
someone having asked.
Colors are not a seam and are not here. A display reads usePalette() for its
own content colors, which is a palette of strings rather than a UI toolkit, so
it arrives through SessionPaletteProvider (@jbrowse/core/ui/PaletteContext)
whatever these are set to. A feature track needs it even with plain chrome.
This module reaches no @mui/* module, and muiFree.test.ts keeps it that way
— asking for less Material UI must not download more of it. What it cannot do is
unship the Material components a stock display imports: DisplayChrome and
TrackControl are in that display's chunk either way, and merely stop
rendering. Keeping them out of the graph means writing your own display
component over DisplayChromeBase, which takes overlays as a prop and imports
no toolkit. See
DISPLAYCHROME.md.
// type signature
({ overlays, trackControl, children, }: { overlays?: Partial<…> | undefined; trackControl?: TrackControlComponent | undefined; children: ReactNode; }) => ElementisLiveModel
Whether an overlay's model can still be called into.
The terminal states unmount the canvas, so a click landing after the track was
closed would otherwise run an action on a destroyed node — which is why both
overlay sets guard their one button with isAlive.
isAlive alone is wrong here, and it throws rather than answering. The four
model shapes in chromeOverlays.ts are structural on purpose ("A display
satisfies one by having the fields; no mixin has to be composed"), so a host
writing their own display over DisplayChromeBase may hand these components a
plain object. isAlive runs assertIsStateTreeNode and throws on one, inside
an event handler, where React logs it and moves on — leaving the Force load
button looking live and doing nothing, which is the exact state
DisplayChromeOverlays.TooLarge documents itself as existing to prevent.
A plain object is never destroyed, so it is always callable. The liveness question only exists for an MST node.
// type signature
(model: unknown) => booleanplainChromeOverlays
The five displayPhase states drawn with no UI toolkit: no theme provider to
mount, no emotion in the host page, and nothing that reads as a stray Material
widget inside someone else's design system.
DisplayUIProvider installs this by default, so mount that rather than naming
this — reach for it directly only to wrap a state or to build a context value by
hand. Colours come from currentColor and the CSS system colours, so the host's
own cascade drives them in both light and dark.
The data-testid values it renders are a contract four of JBrowse's test
systems key on, so a replacement set that keeps them can be driven by those
suites too.
// type signature
DisplayChromeOverlaysPlainTrackControl
A display's ambient bottom-right control — track sizing, the isoform notice, the
show-only badge — drawn with no UI toolkit, the corner-control counterpart of
plainChromeOverlays.
DisplayUIProvider installs this by default. The behaviour is not in here:
dismissal, the keyboard, focus, the top layer and the anchoring are
useTrackControlMenu, so writing your own control means writing markup rather
than re-deriving why the menu opens upward.
The package exports it as plainTrackControl, lower-cased to match
plainChromeOverlays — the two are a pair, and both are things you hand to a
provider rather than render yourself.
// type signature
({ icon, tooltip, label, options, onClick, onMenuClose, onDelete, warning, }: TrackControlProps) => ElementtooLargeBannerText
Which axis tripped (empty when the display gates without a reason), then the way out.
zoomCanRelease decides whether "zoom in" is offered, and it has to be asked
because the advice is not always true. It was, once: the AUTO_FORCE_LOAD_BP
floor turned the byte gate off below 20kb, so zooming far enough always worked.
The byte gate no longer stops at any floor, and an index quotes whole blocks —
so for a file whose blocks are large the same bytes come down however far the
user goes, and telling them to keep zooming into a fetch whose cost cannot fall
is the one thing the banner must not do. zoomCanReleaseGate answers it from
two consecutive measurements rather than from a threshold; see
ByteEstimate.zoomIneffective.
// type signature
(regionTooLargeReason: string, { zoomCanRelease }?: { zoomCanRelease?: boolean | undefined; }) => stringTooltip
A hover/focus label for a control, drawn rather than delegated to the browser's
title attribute — positioned so it clears the display's contain: strict box
and the window edge, dismissed by Escape, and drawn like every other JBrowse
tooltip instead of like whatever the host OS renders.
title is what this chrome used to use, and it was the wrong tool three ways:
it can be neither styled nor positioned, it waits about a second and then
disappears on a timer of its own, and on a control that already carries an
aria-label some screen readers announce both strings. This reaches no UI
toolkit, so the package's no-Material-UI guarantee holds.
Takes a single element child and clones it rather than wrapping it: the controls
that want a tooltip are absolutely positioned inside a legend or sit in a flex
row, where an extra <span> moves them. The child keeps its own handlers —
these compose on top of them. This is the same trigger pattern MUI's own
Tooltip uses, which is what the rest of JBrowse's chrome is built on; the
toolkit is what differs here, not the shape.
<Tooltip title="Hide legend">
<button type="button" aria-label="Hide legend" onClick={onDismiss}>
×
</button>
</Tooltip>The child still needs its own accessible name, because this sets
aria-describedby and never aria-label — see useTooltip, which is this
without the cloning, for a host writing its own markup.
// type signature
({ title, placement, children, }: { title: ReactNode; placement?: TooltipPlacement | undefined; children: ReactElement<…>; }) => ElementTrackOverlayPortal
Lift floating track chrome out of the display's contain: strict sandbox and
into the host's overlay node, so the LGV's inter-region masks cannot bury it at
multi-region scale. TrackOverlaySlot is the other end.
The overlay node takes no pointer events, so anything of yours the user hovers
or clicks sets pointer-events: auto on its own positioned box.
With no slot above it this renders the children in place (fallbackInline, the
default), which preserves chrome that is still meaningful unescaped. Pass
fallbackInline={false} for chrome that only makes sense above the masks and
draws itself some other way elsewhere.
// type signature
({ children, fallbackInline, }: { children: ReactNode; fallbackInline?: boolean | undefined; }) => ReactNodeTrackOverlaySlot
The box a display is mounted in, plus the overlay node its floating chrome
escapes into. Pair to TrackOverlayPortal, which is the other end.
A display's React tree is sealed in a contain: strict sandbox — that is what
isolates its paint, and dropping it is measured and rejected (ADR-058). A
stacking context comes with the isolation, so floating chrome a display draws (a
colour key, hi-c's overlay panel, maf's row labels) cannot out-z-index anything
painted over the track stack from outside. The escape is a node mounted beside
the sandbox rather than inside it, published through TrackOverlayContext; this
component is that node, its context and the paint order between them, in the one
place they have to agree.
TrackContainer uses it, so JBrowse's own layout and an embedder's go through
the same code rather than two copies of one rule. An embedder mounting
RenderingComponent directly needs it too, and that is the case it was added
for: with no provider the context is null, the portal falls back to rendering
inline, and a host that paints region seams over its column buries the chrome
under them with nothing to say so.
<TrackOverlaySlot zIndex={3} style={{ height: display.height }}>
<div style={{ position: 'absolute', inset: 0, contain: 'strict' }}>
<RenderingComponent model={display} />
</div>
</TrackOverlaySlot>zIndex is required, and deliberately has no default. It is the answer to
"above what?", and that is a fact about the caller's layout rather than about
this component: JBrowse's own track container passes 100, which is positioned
above PaddingBlocks and below TrackLabel at 200, and means nothing to a host
whose masks sit at 2. A default would be a number that is right in one layout
and silently wrong in every other, and the failure — chrome painted under a mask
— is invisible until someone looks at the right zoom.
The node takes no pointer events, so it does not eat the canvas's. Chrome that
wants them takes them back on its own positioned box; it also carries
data-gesture-owner, so anything that does is already exempt from the LGV's
click-drag pan.
// type signature
({ children, zIndex, style, overlayStyle, }: { children: ReactNode; zIndex: number; style?: CSSProperties | undefined; overlayStyle?: CSSProperties | undefined; }) => ElementuseTooltip
A hover/focus label for one control, as props to spread — the headless half of
Tooltip, for a host writing its own chrome rather than restyling ours. Same
relationship useTrackControlMenu has to plainTrackControl.
const { triggerProps, tooltip } = useTooltip('Hide legend')
return (
<>
<button {...triggerProps} aria-label="Hide legend" onClick={onDismiss}>
×
</button>
{tooltip}
</>
)triggerProps carries no onClick, so a control's own handler does not collide
with it. Any other handler on this list has to compose rather than replace —
spread first, then call triggerProps.onFocus from yours.
// type signature
(title: ReactNode, { placement }?: { placement?: TooltipPlacement | undefined; }) => TooltipTriggeruseTrackControlMenu
The behaviour behind a bottom-right track control's menu, as prop getters to
spread — dismissal (Escape, an outside press, an ancestor scrolling), the
keyboard (arrows, Home/End), focus, and the anchoring that clears both the
display's contain: strict box and the window edge.
For writing your own control rather than restyling plainTrackControl: each of
those rules is a bug when missed and none of them shows up in a screenshot.
Render menuProps only while open, and portal it to document.body —
createPortal is the caller's to aim, the maths is here. menuProps.style
carries position only.
// type signature
(onClose?: (() => void) | undefined) => TrackControlMenuRelated links
- Guide: Dependencies and re-exports