ESL Media Query

ESLMediaQuery is an extended browser MediaQueryList object and related utils such as rule-value pairs called ESLMediaRuleList.

In addition to native Media Features, ESLMediaQuery allows special shortcuts to simplify syntax and query usage. ESLMediaQuery is more tolerant to logical operations and allows using of multiple 'not' operators or having extra conditions inside the query (all and all still a valid condition). ESLMediaRuleList allows to map condition defined by ESLMediaQuery to the value, it is serializable and supports multiple formats to parse.
Both ESLMediaQuery and ESLMediaRuleList implements EventTarget interface, so they're compatible to use with DOM EventListeners, including ESLEventListener feature.

Supported ESL Media Query features

ESLMediaQuery API

ESLMediaQuery is a central API to create an extended Media Query conditions.

Note: ESLMediaQuery has no real instances and represents IMediaQueryConditionInterface interface. IMediaQueryConditionInterface is implemented by 4 types of inner conditions:

The ESLMediaQuery(IMediaQueryConditionInterface) instances provide the following set of properties and methods:

Event Target methods:

As the ESLMediaQuery implements EventListenr interface, you can use it in the following way:

class Test {
  @listen({ event: 'change', target: ESlMediaQuery.for('@-sm') })
  protected onQueryMatch(e: ESLMediaChangeEvent) {
    // ...
  }
}

The incoming JavaScript event will be an instance of ESLMediaChangeEvent.

ESLScreenBreakpoints

ESLScreenBreakpoints is a custom screen breakpoints registry. It allows defining a named screen width range.

Use ESLScreenBreakpoints.add static method to change default or define your own Screen Breakpoint.

You can also use ESLScreenBreakpoints.remove to exclude breakpoint shortcut from registry.

You can get all available screen breakpoints using the ESLScreenBreakpoints.names property or access the complete breakpoint definitions with the ESLScreenBreakpoints.get method, which will return an ESLScreenBreakpoint instance if it exists.

The list of predefined breakpoints is the following:

ESLScreenDPR

Additional preprocessor to provide DPR shortcuts.

ESLScreenDPR API

ESLMediaShortcuts new

ESLMediaShortcuts(previously ESLEnvShortcuts) is a registry for shortcuts to describe any static/dynamic related conditions that can be used inside ESLMediaQuery conditions.

A shortcut can be added to the registry through ESLMediaShortcuts.set method ESLMediaShortcuts allows adding boolean result that will be converted to all / not all query condition or setup result as native MediaQuery string.

ESLMediaShortcuts supports dynamic shortcut updates. Note: shortcut name cannot contain spaces, starts with a digit (after @ symbol) or contain any special characters except for - and _.

The list of predefined environment shortcuts is the following:

Note: ESLMediaShortcuts is a singleton for the window object. Note: ESLMediaShortcuts considered as a last processor in the ESLMediaQuery processing chain.

ESLMediaRule

Pair of ESLMediaQuery and value (payload) associated with a query condition. ESLMediaRule is used as an item for ESLMediaRuleList.
ESLMediaRule can be parsed from <ESL Media Query> => <value> syntax string, e.g. @XS => 1 (1 is the payload) or @+LG and @DESKTOP => desktop ('desktop' is the payload).

ESLMediaRule API

Event Target methods:

ESLMediaRuleList

ESLMediaRuleList is an observable ESLMediaRule collection. ESLMediaRuleList has methods to work with the whole rules list. It implements EventTarget interface and compatible with ESLEventListeners, so you can observe active value changes.

ESLMediaRuleList can be parsed from <default_value> | <ESL Media Rule> | <ESL Media Rule> string or can be defined with a tuple of corteges with a queries and values.

ESLMediaRuleList should be generalized with the result value type and according payload parser.

Rule defined without query part will match any (all) environment. Queries Examples:

If multiple rule queries satisfied, then the result ESLMediaRuleList value pill be computed as merged value of all active rules. For primitive types of payload that means that the last active rule wins. For objects deep merge result will be used as a result. See deepMerge ESLUtils method for merge details. ESLMediaRuleList use it independently of payload type.

Parsing queries examples:

// Basic parsing
ESLMediaRuleList.parse('1 | @XS => 2'); // first query from the sample above
ESLMediaRuleList.parse('1 | @XS => 2', String); // the same as sample above
ESLMediaRuleList.parse('1 | @XS => 2', Number); // first query from the sample above that store numeric values
ESLMediaRuleList.parse('@XS => {option: 1} | @+SM => {option: 2}', ESLMediaRuleList.OBJECT_PARSER); // second query from the sample above with an object payloads
ESLMediaRuleList.parse('@XS => {option: 1} | @+SM => {option: 2}', evaluate); // the same as the sample above 
ESLMediaRuleList.parse('1|2|3|4|5', '@xs|@sm|@md|@lg|@xl') // parses tuple payloads
ESLMediaRuleList.parse('@mqAlt1 => value1| @mqAlt2 => value2', '@mq1|@mq2'); // parses first argument as an arrow syntax without default tuple consideration.

// Tupple parsing
ESLMediaRuleList.parseTuple('@xs|@sm|@md|@lg|@xl', '1|2|3|4|5') // String payload example
ESLMediaRuleList.parseTuple('@xs|@sm|@md|@lg|@xl', '1|2|3|4|5',  Number) // Numeric payload sample

ESLMediaRuleList API

Event Target methods:

The incoming JavaScript event will be an instance of ESLMediaRuleListEvent.

ESLMediaQuery events

ESLMediaRuleListEvent

ESLMediaRuleListEvent is a custom event dispatched by ESLMediaRuleList instances.

ESLMediaRuleListEvent properties:

ESLMediaChangeEvent

ESLMediaChangeEvent is a custom event dispatched by ESLMediaQuery instances.

ESLMediaChangeEvent properties: