@mastors/flexer 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +112 -361
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,103 +1,95 @@
1
1
  # @mastors/flexer
2
2
 
3
- > Complete flexbox utility class system for the Mastors ecosystem.
3
+ > Complete flexbox utility class system + authoring mixins for the Mastors ecosystem.
4
4
 
5
- [![npm](https://img.shields.io/npm/v/@mastors/flexer.svg)](https://www.npmjs.com/package/@mastors/flexer)
5
+ [![npm version](https://img.shields.io/npm/v/@mastors/flexer.svg)](https://www.npmjs.com/package/@mastors/flexer)
6
6
  [![license](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
7
- [![sass](https://img.shields.io/badge/requires-sass%20%3E%3D1.80-CC6699.svg)](https://sass-lang.com)
8
-
9
- ---
10
-
11
- ## Table of Contents
12
-
13
- - [Overview](#overview)
14
- - [Installation](#installation)
15
- - [Usage](#usage)
16
- - [Utility Classes](#utility-classes)
17
- - [Display](#display)
18
- - [Flex Direction](#flex-direction)
19
- - [Flex Wrap](#flex-wrap)
20
- - [Flex Flow](#flex-flow)
21
- - [Flex Grow & Shrink](#flex-grow--shrink)
22
- - [Flex Basis](#flex-basis)
23
- - [Flex Shorthand](#flex-shorthand)
24
- - [Justify Content](#justify-content)
25
- - [Justify Items](#justify-items)
26
- - [Justify Self](#justify-self)
27
- - [Align Content](#align-content)
28
- - [Align Items](#align-items)
29
- - [Align Self](#align-self)
30
- - [Place Content](#place-content)
31
- - [Place Items](#place-items)
32
- - [Place Self](#place-self)
33
- - [Order](#order)
34
- - [Gap](#gap)
35
- - [Responsive Variants](#responsive-variants)
36
- - [Package Exports](#package-exports)
37
- - [Peer Dependencies](#peer-dependencies)
38
7
 
39
8
  ---
40
9
 
41
10
  ## Overview
42
11
 
43
- `@mastors/flexer` provides a complete set of atomic utility classes for CSS Flexbox — covering every flex container and flex item property. All utilities are generated via the core `generate-utilities()` engine and fully support responsive breakpoint prefixes.
44
-
45
- The package requires `@mastors/core` as a peer dependency and consumes its public API for token values and the generator engine. It produces no output of its own beyond utility classes — no reset, no base styles.
12
+ `@mastors/flexer` delivers a full set of flexbox utility classes and authoring mixins built on top of `@mastors/core`. Every class has a responsive variant — just prefix with a breakpoint key (e.g. `.md:flex-col`).
46
13
 
47
14
  ---
48
15
 
49
16
  ## Installation
50
17
 
51
18
  ```bash
52
- npm install @mastors/flexer @mastors/core sass
19
+ npm install @mastors/flexer @mastors/core
53
20
  # or
54
- pnpm add @mastors/flexer @mastors/core sass
21
+ pnpm add @mastors/flexer @mastors/core
22
+ ```
23
+
24
+ Requires `sass >= 1.80.0`:
25
+
26
+ ```bash
27
+ npm install --save-dev sass
55
28
  ```
56
29
 
57
30
  ---
58
31
 
59
32
  ## Usage
60
33
 
61
- ### Import the full stylesheet
34
+ ### Import the stylesheet
62
35
 
63
36
  ```scss
64
- // Import @mastors/core first (or alongside), then flexer
65
37
  @use "@mastors/core/scss";
66
38
  @use "@mastors/flexer/scss";
67
39
  ```
68
40
 
69
- ### Import flexer standalone (with core)
41
+ Or import only the SCSS source to compile yourself:
70
42
 
71
43
  ```scss
72
- // Flexer internally @uses @mastors/core/api — just import the package
73
- @use "@mastors/flexer/scss";
44
+ @use "@mastors/flexer/scss/index";
74
45
  ```
75
46
 
76
- ### Import a single partial
47
+ ### Use authoring mixins
77
48
 
78
49
  ```scss
79
- @use "@mastors/flexer/scss/utilities/flex-direction";
50
+ @use "@mastors/core/api" as m;
51
+ @use "@mastors/flexer/scss/mixins" as flex;
52
+
53
+ .hero {
54
+ @include flex.flex-container(row, wrap, center, center, 4);
55
+ }
56
+
57
+ .hero__item {
58
+ @include flex.flex-item(1, 1, auto, center);
59
+ }
60
+
61
+ .centered-card {
62
+ @include flex.flex-center;
63
+ }
80
64
  ```
81
65
 
82
- ### HTML usage
66
+ ### Use the generator
83
67
 
84
- ```html
85
- <!-- Flex container -->
86
- <div class="flex flex-row items-center justify-between gap-4">
87
- <div class="flex-1">Grows to fill space</div>
88
- <div class="shrink-0">Does not shrink</div>
89
- </div>
90
-
91
- <!-- Responsive column → row layout -->
92
- <div class="flex flex-col md:flex-row gap-6">
93
- <aside class="basis-1/4">Sidebar</aside>
94
- <main class="flex-1">Content</main>
95
- </div>
96
-
97
- <!-- Centred content -->
98
- <div class="flex items-center justify-center">
99
- <p>Perfectly centered</p>
100
- </div>
68
+ ```scss
69
+ @use "@mastors/flexer/scss/generators/flex-generator" as gen;
70
+
71
+ @include gen.generate-flex-utilities((
72
+ direction: true,
73
+ wrap: true,
74
+ justify: true,
75
+ align: true,
76
+ grow: true,
77
+ shrink: false,
78
+ order: false,
79
+ responsive: true,
80
+ ));
81
+ ```
82
+
83
+ ---
84
+
85
+ ## Package Exports
86
+
87
+ ```json
88
+ {
89
+ ".": "./dist/mastors-flexer.css",
90
+ "./scss": "./scss/index.scss",
91
+ "./scss/*": "./scss/*"
92
+ }
101
93
  ```
102
94
 
103
95
  ---
@@ -106,20 +98,12 @@ pnpm add @mastors/flexer @mastors/core sass
106
98
 
107
99
  ### Display
108
100
 
109
- Sets `display` to a flex context.
110
-
111
101
  | Class | CSS |
112
102
  |---|---|
113
103
  | `.flex` | `display: flex` |
114
104
  | `.inline-flex` | `display: inline-flex` |
115
105
 
116
- Both support responsive prefixes: `.md:flex`, `.lg:inline-flex`.
117
-
118
- ---
119
-
120
- ### Flex Direction
121
-
122
- Controls the main axis direction of a flex container.
106
+ ### Direction
123
107
 
124
108
  | Class | CSS |
125
109
  |---|---|
@@ -128,347 +112,114 @@ Controls the main axis direction of a flex container.
128
112
  | `.flex-col` | `flex-direction: column` |
129
113
  | `.flex-col-reverse` | `flex-direction: column-reverse` |
130
114
 
131
- All support responsive prefixes.
132
-
133
- ---
134
-
135
- ### Flex Wrap
136
-
137
- Controls whether flex items wrap to new lines.
115
+ ### Wrap
138
116
 
139
117
  | Class | CSS |
140
118
  |---|---|
141
119
  | `.flex-wrap` | `flex-wrap: wrap` |
142
- | `.flex-wrap-reverse` | `flex-wrap: wrap-reverse` |
143
120
  | `.flex-nowrap` | `flex-wrap: nowrap` |
144
-
145
- All support responsive prefixes.
146
-
147
- ---
148
-
149
- ### Flex Flow
150
-
151
- Sets `flex-flow` (direction + wrap) in one property.
152
-
153
- | Class | CSS |
154
- |---|---|
155
- | `.flex-flow-row-wrap` | `flex-flow: row wrap` |
156
- | `.flex-flow-row-nowrap` | `flex-flow: row nowrap` |
157
- | `.flex-flow-row-wrap-reverse` | `flex-flow: row wrap-reverse` |
158
- | `.flex-flow-col-wrap` | `flex-flow: column wrap` |
159
- | `.flex-flow-col-nowrap` | `flex-flow: column nowrap` |
160
- | `.flex-flow-col-wrap-reverse` | `flex-flow: column wrap-reverse` |
161
-
162
- All support responsive prefixes.
163
-
164
- ---
165
-
166
- ### Flex Grow & Shrink
167
-
168
- Controls whether a flex item can grow or shrink.
169
-
170
- | Class | CSS |
171
- |---|---|
172
- | `.grow` | `flex-grow: 1` |
173
- | `.grow-0` | `flex-grow: 0` |
174
- | `.shrink` | `flex-shrink: 1` |
175
- | `.shrink-0` | `flex-shrink: 0` |
176
-
177
- ---
178
-
179
- ### Flex Basis
180
-
181
- Sets the initial main-size of a flex item.
182
-
183
- **Named values:**
184
-
185
- | Class | CSS |
186
- |---|---|
187
- | `.basis-auto` | `flex-basis: auto` |
188
- | `.basis-full` | `flex-basis: 100%` |
189
- | `.basis-0` | `flex-basis: 0px` |
190
-
191
- **Fractional values:**
192
-
193
- | Class | Value |
194
- |---|---|
195
- | `.basis-1/2` | `50%` |
196
- | `.basis-1/3` | `33.333%` |
197
- | `.basis-2/3` | `66.667%` |
198
- | `.basis-1/4` | `25%` |
199
- | `.basis-2/4` | `50%` |
200
- | `.basis-3/4` | `75%` |
201
- | `.basis-1/5` | `20%` |
202
- | `.basis-2/5` | `40%` |
203
- | `.basis-3/5` | `60%` |
204
- | `.basis-4/5` | `80%` |
205
- | `.basis-1/6` | `16.667%` |
206
- | `.basis-5/6` | `83.333%` |
207
- | `.basis-1/12` | `8.333%` |
208
-
209
- **Fixed rem values:** `.basis-16` through `.basis-96` (4rem–24rem in standard spacing steps).
210
-
211
- ---
212
-
213
- ### Flex Shorthand
214
-
215
- The most commonly used flex item presets.
216
-
217
- | Class | CSS | When to use |
218
- |---|---|---|
219
- | `.flex-1` | `flex: 1 1 0%` | Grow and shrink, ignore natural size |
220
- | `.flex-auto` | `flex: 1 1 auto` | Grow and shrink, respect natural size |
221
- | `.flex-initial` | `flex: 0 1 auto` | Don't grow, but shrink if needed (browser default) |
222
- | `.flex-none` | `flex: none` | Rigid — no grow, no shrink |
223
-
224
- ---
121
+ | `.flex-wrap-reverse` | `flex-wrap: wrap-reverse` |
225
122
 
226
123
  ### Justify Content
227
124
 
228
- Aligns flex items along the **main axis**.
229
-
230
- | Class | CSS |
231
- |---|---|
232
- | `.justify-start` | `justify-content: flex-start` |
233
- | `.justify-end` | `justify-content: flex-end` |
234
- | `.justify-center` | `justify-content: center` |
235
- | `.justify-between` | `justify-content: space-between` |
236
- | `.justify-around` | `justify-content: space-around` |
237
- | `.justify-evenly` | `justify-content: space-evenly` |
238
- | `.justify-stretch` | `justify-content: stretch` |
239
- | `.justify-normal` | `justify-content: normal` |
240
-
241
- All support responsive prefixes.
242
-
243
- ---
244
-
245
- ### Justify Items
246
-
247
- Aligns flex items along the **inline axis** (all items).
248
-
249
- | Class | CSS |
250
- |---|---|
251
- | `.justify-items-start` | `justify-items: start` |
252
- | `.justify-items-end` | `justify-items: end` |
253
- | `.justify-items-center` | `justify-items: center` |
254
- | `.justify-items-stretch` | `justify-items: stretch` |
255
-
256
- All support responsive prefixes.
257
-
258
- ---
259
-
260
- ### Justify Self
261
-
262
- Aligns a **single** flex item along the inline axis.
263
-
264
- | Class | CSS |
265
- |---|---|
266
- | `.justify-self-auto` | `justify-self: auto` |
267
- | `.justify-self-start` | `justify-self: start` |
268
- | `.justify-self-end` | `justify-self: end` |
269
- | `.justify-self-center` | `justify-self: center` |
270
- | `.justify-self-stretch` | `justify-self: stretch` |
271
-
272
- All support responsive prefixes.
273
-
274
- ---
275
-
276
- ### Align Content
277
-
278
- Aligns **wrapped flex lines** along the cross axis.
279
-
280
- | Class | CSS |
281
- |---|---|
282
- | `.content-normal` | `align-content: normal` |
283
- | `.content-center` | `align-content: center` |
284
- | `.content-start` | `align-content: flex-start` |
285
- | `.content-end` | `align-content: flex-end` |
286
- | `.content-between` | `align-content: space-between` |
287
- | `.content-around` | `align-content: space-around` |
288
- | `.content-evenly` | `align-content: space-evenly` |
289
- | `.content-stretch` | `align-content: stretch` |
290
- | `.content-baseline` | `align-content: baseline` |
291
-
292
- All support responsive prefixes.
293
-
294
- ---
125
+ `.justify-start` `.justify-end` `.justify-center` `.justify-between` `.justify-around` `.justify-evenly`
295
126
 
296
127
  ### Align Items
297
128
 
298
- Aligns **all** flex items along the cross axis.
129
+ `.items-start` `.items-end` `.items-center` `.items-baseline` `.items-stretch`
299
130
 
300
- | Class | CSS |
301
- |---|---|
302
- | `.items-start` | `align-items: flex-start` |
303
- | `.items-end` | `align-items: flex-end` |
304
- | `.items-center` | `align-items: center` |
305
- | `.items-stretch` | `align-items: stretch` |
306
- | `.items-baseline` | `align-items: baseline` |
131
+ ### Align Content
307
132
 
308
- All support responsive prefixes.
309
-
310
- ---
133
+ `.content-start` `.content-end` `.content-center` `.content-between` `.content-around` `.content-evenly`
311
134
 
312
135
  ### Align Self
313
136
 
314
- Aligns a **single** flex item along the cross axis.
315
-
316
- | Class | CSS |
317
- |---|---|
318
- | `.self-auto` | `align-self: auto` |
319
- | `.self-start` | `align-self: flex-start` |
320
- | `.self-end` | `align-self: flex-end` |
321
- | `.self-center` | `align-self: center` |
322
- | `.self-stretch` | `align-self: stretch` |
323
- | `.self-baseline` | `align-self: baseline` |
324
-
325
- All support responsive prefixes.
326
-
327
- ---
328
-
329
- ### Place Content
330
-
331
- Shorthand for `align-content` + `justify-content`.
332
-
333
- | Class | CSS |
334
- |---|---|
335
- | `.place-content-center` | `place-content: center` |
336
- | `.place-content-start` | `place-content: start` |
337
- | `.place-content-end` | `place-content: end` |
338
- | `.place-content-between` | `place-content: space-between` |
339
- | `.place-content-around` | `place-content: space-around` |
340
- | `.place-content-evenly` | `place-content: space-evenly` |
341
- | `.place-content-stretch` | `place-content: stretch` |
342
- | `.place-content-baseline` | `place-content: baseline` |
343
-
344
- All support responsive prefixes.
137
+ `.self-auto` `.self-start` `.self-end` `.self-center` `.self-stretch` `.self-baseline`
345
138
 
346
- ---
139
+ ### Place Content / Items
347
140
 
348
- ### Place Items
141
+ `.place-content-start` `.place-content-center` `.place-content-between` `.place-content-stretch`
142
+ `.place-items-start` `.place-items-center` `.place-items-end` `.place-items-stretch`
349
143
 
350
- Shorthand for `align-items` + `justify-items`.
144
+ ### Grow / Shrink
351
145
 
352
- | Class | CSS |
353
- |---|---|
354
- | `.place-items-start` | `place-items: start` |
355
- | `.place-items-end` | `place-items: end` |
356
- | `.place-items-center` | `place-items: center` |
357
- | `.place-items-stretch` | `place-items: stretch` |
358
- | `.place-items-baseline` | `place-items: baseline` |
146
+ `.grow` `.grow-0` `.shrink` `.shrink-0`
359
147
 
360
- All support responsive prefixes.
148
+ ### Flex Shorthand
361
149
 
362
- ---
150
+ `.flex-1` `.flex-auto` `.flex-initial` `.flex-none`
363
151
 
364
- ### Place Self
152
+ ### Order
365
153
 
366
- Shorthand for `align-self` + `justify-self` on a single item.
154
+ `.order-first` `.order-last` `.order-none` `.order-1` through `.order-12`
367
155
 
368
- | Class | CSS |
369
- |---|---|
370
- | `.place-self-auto` | `place-self: auto` |
371
- | `.place-self-start` | `place-self: start` |
372
- | `.place-self-end` | `place-self: end` |
373
- | `.place-self-center` | `place-self: center` |
374
- | `.place-self-stretch` | `place-self: stretch` |
156
+ ### Gap
375
157
 
376
- All support responsive prefixes.
158
+ `.gap-0` through `.gap-96` (follows the core spacing scale)
159
+ `.gap-x-{n}` `.gap-y-{n}`
377
160
 
378
161
  ---
379
162
 
380
- ### Order
163
+ ## Authoring Mixins
381
164
 
382
- Controls the visual order of a flex item.
165
+ ### `flex-container($direction, $wrap, $justify, $align, $gap, $inline)`
383
166
 
384
- **Named values:**
167
+ One-call flex container configuration.
385
168
 
386
- | Class | CSS |
387
- |---|---|
388
- | `.order-first` | `order: -9999` |
389
- | `.order-last` | `order: 9999` |
390
- | `.order-none` | `order: 0` |
169
+ ```scss
170
+ @include flex.flex-container(
171
+ $direction: row,
172
+ $wrap: wrap,
173
+ $justify: space-between,
174
+ $align: center,
175
+ $gap: 4, // uses m.spacing(4)
176
+ $inline: false
177
+ );
178
+ ```
391
179
 
392
- **Numeric scale:** `.order-1` through `.order-12`.
180
+ ### `flex-item($grow, $shrink, $basis, $align-self, $order)`
393
181
 
394
- ---
182
+ One-call flex item configuration.
395
183
 
396
- ### Gap
184
+ ```scss
185
+ @include flex.flex-item(
186
+ $grow: 1,
187
+ $shrink: 1,
188
+ $basis: auto,
189
+ $align-self: center,
190
+ $order: null
191
+ );
192
+ ```
397
193
 
398
- Gap utilities (`.gap-*`, `.gap-x-*`, `.gap-y-*`) are provided by `@mastors/core` and work for both flex and grid containers. They do not need to be imported separately — they are available whenever `@mastors/core` is imported.
194
+ ### `flex-center` / `flex-center-x` / `flex-center-y`
399
195
 
400
- See the [`@mastors/core` spacing utilities](../core/README.md#utility-classes) for the full scale.
196
+ Single-line centering shortcuts.
401
197
 
402
- ```html
403
- <div class="flex gap-4">...</div>
404
- <div class="flex gap-x-6 gap-y-2">...</div>
198
+ ```scss
199
+ @include flex.flex-center; // centers on both axes
200
+ @include flex.flex-center-x; // centers horizontally only
201
+ @include flex.flex-center-y; // centers vertically only
405
202
  ```
406
203
 
407
204
  ---
408
205
 
409
206
  ## Responsive Variants
410
207
 
411
- Every utility marked `responsive: true` generates breakpoint-prefixed variants using the pattern `.{bp}:{class}`.
412
-
413
- **Breakpoints:**
414
-
415
- | Prefix | Min-width |
416
- |---|---|
417
- | *(none)* | 0px (mobile base) |
418
- | `sm:` | 640px |
419
- | `md:` | 768px |
420
- | `lg:` | 1024px |
421
- | `xl:` | 1280px |
422
- | `2xl:` | 1536px |
423
-
424
- **Examples:**
208
+ Every utility class ships a breakpoint-prefixed responsive variant:
425
209
 
426
210
  ```html
427
- <!-- Stack on mobile, row on md and above -->
428
- <div class="flex flex-col md:flex-row">
429
-
430
- <!-- Center on small, space-between on large -->
431
- <nav class="flex justify-center lg:justify-between">
432
-
433
- <!-- Change alignment per breakpoint -->
434
- <div class="flex items-start sm:items-center lg:items-end">
435
-
436
- <!-- Responsive flex display -->
437
- <div class="flex xl:inline-flex">
438
- ```
439
-
440
- Utilities that support responsive variants: `flex` display, `flex-direction`, `flex-wrap`, `flex-flow`, `justify-content`, `justify-items`, `justify-self`, `align-content`, `align-items`, `align-self`, `place-content`, `place-items`, `place-self`.
441
-
442
- ---
443
-
444
- ## Package Exports
445
-
446
- ```json
447
- {
448
- ".": "./dist/mastors-flexer.css",
449
- "./scss": "./scss/index.scss",
450
- "./scss/*": "./scss/*"
451
- }
211
+ <div class="flex-col md:flex-row lg:flex-row">...</div>
212
+ <div class="items-start md:items-center">...</div>
213
+ <div class="gap-4 lg:gap-8">...</div>
452
214
  ```
453
215
 
454
- ```scss
455
- /* Full flexer stylesheet */
456
- @use "@mastors/flexer/scss";
457
-
458
- /* Individual partial */
459
- @use "@mastors/flexer/scss/utilities/flex-direction";
460
- ```
216
+ Breakpoints: `sm:` `md:` `lg:` `xl:` `2xl:`
461
217
 
462
218
  ---
463
219
 
464
- ## Peer Dependencies
220
+ ## Changelog
465
221
 
466
- | Package | Version |
467
- |---|---|
468
- | `@mastors/core` | `>= 1.0.0` |
469
- | `sass` | `>= 1.80.0` |
470
-
471
- ---
222
+ See the [root CHANGELOG](../../README.md#changelog).
472
223
 
473
224
  ## License
474
225
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastors/flexer",
3
- "version": "1.1.0",
3
+ "version": "1.2.1",
4
4
  "description": "Mastors Flexer — complete flexbox utility class system",
5
5
  "license": "MIT",
6
6
  "author": "Mastors Contributors",