Skip to content

Commit 15f6330

Browse files
randombitsUKrandombitsUK
authored
chore: Update README (#33)
The README has been updated to sign-post the changes in v4.0.0 and to update the examples with @use.
1 parent 425e39c commit 15f6330

File tree

1 file changed

+89
-126
lines changed

1 file changed

+89
-126
lines changed

‎README.md‎

Lines changed: 89 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -6,101 +6,30 @@
66

77
## Breaking Change: v4.0.0
88

9-
### @import, @use and @forward
9+
v4.0.0 of GEL Grid uses the [@use](https://sass-lang.com/documentation/at-rules/use/) and [@forward](https://sass-lang.com/documentation/at-rules/forward/) approach and removes [@import](https://sass-lang.com/documentation/at-rules/import/).
1010

11-
The `@import` directive is now deprecated in favour of `@use` and `@forward`, see [SASS documentation](https://sass-lang.com/documentation/at-rules/use/) for more information.
11+
This has a number of consequences, but mostly the impact comes to how other modules are now loaded in and how you can access variables. Namespaces now come into play so please read the sass documention linked to above.
1212

13-
GEL Sass Tools has now been updated to `@use` and `@forward` to remove a large number of deprecation notices.
13+
In addition there were a number of __browser prefixes__ used in versions prior to v4. Given how much the browser landscape has changed since they were added, it is __now time to remove them__.
1414

15-
With the new @use directive, no var, function, or mixin is placed in global scope, and they are all scoped within the file.
16-
17-
This means that users will explicitly need to include the partial file in each file that may use its vars, functions or mixins.
18-
19-
As a result the right-to-left functionality will not work in the way it used to, because you can only bring in an external file once via `@use`.
20-
21-
Previously you could have:
22-
```
23-
.ltr {
24-
#{$margin-right}: 10px;
25-
#{$margin-left}: 10px;
26-
}
27-
28-
$rtl: true;
29-
@import '../sass-tools';
30-
31-
.rtl {
32-
#{$margin-right}: 10px;
33-
#{$margin-left}: 10px;
34-
}
35-
```
36-
37-
which compiled to:
38-
```
39-
.ltr {
40-
margin-right: 10px;
41-
margin-left: 10px;
42-
}
43-
44-
.rtl {
45-
margin-left: 10px;
46-
margin-right: 10px;
47-
}
48-
```
49-
50-
You can no longer do this, the rtl paramater must be set at the point of loading:
51-
```
52-
@use '../sass-tools';
53-
54-
.ltr {
55-
#{sass-tools.$margin-right}: 10px;
56-
#{sass-tools.$margin-left}: 10px;
57-
}
58-
```
59-
compiles to
60-
61-
```
62-
.ltr {
63-
margin-right: 10px;
64-
margin-left: 10px;
65-
}
66-
```
67-
68-
Whereas:
69-
```
70-
@use '../sass-tools' with ($rtl: true);
71-
72-
.rtl {
73-
#{sass-tools.$margin-right}: 10px;
74-
#{sass-tools.$margin-left}: 10px;
75-
}
76-
```
77-
compiles to
78-
79-
```
80-
.rtl {
81-
margin-left: 10px;
82-
margin-right: 10px;
83-
}
84-
```
85-
86-
87-
### Browser Prefixes
88-
89-
Browsers have moved forward considerably since GEL Sass Tools was created and the browser vendor prefixes are no longer required and have therefore been removed.
15+
For usage of GEL Sass Tools prior to v4.0.0 please reference the [v3.4.0 readme](https://github.com/bbc/gel-sass-tools/tree/3.4.0).
9016

9117

9218
## What is this?
9319

94-
GEL Sass Tools is a collection of Sass variables, functions and mixins which allows you to work with GEL units consistently within your Sass. It is also required by other [GEL Foundations](https://github.com/bbc/gel-foundations) components.
20+
GEL Sass Tools is a collection of Sass variables, functions and mixins which allows you to work with GEL units consistently within your Sass. It is also used by other [GEL Foundations](https://github.com/bbc/gel-foundations) components.
9521

9622
Here is how you could use these tools in your Sass:
9723

98-
```sass
24+
```scss
25+
@use 'gel-sass-tools/sass-tools';
26+
@use 'sass-mq/mq';
27+
9928
.my-component {
100-
margin-top: $gel-spacing-unit;
29+
margin-top: sass-tools.$gel-spacing-unit;
10130

102-
@include mq($from: gel-bp-m) {
103-
margin-top: double($gel-spacing-unit);
31+
@include mq.mq($from: gel-bp-m) {
32+
margin-top: sass-tools.double(sass-tools.$gel-spacing-unit);
10433
}
10534
}
10635
```
@@ -127,10 +56,10 @@ This would compile to:
12756
$ npm install --save gel-sass-tools
12857
```
12958

130-
```sass
59+
```scss
13160
// your-app/main.scss
132-
@use 'node_modules/gel-sass-tools/sass-tools';
133-
@use 'node_modules/sass-mq/mq'
61+
@use 'gel-sass-tools/sass-tools';
62+
13463
```
13564

13665
### Install manually
@@ -139,11 +68,22 @@ You can install this component manually by downloading the content of this Git r
13968

14069
> **Note:** you will manually need to manage the dependencies below, without these this component will fail to compile.
14170
142-
## Dependencies
14371

144-
In order to use the component you will need the following components available:
72+
### IMPORTANT: Specify a Loadpath
14573

146-
- [Sass MQ](https://github.com/sass-mq/sass-mq)
74+
Because this module depends on other modules such as [Sass MQ](https://github.com/sass-mq/sass-mq), when compiling your Sass it needs to know where find the referenced modules. It does this via a [loadPath](https://sass-lang.com/documentation/at-rules/use/#load-paths).
75+
76+
If compiling from the command line you can specify:
77+
```
78+
sass --load-path=node_modules/ <options>
79+
```
80+
81+
whereas within nodejs you can call compile ot compileAsync:
82+
```js
83+
await sass.compileAsync(file, { loadPaths: ['./node_modules'] })
84+
```
85+
86+
This ensures the dependencies required by this module can be loaded correctly.
14787

14888
## Usage
14989

@@ -169,19 +109,21 @@ The following breakpoints are defined and added to the [Sass MQ](https://github.
169109

170110
These can be called when using the `mq` mixin:
171111

172-
```sass
112+
```scss
113+
@use 'sass-mq/mq';
114+
173115
.my-component {
174116
...
175117

176-
@include mq($from: gel-bp-s) {
118+
@include mq.mq($from: gel-bp-s) {
177119
...
178120
}
179121

180-
@include mq($from: gel-bp-m) {
122+
@include mq.mq($from: gel-bp-m) {
181123
...
182124
}
183125

184-
@include mq($from: gel-bp-l) {
126+
@include mq.mq($from: gel-bp-l) {
185127
...
186128
}
187129
}
@@ -200,31 +142,37 @@ The following `math` functions are included:
200142

201143
These functions can be used inline with any numerical CSS rule. E.g:
202144

203-
```sass
145+
```scss
146+
@use 'gel-sass-tools/sass-tools';
147+
204148
.my-component {
205-
margin-bottom: halve($gel-spacing-unit);
206-
padding-left: double($gel-spacing-unit);
207-
padding-right: double($gel-spacing-unit);
149+
margin-bottom: sass-tools.halve(sass-tools.$gel-spacing-unit);
150+
padding-left: sass-tools.double(sass-tools.$gel-spacing-unit);
151+
padding-right: sass-tools.double(sass-tools.$gel-spacing-unit);
208152
}
209153
```
210154

211155
or functions can be nested within other Sass features such as mixins:
212156

213-
```sass
157+
```scss
158+
@use 'gel-sass-tools/sass-tools';
159+
214160
.my-component {
215-
@include toRem('margin-bottom', halve($gel-spacing-unit));
216-
@include toRem('padding-left', double($gel-spacing-unit));
217-
@include toRem('padding-right', double($gel-spacing-unit));
161+
@include sass-tools.toRem('margin-bottom', sass-tools.halve(sass-tools.$gel-spacing-unit));
162+
@include sass-tools.toRem('padding-left', sass-tools.double(sass-tools.$gel-spacing-unit));
163+
@include sass-tools.toRem('padding-right', sass-tools.double(sass-tools.$gel-spacing-unit));
218164
}
219165
```
220166

221167
### REM mixin
222168

223169
The `rem` tool can be used in two ways. Either by directly calling the `toRem($value)` function, which will convert the supplied value and return a `rem` unit. E.g:
224170

225-
```sass
171+
```scss
172+
@use 'gel-sass-tools/sass-tools';
173+
226174
.my-component {
227-
margin-bottom: toRem($gel-spacing-unit);
175+
margin-bottom: sass-tools.toRem(sass-tools.$gel-spacing-unit);
228176
}
229177
```
230178

@@ -233,9 +181,11 @@ The `rem` tool can be used in two ways. Either by directly calling the `toRem($v
233181
You can also use the `@include toRem($value);` mixin, which by default returns a `px` fallback to allow support for older browsers which don't support `rem` units. E.g:
234182

235183
**Sass**
236-
```sass
184+
```scss
185+
@use 'gel-sass-tools/sass-tools';
186+
237187
.my-component {
238-
@include toRem('margin-bottom', 16px);
188+
@include sass-tools.toRem('margin-bottom', 16px);
239189
}
240190
```
241191

@@ -281,7 +231,7 @@ Interpolation should be used for any property which has a direction (e.g. `paddi
281231

282232
Taking the following CSS as an example:
283233

284-
```sass
234+
```scss
285235
// Original Sass
286236
.my-component {
287237
float: left;
@@ -290,25 +240,30 @@ Taking the following CSS as an example:
290240

291241
For a RTL layout, `float: left;` should be flipped to `float: right;`. We can use the `flip()` function to accomplish this.
292242

293-
```sass
294-
// Flipped Sass
295-
.my-component {
296-
float: flip(left, right);
243+
```scss
244+
@use 'gel-sass-tools/sass-tools';
245+
246+
.ltr {
247+
float: sass-tools.flip(left, right);
248+
}
249+
250+
sass-tools.$rtl: true;
251+
252+
.rtl {
253+
float: sass-tools.flip(left, right);
297254
}
298255
```
299256

300257
When Sass comes across the `flip()` function, it will check the value of the `$rtl` variable. If `$rtl` is `false`, the `flip()` function will take the first parameter. If `$rtl` is `true`, the `flip()` function will take the second parameter.
301258

302259
The Sass will compile out as follows:
303260

304-
```sass
305-
// Compiled LTR style
306-
.my-component {
261+
```css
262+
.ltr {
307263
float: left;
308264
}
309265

310-
// Compiled RTL style
311-
.my-component {
266+
.rtl {
312267
float: right;
313268
}
314269
```
@@ -319,34 +274,42 @@ Interpolation is used to adjust CSS properties which contain a direction within
319274

320275
Taking the following CSS as an example:
321276

322-
```sass
277+
```scss
278+
@use 'gel-sass-tools/sass-tools';
279+
323280
// Original Sass
324281
.my-component {
325-
padding-left: $gel-spacing-unit; // 8px
282+
padding-left: sass-tools.$gel-spacing-unit; // 8px
326283
}
327284
```
328285

329286
For a RTL layout, `padding-left: 8px;` should be flipped to `padding-right: 8px;`.
330287

331288
In order to flip this, we have to interpolate the style property:
332289

333-
```sass
334-
// Flipped Sass
335-
.my-component {
336-
#{$padding-left}: $gel-spacing-unit; // 8px
290+
```scss
291+
@use 'gel-sass-tools/sass-tools';
292+
293+
.ltr {
294+
#{sass-tools.$padding-left}: sass-tools.$gel-spacing-unit; // 8px
337295
}
296+
297+
sass-tools.$rtl: true;
298+
299+
.rtl {
300+
#{sass-tools.$padding-left}: sass-tools.$gel-spacing-unit; // 8px
301+
}
302+
338303
```
339304

340305
This will compile out to:
341306

342-
```sass
343-
// Compiled LTR style
344-
.my-component {
307+
```css
308+
.ltr {
345309
padding-left: 8px;
346310
}
347311

348-
// Compiled RTL style
349-
.my-component {
312+
.rtl {
350313
padding-right: 8px;
351314
}
352315
```

0 commit comments

Comments
 (0)