ember-element-query

ember-element-query !npm version 
===================

* Use element queries effortlessly on any element or component.
* Use it in the form of the {{element-query}} modifier or the component.
* Apply styles that respond based on element's own width rather than viewport width.
* Do CSS transforations and template transformations.

Element queries are a technique to do responsive transformations based on element's own size rather than viewport size.

It lets you implement reusable responsive components — with encapsulated styles, decoupled from their parent context. Such components will realign their content depending on how much space is available to them.

For example, if you put a responsive component into a tight sidebar, it will align its content vertically. When the sidebar expands, the component will realign horizontally in order to efficiently use available space.

Here's a biased comparison table with competing addons (as of 2021.08):

| | ember-element-query | ember-fill-up | ember-container-query |
| -------------------------------------------------- | :-----------------: | :--------------------------------------------------------: | :-----------------------------------------------------------------------: |
| Octane | ✔ | 🚫 | ✔ |
| ResizeObserver | ✔ | ✔ | 🚫 |
| Offers a modifier | ✔ | 🚫 | 🚫 |
| Offers a component | ✔ | ✔ | ✔ |
| Actively maintained | ✔ | 🚫 | ✔ |
| API convenience | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |

See detailed comparison with code samples.

*

- Demo
- API Docs
- Roadmap
- Rationale
- Concept of sizes
- How ember-element-query works
- Using attributes in CSS
- Edge cases
- ⚠ Use in compound selectors only!
- Installation
- Usage
- As a modifier
- As a component
- Advanced usage
- onResize callback
- Custom sizes
- Using height
- Using aspect ratio
- Opting out of width attributes
- Customizing attribute prefix
- Using multiple modifiers on the same element
- Disabling
- Customizing component element
- Debouncing
- CSS fallback
- FastBoot fallback
- Browser support
- Alternatives
- Comparison
- Defining custom rules rules, using template and CSS transformations
- Using default rule definitions
- Customizing element tag while doing template transformations
- Customizing element tag while doing pure CSS transformations
- Using directly on images and other void elements
- Using both width and height in a rule for template transformation
- Contributing
- Tools
- Installation
- Linting
- Running tests
- Running the dummy application
- License
- Credit

Demo
--------

https://lolmaus.github.io/ember-element-query/

This addon's demo is borrowed from ember-container-query per @ijlee2's generous permission.

API Docs
--------

https://lolmaus.github.io/ember-element-query/api/

Roadmap
-------

This addon is ~~in active development~~ complete! 🎉

* [x] {{element-query}} modifier
* [x] Exists
* [x] Sets up a ResizeObserver
* [x] Calls the onResize callback with params
* [x] Applies attributes to elements
* [x] Accepts sizes
* [x] Accepts sizesHeight
* [x] Accepts sizesRatio
* [x] Accepts prefix
* [x] Updates on arugments change
* [x] Add fool-proof exceptions
* [x] Disabling
* [x] Applying a general [eq] attribute
* [x] component
* [x] Exists
* [x] Applies attributes to itself
* [x] Calls the onResize callback with params
* [x] Yields block params
* [x] Accepts sizes
* [x] Accepts sizesHeight
* [x] Accepts sizesRatio
* [x] Accepts prefix
* [x] Accepts tagName
* [x] Disabling
* [x] Expose types
* [x] CI
* [x] npm package
* [x] Documentation
* [x] Concept
* [x] Feature description
* [x] Usage
* [x] Browser support
* [x] Comparison with alternatives
* [x] TypeDoc API documentation
* [x] Document
* [x] Set up auto deployment
* [x] Demo app

Rationale
---------

CSS media queries have a few disadvantages:

* They account for scrollbar width. On OSes with a scrollbar such as Windows and Linux, available document width is some 15px smaller than the one detected by a media query. Resulting styles are slightly inconsistent across OSes.
They are designed for creating responsive layouts, whereas making responsive components* is unreasonably hard:
* If your responsive component appears in different contexts, you have to define media queries separately for each context and make sure they don't overlap.
* If you want to make your responsive component reusable, you can't apply responsive styles directly to it because you don't know all the contexts it might be used in. Instead, you have to offer the styles as preprocessor mixins or CSS snippets, for the consuming app developer to apply them by hand in every context.
Responsive components put into dynamic contexts (such as collapsible sidebars, grids, other responsive components, etc) require lots* of media queries, which involve unreasonably complicated math. Check out this old demo for a rationale.

All those problems wouldn't exist if we were able to apply styles conditionally based on element's own width:

``css
/ Hypothetical sample. I wish these were possible, but alas! /

/ When .my-menu is <= 499px, apply margin-bottom to .my-menu--item /
.my-menu:max-width(499px) .my-menu--item {
margin-bottom: 10px;
}

/ When .my-menu is >= 500px, apply flex to it /
.my-menu:min-width(500px) {
display: flex;
}

/ When .my-menu is >= 500px, apply margin-right to .my-menu--item /
.my-menu:min-width(500px) .my-menu--item {
margin-right: 10px;
}
`

Unfortunately, CSS is not aware of element's current width, so pseudoselectors like :min-width(500px) are impossible... unless you use a tool like ember-element-query.

Concept of sizes
----------------

ember-element-query operates with sizes. "Sizes" are like T-shirt sizes, except they indicate element width.

The default sizes scale is:

Breakpoints: 0 200px 400px 600px 800px 1000px 1200px 1400px
├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────>
Sizes: · xxs · xs · s · m · l · xl · xxl · xxxl

The left limit of each size range is inclusive, the right limit is non-inclusive.

For example, an element is considered to be of size m when its width is >= 600px and < 800px.

Here's an explicit sizes chart:

Breakpoints: 0 200px 400px 600px 800px 1000px 1200px 1400px
├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────>
Sizes: · xxs · xs · s · m · l · xl · xxl · xxxl
· · · · · · · ·
xxs │ · · · · · · ·
0—199 ├────────┤· · · · · · ·
· · · · · · · ·
xs ├─────────┤ · · · · · ·
200—399 ├──────────────────┤· · · · · ·
· · · · · · · ·
s ├───────────────────┤ · · · · ·
400—599 ├────────────────────────────┤· · · · ·
· · · · · · · ·
m ├─────────────────────────────┤ · · · ·
600—799 ├──────────────────────────────────────┤· · · ·
· · · · · · · ·
l ├───────────────────────────────────────┤ · · ·
800—999 ├────────────────────────────────────────────────┤· · ·
· · · · · · · ·
xl ├─────────────────────────────────────────────────┤ · ·
1000—1199 ├──────────────────────────────────────────────────────────┤· ·
· · · · · · · ·
xxl ├───────────────────────────────────────────────────────────┤ ·
1200—1399 ├────────────────────────────────────────────────────────────────────┤·
· · · · · · · ·
xxxl ├─────────────────────────────────────────────────────────────────────┤
1400+ ├──────────────────────────────────────────────────────────────────────────>

How ember-element-query works
-----------------------------

ember-element-query applies HTML attributes to an element indicating its current size.

There are three types of attributes, all of them are applied at once:

* at- attribute is applied with element's current size.

For example, an element with width of 764px will receive an at-m attribute.

* from- attributes are applied with element's current size and all smaller sizes.

For example, an element with width of 764px will receive attributes from-xxs, from-xs, from-s and from-m.

* to- attributes are applied with element's current size and all larger sizes.

For example, an element with width of 764px will receive attributes to-m, to-l, to-xxl and to-xxxl.

Don't feel confused! This is very simple:

When you want say "when my element is of size M*", use the at-m attribute.
When you want say "when my element is of size M or larger*", use the from-m attribute.
When you want say "when my element is of size M or small*", use the to-m attribute.

$3

In order to do responsive CSS transformations, use attributes like this:

`css
.foo[at-xxs] {
/ These styles when be applied when the element has exactly the size of xxs, namely 0—199 px. /
}

.foo[from-xs] {
/ These styles when be applied when the element has the size of xxs or larger, namely 200+ px. /
}

.foo[to-xl] {
/ These styles when be applied when the element has the size of xl or smaller, namely 0—1199 px. /
}

.foo[from-s][to-l] {
/ These styles when be applied when the element has the size between s and l inclusively, namely 400—999 px. /
}
`

Responsive template transformations are also possible, see below.

$3

Note that some attribute usages don't make much sense:

* The smallest from- and the largest to- attribute are applied at all times, thus .foo[from-xxs] and .foo[to-xxxl] selectors are both equivalent to simply .foo.
* .foo[to-xxs] is equivalent to .foo[at-xxs], and .foo[from-xxxl] is equivalent to .foo[at-xxxl].
* .foo[from-m][to-m] is equivalent to .foo[at-m].

$3

Attribute selectors in CSS should only be used in conjunction with semantic selectors.

The following usage will mess up you website/app:

`css
/ Never do this! /
[at-m] {
float: left;
}

/ Still quite bad /
aside[at-m] {
float: left;
}

/ OK /
.my-side-block[at-m] {
float: left;
}
`

Installation
------------

Use ember-cli to install the addon as usual:

ember i ember-element-query

This addon does not do anything on install, so it can alternatively be installed with npm:

npm i -D ember-element-query

...or Yarn:

yarn add -D ember-element-query

Usage
-----

$3

Using the modifier is preferred if you only do CSS transformations, which is recommended according to the Responsiv Web Design doctrine.

Simply apply the {{element-query}} modifier to any element or angle bracket component like this:

`hbs

`

As a result, element query attributes will be applied to the element. The result could look like this:

`hbs

`

$3

The component is useful when you need to do template transformations.

If you want to render chunks of template conditionally, use this syntax:

`hbs

{{#if EQ.at-m}}
{{! This will only be rendered when the component is of size m. }}
{{/if}}

{{#if EQ.from-m}}
{{! This will only be rendered when the component is of size m or larger. }}


{{#if EQ.to-m}}
{{! This will only be rendered when the component is of size m or smaller. }}
{{/EQ.to-m}}

{{#if (and EQ.from-s EQ.to-l)}}
{{! This will only be rendered when the component is of size s, m or l. }}
{{/if}}

`

The first yield argument EQ is an object with current element query attributes. Keys are attribute names and values are true. Non-matching attributes are undefined. Thus, {{#if EQ.from-m}} renders only when the element is of size m or larger.

The second argument EQInfo is the same object that is passed to the onResize callback described below.

Advanced usage
--------------

$3

You can pass a callback to the onResize argument and it will be called whenever the element resizes:

`js
@action
reportResize(eqInfo) {
eqInfo.element // => current element
eqInfo.width // => current element's width in px (number)
eqInfo.height // => current element's height in px (number)
eqInfo.ratio // => current element's aspect ratio (width/height, number)
eqInfo.size // => current element's width size name (string or undefined)
eqInfo.sizeHeight // => current element's height size name (string or undefined)
eqInfo.sizeRatio // => current element's aspect ratio size name (string or undefined)
eqInfo.prefix // => current prefix (string or undefined)
eqInfo.attributes // => matching element query attributes in array form: ['from-xxs', 'from-xs', ...]
eqInfo.attributesRecord // => matching element query attributes in object form: {'from-xxs': true, 'from-xs': true, ...}
// non-matching attributes are not defined on the object
}
`

`hbs

`

`hbs

`

$3

Your tailored visual designs might require component switching layouts at specific breakpoints, different from this addon's defaults.

You can override the defaults with the sizes argument. It receives a plain object where keys are breakpoint names and arguments are numbers representing width.

⚠ One of the numbers must be 0, otherwise the addon will crash your app.

`hbs
{{element-query
sizes=(hash
small=0
medium=350
large=700
)
}}
>
`

`hbs
@sizes={{hash
small=0
medium=350
large=700
}}
>

`

The above example defines sizes like this:

* small: 0—349 px,
* medium: 350—699 px,
* large: 700+ px.

When the element has the width of 421px, it will receive attributes at-medium, from-medium, to-medium, from-small and to-large. (Confused? See above.)

$3

By default, only attributes for horizontal sizes are applied to your element.

If you want to use attributes for vertical sizes, set sizesHeight to true:

`hbs

`

`hbs

`

Enabling heightSizes will cause two sets of attributes to be applied: width and height. Attributes representing width sizes will be the same as usual. Attributes representing height sizes will be postfixed with -height: xxs-height, xl-height, etc.

This lets you apply CSS like this:

`css
.foo[to-s][from-xl-height] {
/ I am thin and tall /
}
`

You can customize height sizes by passing a hash to @sizesHeight. Make sure that height size names are different from width sizes!

`hbs
{{element-query
sizesHeight=(hash small-height=0 medium-height=200 large-height=400)
}}
>