You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -125,6 +127,150 @@ After initilization. The following methods can be used.
125
127
126
128
##### Events
127
129
128
-
## Gotchas
130
+
After the breakpoints module is initialized it fires a `breakpointChange` event on the window object whenever the viewport size moves past any one of the breakpoints. The `detail` property of the event contains four values
129
131
130
-
This library is in active development. Pull in a particular commit or tag, or coordinate with Dave if you'd like to use it in your project as it may be subject to change.
132
+
*`detail.breakpoint`: the largest single breakpoint the current viewport size size has surpassed
133
+
*`detail.breakpoints`: an array of breakpoints that the current viewport size has surpassed
134
+
*`detail.lastBreakpoint`: the largest single breakpoint the previous viewport size size had surpassed
135
+
*`detail.lastBreakpoints`: an array of breakpoints that the previous viewport size had surpassed
136
+
137
+
This can be used to trigger your own JS code on breakpoint changes. The example below fires whenever the viewport crosses the "desktop" breakpoint, either from smaller than desktop to bigger or visa versa:
138
+
139
+
```
140
+
import { Breakpoints } from '@evanshunt/derekstrap';
if (evt.detail.breakpoints.includes('desktop') !== evt.detail.lastBreakpoints.includes('desktop')) {
145
+
// do something here
146
+
}
147
+
});
148
+
```
149
+
150
+
Note that the event emitter is debounced. It will not fire until 50ms have passed since the last resize event.
151
+
152
+
### debounce.js
153
+
154
+
Derekstrap includes a `debounce()` helper function, used by the Breakpoints module. The code was borrowed from here: [https://davidwalsh.name/javascript-debounce-function](https://davidwalsh.name/javascript-debounce-function). Debouncing is a handy way to ensure a function that runs on resize, scroll, mouse movement or any other event which might occur many times in a row only runs after the action stops.
155
+
156
+
#### Example usage
157
+
158
+
```
159
+
import { debounce } from '@evanshunt/derekstrap';
160
+
161
+
var myResizeFunction = debounce(function() {
162
+
// do something here that you want to happen on
163
+
// resize, but not so often that it crashes the browser
See [src/Breakpoints.js](src/Breakpoints.js) for another example.
170
+
171
+
### Proportional Box
172
+
173
+
The proportional box module is intended to allow you to define an aspect ratio for an element. Often useful for elements which have a background image. The module consists of 3 mixins, two of which are helper methods for `proportional-box()` which is the one you will most likely use in your project.
174
+
175
+
The method takes 3 arguments. The `$view-width` and `$offset` arguments are optional and will depend on other styles applied to the element in order to function properly. By default the mixin assumes a full-bleed element. The opional arguments are there to configure an element that is not full bleed.
176
+
177
+
*`$aspect-ratio`: Width / height, probably best written as an expression which evaluates to a number, e.g. `16 / 9` rather than `1.77777`. (required)
178
+
*`$view-width`: Defaults to `100vw`. This argument should be the proportion of the viewport widht the element takes up, excluding fixed margins. If the element takes up 100% of the viewport except for a 50px margin on each side, the value here should still be `100vw`. Only pass a different value here if the image is not proportional to the entire viewport. If it should be `50vw` wide (excluding fixed margins) then pass `50vw`. (optional)
179
+
*`$offset`: Defaults to `0px`. This is the place to define fixed width margins. The value passed should reflect the margin _on one side_ of the element. It will be multiplied by 2 in the mixin. This logic assumes identical left and right margins. If that is not the case the offset value should be (left margin + right margin) / 2.
180
+
181
+
The following background image properties are added to the element using this mixin:
182
+
183
+
```
184
+
background-size: cover;
185
+
background-repeat: no-repeat;
186
+
background-position: center;
187
+
```
188
+
189
+
#### Example usage
190
+
191
+
```
192
+
@use '~@evanshunt/derekstrap';
193
+
194
+
// Gives a full bleed widget element a 3/2 aspect ratio
195
+
.widget {
196
+
@include derekstrap.proportional-box(3/2);
197
+
margin: 0;
198
+
width: 100vw;
199
+
background-image: url(example.png);
200
+
}
201
+
202
+
// Gives a small widget that fills 50% of the viewport with a 20px margin on either side a 1/1 apsect ratio.
This module sets the base sizing of text relative to viewport, with resets at each breakpoint defined and configured with the [Breakpoints](#Breakpoints) module. This allows layouts to behave more consistently with fewer odd issues caused by line wrapping. The breakpoint resets ensure the text does not huge on large screens.
214
+
215
+
In most cases it will be sufficient to import this module in your stylesheets without any additional configuration. It is included by default if you import Derekstrap but to use this module alone you would do the following:
216
+
217
+
```
218
+
@use '~@evanshunt/derekstrap/proportional-text';
219
+
```
220
+
221
+
### setUserAgent.js
222
+
223
+
When Derekstrap is imported and initialized it runs [setUserAgent.js](src/setUserAgent.js) which appends the browser user agent string to a `data-user-agent` attribute `html` element.
224
+
225
+
```
226
+
import { Derekstrap} from '@evanshunt/derekstrap';
227
+
Derekstrap.init();
228
+
```
229
+
230
+
This will result in markup like the following:
231
+
232
+
```
233
+
<html lang="en" data-useragent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Safari/605.1.15">
234
+
```
235
+
236
+
### Spacing
237
+
238
+
The spacing module is a set of mixins for defining the whitespace around a block. It is intended to allow consistency across blocks, and for flexibility allows use of `padding`, `margin` or `left`/`right`/`top`/`bottom` attributes to create the whitespace. By default the mixins will apply to both top and bottom or both left and right, and will use the `padding` attribute, but this can be configured with optional arguments.
239
+
240
+
To standardize spacing across blocks it will be useful to define your own variable map of spacing using the same breakpoint names as used with the [Breakpoints](#Breakpoints) module.
Note that when the spacing is applied to only one side the element, the opposite side gets set to zero. It is not possible at this time to use the mixin to set different spacing on either side of the element using the same attribute. Configuring both sides independently will be possible in version 1.0.
0 commit comments