react

zeejs React - simple API to create multi layered UI

what's in the box

• layers - automatic ordering of nested layers
• backdrop - hide / block background or keep a layer as part of the flow
• focus
  • Tab between layers
  • trap focus above backdrop
  • re-focus when blocking layer close
  • focusChange notification when focus outside / inside logical layer
• click outside - notification for click outside of logical layer
• mouse interaction - notification for mouse enter / leave of logical layer
• escape catching - notification for escape press
• server rendering - single pass nested rendering of layers in the server
• component primitives - Tooltip, Popover, Modal
• typed - built with TypeScript
• tested - tested in a browser

how to use

This document describes the zeejs React usage, For a more in depth overview of zeejs, please see the general documentation.

<Root> component

At the base of the application or website place the <Root> component. The Root component is responsible for collecting, rendering and managing the layers.

Notice that Root is required for zeejs to work properly.

props:

name	type	default	required	description
className	string	""	false	CSS class name to be placed on the wrapper element around all layers
style	React.CSSProperties	{}	false	CSS styles to be placed on the wrapper element around all layers

code example:

import { Root } from '@zeejs/react';

ReactDOM.render(
    <Root className="app-root" style={{ height: `100%` }}>
        {/* application code */}
    </Root>
);

will output:

<div class="app-root" style="height: 100%">
    <zeejs-layer>
        <!-- application code -->
    </zeejs-layer>
</div>

<Layer> component

At every point that requires a part of the DOM to be moved up the normal layout flow and out of any overflows, a <Layer> component can be placed. The Layer is the low level primitive of zeejs that takes any given content and renders it in its own layer.

The component will generate a new zeejs layer above layer it is rendered in.

props:

name	type	default	required	description
backdrop	"none" | "block" | "hide"	"none"	false	background behavior; see docs
overlap	"window" | HTMLElement	"window"	false	layer bounds reference
onClickOutside	(target: EventTarget) => void		false	invoked on click outside; see docs
onMouseIntersection	(isInside: boolean) => void		false	invoked when mouse leaves or enters layer; see docs
onFocusChange	(isFocused: boolean) => void		false	invoked when focus is moved into/out of layer; see docs
onEscape	(event: KeyboardEvent) => void		false	invoked when escape is pressed; see docs

code example:

import { Layer } from '@zeejs/react';

const Component = () => {
    return (
        <div>
            <Layer>{/* layer content */}</Layer>
        </div>
    );
};

will output (assuming render in the application layer):

<div>
    <zeejs-layer>
        <!-- application code containing layer component -->
    </zeejs-layer>
    <zeejs-layer style="/* bound to window or reference element */">
        <!-- layer content -->
    </zeejs-layer>
</div>

nesting code example:

import { Layer } from '@zeejs/react';

const Component = () => {
    return (
        <div>
            <Layer>
                <div>
                    {/* layer A content*/}
                    <Layer>{/* layer B content */}</Layer>
                </div>
            </Layer>
        </div>
    );
};

will output (assuming render in the application layer):

<div>
    <zeejs-layer>
        <!-- application code containing layer component -->
    </zeejs-layer>
    <zeejs-layer>
        <!-- layer A content -->
    </zeejs-layer>
    <zeejs-layer>
        <!-- layer B content -->
    </zeejs-layer>
</div>

<Modal> component

The modal primitive display content that is not affected by the scroll of lower layers.

props:

name	type	default	required	description
backdrop	"none" | "block" | "hide"	"block"	false	background behavior; see docs
position	"topLeft" | "top" | "topRight" | "left" | "center" | "right" | "bottomLeft" | "bottom" | "bottomRight"	"center"	false	fixed align position
show	boolean	true	false	flag if the layer should be displayed
onClickOutside	(target: EventTarget) => void		false	invoked on click outside; see docs
onMouseIntersection	(isInside: boolean) => void		false	invoked when mouse leaves or enters layer; see docs
onFocusChange	(isFocused: boolean) => void		false	invoked when focus is moved into/out of layer; see docs
onEscape	(event: KeyboardEvent) => void		false	invoked when escape is pressed; see docs
className	string	""	false	CSS class name to add to the modal box
style	React.CSSProperties	{}	false	CSS inline style to add to the modal box

<Tooltip> component

The tooltip primitive displays hovered content that is bound to the UI that opened it, usually used to label or describe it.

props:

name	type	default	required	description
mouseDelay	number	500	delay for mouse out / in
positionX	"before" | "start" | "center" | "end" | "after"	"center"	false	align X position
positionY	"before" | "start" | "center" | "end" | "after"	"before"	false	align X position
margin	number	0	false	requested gap from anchor

<Popover> component

The modal primitive display content that is not affected by the scroll of lower layers while being bound to the UI the opened it.

props:

name	type	default	required	description
backdrop	"none" | "block" | "hide"	"block"	false	background behavior; see docs
positionX	"before" | "start" | "center" | "end" | "after"	"center"	false	align X position
positionY	"before" | "start" | "center" | "end" | "after"	"after"	false	align Y position
margin	number	0	false	requested gap from anchor
avoidAnchor	boolean	false	false	attempt to not overlap the anchor that opened it while pushed in by overflow
matchWidth	boolean	false	false	force the popover box to be in the width of the anchor
matchHeight	boolean	false	false	force the popover box to be in the height of the anchor
show	boolean	true	false	flag if the layer should be displayed
onClickOutside	((target: EventTarget) => void		false	invoked on click outside; see docs
ignoreAnchorClick	boolean	false	false	when true click on anchor does not invoke onClickOutside handler
onMouseIntersection	(isInside: boolean) => void		false	invoked when mouse leaves or enters layer; see docs
onFocusChange	(isFocused: boolean) => void		false	invoked when focus is moved into/out of layer; see docs
onEscape	(event: KeyboardEvent) => void		false	invoked when escape is pressed; see docs
onDisplayChange	(isPositioned: boolean) => void		false	invoked when the popover is displayed (after positioning) or removed from DOM
className	string	""	false	CSS class name to add to the popover box
style	React.CSSProperties	{}	false	CSS inline style to add to the popover box