Declarative z-indexes (declarative-z-indexes)
Prevent z-index conflicts by generating them from declarative constraints
Have you ever struggled with exponential z-index wars? Have you ever changed a z-index only to find that you now need to change several others? Then declarative z-indexes are for you.
Instead of writing each z-index separately, you write out all of the different relationships between your z-index layers. Then, suitable z-indexes are generated for each of the layers. Easy as pie!
Table of Contents
Background
The idea for this library originally came from UIKit's Auto Layout constraints.
Install
Install using npm:
npm install declarative-z-indexes
Usage
First, create a solver using the exported LayerSolver class
const solver = ;Then, create some layers to be solved for
const body = solver;const header = solver;const modal = solver;Add constraints between your layers
header; modal;modal;And finally, generate your z-indexes!
const solution = solver; // {body: 1, header: 2, modal: 3}Note: Don't depend on the actual z-index values that are produced! The
generated z-indexes will always satisfy the constraints but the literal values
might change in future versions of this library. For instance, in the future
solver.solve() might return something else like {body: 100, header: 150, modal: 200}
if the generating algorithm is changed.
Use the generated z-indexes in inline styles
<body> <header => </header> <article => </article></body>API
LayerSolver
LayerSolver is the default export of declarative-z-indexes.
-
addLayer(name: string): Layer
TheaddLayermethod returns a new dynamic layer to be solved for. The same name cannot be reused for multiple layers. -
addStaticLayer(name: string, index: number): Layer
TheaddStaticLayermethod returns a new static layer. Static layers have a static z-index that will be used when solving the constraints for the dynamic layers.Example uses cases for static layers might be external library z-indexes that cannot be modified.
const solver = ;const modal = solver;const modalDecoration = solver;modalDecoration;solver; // {bootstrapModal: 1000, modalDecoration: 1001}(Note again: the resulting value of
bootstrapModalwill always be1000, but don't depend onmodalDecorationbeing1001! Its value will be above1000but the literal value might change in a future version of the library) -
solve(): {[layer: string]: number}
Thesolvemethod solves the current constraints on the dynamic layers and returns a map-like object from each layer's name to the generated z-index value.solveis idempotent: every time you call it,solvegenerates a brand new solution based on the constraints currently stored in the solver. It's safe to call solve multiple times and even add new constraints between calls without affecting past solutions.
Layer
A Layer is the object that is used to specify constraints in the system. It
is returned from a LayerSolver's addLayer and addStaticLayer methods.
-
isAbove(layer: Layer)
TheisAbovemethod adds a constraint that the current layer should be above the passed in layer. -
isBelow(layer: Layer)
TheisBelowmethod adds a constraint that the current layer should be below the passed in layer.
Contribute
The initial design and API of this library is still being created! Once that is done, we'll start taking contributions. Until then, hold tight!