Responsive

Specifies the various responsive state objects keyed by their name. Each key (except '*', see below) in this object is a state name (see responsiveState) and its corresponding value is the associated ResponsiveState object.

This property makes it easy to create mobile-friendly widgets that adapt to the size of the device they are being used on.

Some properties of a ResponsiveState object are special, for example when and callback. All other properties of the state object are config properties to apply when that state is active.

The when property can be a function that computes the score for the state. The state whose when function returns the lowest score is selected and its non-special properties will be assigned to the instance. If when is a number, it will be converted into a scoring function (see below).

A when function accepts two readonly parameters and returns either a numeric score if the state should be considered, or false or null if the state should be ignored (i.e., it does match with the current state).

The first parameter is a readonly proxy for the widget whose size and other properties determine the state's score. The proxy tracks property access to that widget in order to update the responsive state should any of those properties change.

The second argument to a when function is the BrowserHelper singleton. This allows a when function to conveniently test platform and browser information.

The state whose when function returns the lowest score is selected as the new responsiveState and its config object (minus the when function and other special properties) is applied to the instance.

If when is a number, it is converted to function. The following two snippets produce the same when scoring:

     small : {
         when : 400,
         ...
     }

The above converted to:

     small : {
         when : ({ width }) => width <= 400 && 400,
         ...
     }

Selecting the lowest score as the winner allows for the simple conversion of width threshold to score value, such that the state with the smallest matching width is selected.

If the responsive config object has an asterisk key ('*'), its value is used as the default set of config properties to apply all other states. This will be the only config properties to apply if no when function returns a score. In this way, this special state object acts as a default state as well as a set of default values for other states to share. This state object has no when function.

The default for this config is:

 {
     small : {
         when : 400
     },

     medium : {
         when : 800
     },

     large : {
         when : () => Infinity
     },

     '*' : {}
 }

A derived class (or instance) can use these states by populating other config properties, define additional states, and/or adjust the when properties to use different size thresholds.

Set to true to mark this instance as the default responsiveTarget for descendants that do not specify an explicit responsiveTarget of their own.

The name of the active state of the responsive config. This is assigned internally and should not be assigned directly.

The widget whose size and other properties drive this object's responsive behavior. If this config is not specified, the closest ancestor that specified responsiveRoot=true will be used. If there is no such ancestor, then the instance using this mixin is used.

If this value is set to '@', then this instance is used even if there is a responsiveRoot ancestor.

If this config is a string that starts with '@', the text following the first character is the name of the property on this instance that holds the target to use. For example, '@owner' to use the value of the owner property as the responsive target.

If this config is a string that does not start with '@', that string is passed to up to find the closest matching ancestor.

If another widget is used as the responsiveTarget and if this instance does not specify any explicit when properties in its responsive config, then the when definitions of the responsiveTarget will be used for this instance.

Triggered before a new responsiveState is applied.

Triggered when a new responsiveState is applied.

Called before a new responsiveState is applied.

Called when a new responsiveState is applied.

A state definition object used by the responsive config property.

 {
     responsive : {
         small : {
             // a ResponsiveState object
             when : 400,

             callback() {
                 console.log('Applied small not first time');
             },

             once : {
                 mode : 'full',

                 callback() {
                     console.log('Applied small first time');
                 }
             }

             // All other properties are configs to apply when
             // the state is active
             text  : null,
             color : 'b-blue'
         }
     }
 }

See Responsive for more details.