react-layer-stack - npm Package Compare versions

Comparing version 1.5.0 to 1.5.1

package.json

		{
		"name": "react-layer-stack",
		"version": "1.5.0",
		"version": "1.5.1",
		"description": "Simple but ubiquitously powerful and agnostic layering system for React. Useful for any kind of windowing/popover/modals/tooltip application",
		@@ -5,0 +5,0 @@ "repository": {

README.md

		[Live demo](https://fckt.github.io/react-layer-stack/)

		### Description
		### Rationale
		`react`/`react-dom` comes comes with 2 basic assumptions/ideas:
		- every UI is hierarchical naturally. This why we have the idea of `components` which wrap each other
		- `react-dom` mounts (physically) child component to its parent DOM node by default

		I've designed `react-layer-stack` to fix one of the most tricky problems React users are facing with: bottom-to-up UI communication. top-to-bottom flow covers the most UI needs naturally, but sometimes you need to take control over UI element which is linked to parent logically (means you need to use the local context of), but physically located in the different DOM branch. Modals, drag'n'drops, popovers, popups, windows - are the various examples of bottom-to-up UI elements (good analogy https://en.wikipedia.org/wiki/Zooming_user_interface).
		The problem is that sometimes the second property isn't what you want in your case. Sometimes you want to mount your component into different physical DOM node and hold logical connection between parent and child at the same time.

		This lib allows to hold (or share) context (closure) of deep children components with the top layers: you can use variables from closure (which will propagate automatically if you'll provide it to `use` property of `Layer`). Anonymous function which renders `Layer` into `LayerStackMountPoint` receives: layer info (state, index in stack), callbacks (to show and hide layers) and event data from the toggle which controlls this `Layer`.
		Canonical example is Tooltip-like component: at some point of development process you could find that you need to add some description for your `UI element`: it'll render in fixed layer and should know its coordinates (which are that `UI element` coord or mouse coords) and at the same time it needs information whether it needs to be shown right now or not, its content and some context from parent components. This example shows that sometimes logical hierarchy isn't match with the physical DOM hierarchy.

		```javascript
		import React, { Component } from 'react';
		import { Layer, LayerContext } from 'react-layer-stack';

		class Demo extends Component {
		render() {
		return (
		<div>
		<LayerContext id="lightbox">{({ showMe, hideMe }) => (
		<button onMouseLeave={ hideMe } onMouseMove={ ({ pageX, pageY }) => {
		showMe({
		left: pageX + 20, top: pageY,
		content: `“More Content! More!”,`,
		})
		}}>Move your pointer to it.</button> )}
		</LayerContext>

		<Layer id="lightbox">{(_, { content, top, left }) => // will be rendered into <LayerStackMountPoint />
		<div style={{ position: "fixed" }}>
		<div style={{
		top, left, position: "absolute",
		padding: '10px',
		background: 'rgba(0,0,0,0.7)', color: '#fff', borderRadius: '5px',
		boxShadow: '0px 0px 50px 0px rgba(0,0,0,0.60)'}}>
		{ content }
		</div>
		</div>
		}</Layer>
		</div>
		)
		```

		Another option could be use one of dozens complete implementations with different properties:
		https://js.coach/?search=popover

		### More examples
		https://github.com/fckt/react-layer-stack/blob/master/demo/src/Demo.js

		### Live demo
		https://fckt.github.io/react-layer-stack/

		### Installation
		@@ -14,2 +58,32 @@ ```

		### API

		#### `<LayerStackMountPoint />`

		This is mount point for `Layers`.

		`id: string` - you can have multiple `LayerStackMountPoint` which could have different ID's.

		`children: callback({ views, displaying, show: callback(id, args), hide, hideAll, mountPointId, mountPointArgs }): ReactElement` - you can choose different strategies how to render `Layers` in `LayerStackMountPoint` instead of the default one.

		#### `<Layer />`

		`id: string` - a Layer identificator

		`initialArgs` - initial arguments for a Layer

		`use: array` - array with context variables. Useful if you want to re-render the Layer if parent variables (closure) are changed

		`children: callback({ isActive, showMe: callback(args), showOnlyMe, hideMe, hideAll }, ...args): ReactElement` - will be rendered into

		#### `<LayerContext />`

		`id: string` - a Layer identificator which LayerContext corresponds to

		`children: callback({ isActive, showMe: callback(args), showOnlyMe, hideMe, hideAll }): ReactElement` - will be mounted (rendered) directly to its parent

		### Store layers in your redux store

		`react-layer-stack` provides `reducer` (`import { reducer } from 'react-layer-stack'`) which you can combine into your Redux store instead of using preconfigured `LayerStackProvider`. This is useful if you want to store everything in one store (which is good practice).

		### Real-world usage example
		@@ -76,6 +150,9 @@

		Another solution is to use on of ready-to-use components. But lot of times are you need slightly different bahavior/look and more productive to implememnt home-grown ad-hock solution.
		Another solution is to use on of ready-to-use components. But lot of times are you need slightly different behavior/look and more productive to implement home-grown ad-hock solution.

		And the last option is to find library like https://github.com/tajo/react-portal, designed ot address the needs of bottom-to-up communication. These libs are often quite opinionated to their cases and doesn't solve the problem in its roots. react-layer-stack aims to give an answer how to organise bottom-to-up communication in the most natural, reasonable and flexible way.
		And the last option is to find library like https://github.com/tajo/react-portal or https://react-bootstrap.github.io/react-overlays/, designed to address the needs of bottom-to-up communication. These libs are often quite opinionated to their cases and doesn't solve the problem in its roots. react-layer-stack aims to give an answer how to organize bottom-to-up communication in the most natural, reasonable and flexible way.

		### The future
		Obviously there is a lot of applications for the Layer API (https://github.com/fckt/react-layer-stack/blob/master/README.md#layer-). The cautious question is: could be it become a foundation or standard API to declare some kind of "universal" React "modules"? If so, could be the entire application become a "module"?

		### Images to understand the whole thing
		@@ -82,0 +159,0 @@ #### View layers stack

react-layer-stack - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics