Mantis Querist

A smart and practical way to handle breakpoints in Stylus

Why?

Why use Mantis Querist if already exists Rupture? Let me explain.

First of all, Rupture is a great tool, but didn't work for me. I'll list here some points I tried to improve creating the Mantis Querist:

• Rupture works with block mixins, which eliminates the need to write the @media at-rule, but affect readability, especially when you need to use a media query that Rupture doesn't support. In Mantis Querist, the way to use media queries is more consistent and really much more clearer to read. Compare for yourself:

  This is worse...

  header
  footer
      some-property value
   
      @media print
          display none
   
  .element
      some-property value
   
      +from-width(3)
          another-property value

  ...than this

  header
  footer
      some-property value
   
      +media(print)
          display none
   
  .element
      some-property value
   
      +media(from('lg'))
          another-property value

  Mantis Querist uses functions, then you can do whatever you want with the return.

  $mobile = to('md')
  $mobile-portrait = join-media-query($mobile, $feature: '(orientation: portrait)')
   
  .element
      @media $mobile
          some-property value
   
      @media $mobile-portrait
          another-property value

• Rupture uses scale indices to identify a breakpoint, making difficult to know which breakpoint is at stake, and if a breakpoint is added or removed, it can completely change the index of each breakpoint. You also can pass the scale name, but you've to keep two variables in sync to avoid problems with indices. With Mantis Querist you name each breakpoint with the name you feel convenient in the same variable. See the configuration section.

Installation

The installation can be done in 3 steps:

• Step 1

  Install via NPM:

  $ npm i --save mantis-querist

• Step 2

  You can use this plugin in different ways, but all consist of passing the plugin to the .use method of Stylus. For this example, I'll use it with Gulp in a ES6 enviornment.

  import gulp from 'gulp';
  import stylus from 'gulp-stylus';
  import querist from 'mantis-querist';
   
  gulp.task('css', () =>
      gulp.src('path-to-source.styl')
          .pipe(stylus({
              use: [
                  querist()
              ]
          }))
          .pipe(gulp.dest('path-to-dest/'))
  );

• Step 3

  Now just import the plugin into your .styl file as you already know.

  @import 'mantis-querist'

Configuration

Mantis Querist has a hash named $mantis.querist.breakpoints that comes with some predefined breakpoints:

$mantis.querist.breakpoints ?= {
    sm: 0, // small
    md: 640, // medium
    lg: 960, // large
}

You can add, remove or modify breakpoints just changing the $mantis.querist.breakpoints variable. Examples:

Adding or changing

$mantis.querist.breakpoints.xl = 1440 // extra large
$mantis.querist.breakpoints.fl = 1920 // fucking large
 
// or
 
$my-breakpoints = {
    xl: 1440,
    fl: 1920
}
merge($mantis.querist.breakpoints, $my-breakpoints)
// => {"sm":"(0)","md":"(640)","lg":"(960)","xl":"(1440)","fl":"(1920)"}

Removing existing

remove($mantis.querist.breakpoints, 'lg')
// => {"lg", "(960)"}

Or simply replace

$mantis.querist.breakpoints = {
    foo: 123,
    bar: 456,
    baz: 789
}

Something very important is that breakpoints must be in ascending order, otherwise the media queries will not work as expected.

Functions

Mantis Querist has 4 main handy functions, they are: from, to, at and between.

│        sm                md                lg                xl
├─────────────────┼─────────────────┼─────────────────┼─────────────────>
│
│                                         from(lg)
│                                   ├───────────────────────────────────>
│
│                                          to(lg)
├─────────────────────────────────────────────────────┤
│
│                                          at(lg)
│                                   ├─────────────────┤
│
│                                     between(md, lg)
│                 ├───────────────────────────────────┤

from(breakpoint[, $type])

The from() is like (min-width: breakpoint)

to(breakpoint[, $type])

The to() is like (max-width: breakpoint)

at(breakpoint[, $type])

The at() is like (min-width: breakpoint) and (max-width: next-breakpoint)

between(min-breakpoint, max-breakpoint[, $type])

The between() is like (min-width: min-breakpoint) and (max-width: max-breakpoint)

The $type parameter is the media type, it's set to 'screen' by default, but you can change specifically in each function or directly in the configuration variable $mantis.querist.type. Set to false, will omit the media type from the media query.

There are other configuration variables in the $mantis.querist hash, like $mantis.querist.unit, that's defined as 'px', but you can change to the unit you want.

Usage

Once properly set up Mantis Querist, is very simple to use. See some examples:

.element-a
    background black
 
    +media(from('md'))
        background red
 
    +media(from('lg'))
        background green
 
.element-b
    float left
 
    +media(to('sm'))
        float none
        display block
 
.element-c
    position relative
 
    +media(between('md', 'lg', $type: 'tv'))
        position absolute

You also can use this way, without +media():

.element-a
    background black
 
    @media $from.md
        background red
 
    @media $from.lg
        background green
 
.element-b
    float left
 
    @media $to.sm
        float none
        display block
 
.element-c
    position relative
 
    @media $between.md.lg
        position absolute

All you need to do is run querist-init(), and this will generate a hash for each of the 4 main functions with all possible combinations. Example:

$from.sm = from('sm')
$from.md = from('md')
$from.lg = from('lg')
$to.sm = to('sm')
$to.md = to('md')
$to.lg = to('lg')
$at.sm = at('sm')
$at.md = at('md')
$at.lg = at('lg')
$between.sm.md = between('sm', 'md')
$between.sm.lg = between('sm', 'lg')
$between.md.lg = between('md', 'lg')

Questions?

If you've questions, issues or ideas, feel free to tweet me or talk to me through some of my contacts on my website.

License

© 2016 Acauã Montiel

MIT License