Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mediamonks/seng-device-state-tracker
DeviceStateTracker is a utility class that tracks which media query is currently active using the matchMedia API.
https://github.com/mediamonks/seng-device-state-tracker
javascript media-queries seng typescript
Last synced: 3 days ago
JSON representation
DeviceStateTracker is a utility class that tracks which media query is currently active using the matchMedia API.
- Host: GitHub
- URL: https://github.com/mediamonks/seng-device-state-tracker
- Owner: mediamonks
- License: mit
- Created: 2017-05-27T14:13:20.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-10-24T07:40:32.000Z (over 6 years ago)
- Last Synced: 2025-01-04T01:47:51.318Z (29 days ago)
- Topics: javascript, media-queries, seng, typescript
- Language: TypeScript
- Homepage:
- Size: 325 KB
- Stars: 0
- Watchers: 14
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/mediamonks/seng-device-state-tracker)
[](https://codeclimate.com/github/mediamonks/seng-device-state-tracker)
[](https://coveralls.io/github/mediamonks/seng-device-state-tracker?branch=master)
[](https://www.npmjs.com/package/seng-device-state-tracker)
[](https://www.npmjs.com/package/seng-device-state-tracker)
# seng-device-state-tracker
DeviceStateTracker is a utility class that tracks which media query is currently active using the matchMedia API.
## Installation
### yarn / npm
```sh
yarn add seng-device-state-tracker
```
```sh
npm i -S seng-device-state-tracker
```
### other
We also have browser, amd, commonjs, umd, systemjs and es6 versions of
this module available attached to the [Github Releases](https://github.com/mediamonks/seng-device-state-tracker/releases).
### manual
Check the **build** section below to see your you can build for all the
targets yourself.
## Usage information
When using max-width media queries make sure to set the DeviceStateTracker in reverse order, set the
reverseDeviceStateOrder boolean truthy when initializing the DeviceStateTracker class.
To keep track of the currently selected media query set the stateIndicator boolean truthy. This will add a unstyled
div element to the DOM.
## Example configuration for deviceStateTracker
```js
const config = {
mediaQueries: {
X_SMALL: '(max-width: 479px)',
SMALL: '(min-width: 480px)',
MEDIUM: '(min-width: 768px)',
LARGE: '(min-width: 1024px)',
},
deviceState: {
X_SMALL: 0,
SMALL: 1,
MEDIUM: 2,
LARGE: 3,
},
// When the keys below aren't set it will default to false for these options
showStateIndicator: true,
reverseDeviceStateOrder: false,
};
```
## Usage TypeScript
**Configuration**
```ts
/**
* Object with available media queries
*/
export const mediaQueries:IMediaQuery = {
X_SMALL: '(max-width: 479px)',
SMALL: '(min-width: 480px)',
MEDIUM: '(min-width: 768px)',
LARGE: '(min-width: 1024px)',
MEDIUM_ISOLATE: '(min-width: 768px) and (max-width: 1023px)',
};
/**
* This enum is used by the DeviceStateTracker class to determine which of the media queries in
* the mediaQueries object above are considered 'device states'. Names of this enum have to
* correspond with one of the keys in the mediaQueries object. When using the DeviceStateTracker,
* make sure you have enough device states so that there will always be one with a matching media query.
*/
export enum DeviceState {
X_SMALL,
SMALL,
MEDIUM,
LARGE,
}
```
**Usage**
```ts
import DeviceStateTracker, { DeviceStateEvent } from 'seng-device-state-tracker';
import { mediaQueries, DeviceState } from './path/to/config/deviceStateConfig';
const deviceStateTracker:DeviceStateTracker = new DeviceStateTracker({
mediaQueries,
deviceState: DeviceState,
});
// Retrieve the current state after initialisation
const { state, name } = deviceStateTracker.currentDeviceState;
deviceStateTracker.addEventListener(DeviceStateEvent.STATE_UPDATE, (event:DeviceStateEvent) => {
if (event.data.state === DeviceState.SMALL) {
console.log('Matched', event.data.name);
}
});
```
## Usage JavaScript
**Configuration**
```js
export const mediaQueries = {
X_SMALL: '(max-width: 479px)',
SMALL: '(min-width: 480px)',
MEDIUM: '(min-width: 768px)',
LARGE: '(min-width: 1024px)',
MEDIUM_ISOLATE: '(min-width: 768px) and (max-width: 1023px)',
};
/**
* This enum is used by the DeviceStateTracker class to determine which of the media queries in
* the mediaQueries object above are considered 'device states'. Names of this enum have to
* correspond with one of the keys in the mediaQueries object. When using the DeviceStateTracker,
* make sure you have enough device states so that there will always be one with a matching media query.
*/
export const DeviceState = {
X_SMALL: 0,
SMALL: 1,
MEDIUM: 2,
LARGE: 3,
};
```
**Usage**
```js
import DeviceStateTracker, { DeviceStateEvent } from 'seng-device-state-tracker';
import { mediaQueries, DeviceState } from './path/to/config/deviceStateConfig';
const deviceStateTracker = new DeviceStateTracker({
mediaQueries,
deviceState: DeviceState,
});
// Retrieve the current state after initialisation
const { state, name } = deviceStateTracker.currentDeviceState;
deviceStateTracker.addEventListener(DeviceStateEvent.STATE_UPDATE, (event) => {
if (event.data.state === DeviceState.SMALL) {
console.log('Matched', event.data.name);
}
});
```
## Documentation
View the [generated documentation](http://mediamonks.github.io/seng-device-state-tracker/).
## Building
In order to build seng-device-state-tracker, ensure that you have [Git](http://git-scm.com/downloads)
and [Node.js](http://nodejs.org/) installed.
Clone a copy of the repo:
```sh
git clone https://github.com/mediamonks/seng-device-state-tracker.git
```
Change to the seng-device-state-tracker directory:
```sh
cd seng-device-state-tracker
```
Install dev dependencies:
```sh
yarn
```
Use one of the following main scripts:
```sh
yarn build # build this project
yarn dev # run dev-watch mode, serving example/index.html in the browser
yarn generate # generate all artifacts (compiles ts, webpack, docs and coverage)
yarn typings # install .d.ts dependencies (done on install)
yarn test:unit # run the unit tests
yarn validate # runs validation scripts, including test, lint and coverage check
yarn lint # run tslint on this project
yarn doc # generate typedoc documentation
```
When installing this module, it adds a pre-push hook, that runs the `validate`
script before committing, so you can be sure that everything checks out.
If you want to create the distribution files yourself, you can run the
`build-dist` script, and the following files will get generated in the
`dist` folder:
- **/dist/seng-device-state-tracker.js**: bundled with webpack, can be loaded from
a script tag, available as `window.SengDeviceStateTracker`
- **/dist/seng-device-state-tracker.min.js**: same as above, but minified
- **/dist/seng-device-state-tracker-amd.js**: bundled with webpack, can be used
with e.g. requirejs
- **/dist/seng-device-state-tracker-commonjs.js**: bundled with webpack, can be
used in systems that support commonjs, but you should just use npm
- **/dist/seng-device-state-tracker-umd.js**: bundled with webpack, works in the
browser, with requirejs, and in a commonjs system
- **/dist/seng-device-state-tracker-umd.min.js**: same as above, but minified
- **/dist/seng-device-state-tracker-system.js**: bundled with typescript, can be
used in systems that support systemjs
- **/dist/seng-device-state-tracker-es6.zip**: transpiled with typescript, only
types are removed from the source files
## Contribute
View [CONTRIBUTING.md](./CONTRIBUTING.md)
## Changelog
View [CHANGELOG.md](./CHANGELOG.md)
## Authors
View [AUTHORS.md](./AUTHORS.md)
## LICENSE
[MIT](./LICENSE) © MediaMonks