@mastors/flexer 1.2.0 → 1.2.2

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 +111 -380
  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";
45
+ ```
46
+
47
+ ### Use authoring mixins
48
+
49
+ ```scss
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
+ }
74
64
  ```
75
65
 
76
- ### Import a single partial
66
+ ### Use the generator
77
67
 
78
68
  ```scss
79
- @use "@mastors/flexer/scss/utilities/flex-direction";
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
+ ));
80
81
  ```
81
82
 
82
- ### HTML usage
83
+ ---
83
84
 
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>
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,367 +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
- ---
347
-
348
- ### Place Items
349
-
350
- Shorthand for `align-items` + `justify-items`.
139
+ ### Place Content / Items
351
140
 
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` |
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`
359
143
 
360
- All support responsive prefixes.
144
+ ### Grow / Shrink
361
145
 
362
- ---
363
-
364
- ### Place Self
365
-
366
- Shorthand for `align-self` + `justify-self` on a single item.
367
-
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` |
146
+ `.grow` `.grow-0` `.shrink` `.shrink-0`
375
147
 
376
- All support responsive prefixes.
148
+ ### Flex Shorthand
377
149
 
378
- ---
150
+ `.flex-1` `.flex-auto` `.flex-initial` `.flex-none`
379
151
 
380
152
  ### Order
381
153
 
382
- Controls the visual order of a flex item.
383
-
384
- **Named values:**
154
+ `.order-first` `.order-last` `.order-none` `.order-1` through `.order-12`
385
155
 
386
- | Class | CSS |
387
- |---|---|
388
- | `.order-first` | `order: -9999` |
389
- | `.order-last` | `order: 9999` |
390
- | `.order-none` | `order: 0` |
156
+ ### Gap
391
157
 
392
- **Numeric scale:** `.order-1` through `.order-12`.
158
+ `.gap-0` through `.gap-96` (follows the core spacing scale)
159
+ `.gap-x-{n}` `.gap-y-{n}`
393
160
 
394
161
  ---
395
162
 
396
- ### Gap
163
+ ## Authoring Mixins
397
164
 
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.
165
+ ### `flex-container($direction, $wrap, $justify, $align, $gap, $inline)`
399
166
 
400
- See the [`@mastors/core` spacing utilities](../core/README.md#utility-classes) for the full scale.
167
+ One-call flex container configuration.
401
168
 
402
- ```html
403
- <div class="flex gap-4">...</div>
404
- <div class="flex gap-x-6 gap-y-2">...</div>
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
+ );
405
178
  ```
406
179
 
407
- ---
408
-
409
- ## Responsive Variants
410
-
411
- Every utility marked `responsive: true` generates breakpoint-prefixed variants using the pattern `.{bp}:{class}`.
412
-
413
- **Breakpoints:**
180
+ ### `flex-item($grow, $shrink, $basis, $align-self, $order)`
414
181
 
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:**
182
+ One-call flex item configuration.
425
183
 
426
- ```html
427
- <!-- Stack on mobile, row on md and above -->
428
- <div class="flex flex-col md:flex-row">
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
+ ```
429
193
 
430
- <!-- Center on small, space-between on large -->
431
- <nav class="flex justify-center lg:justify-between">
194
+ ### `flex-center` / `flex-center-x` / `flex-center-y`
432
195
 
433
- <!-- Change alignment per breakpoint -->
434
- <div class="flex items-start sm:items-center lg:items-end">
196
+ Single-line centering shortcuts.
435
197
 
436
- <!-- Responsive flex display -->
437
- <div class="flex xl:inline-flex">
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
438
202
  ```
439
203
 
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
204
  ---
443
205
 
444
- ## Package Exports
445
-
446
- ```json
447
- {
448
- ".": "./dist/mastors-flexer.css",
449
- "./scss": "./scss/index.scss",
450
- "./scss/*": "./scss/*"
451
- }
452
- ```
206
+ ## Responsive Variants
453
207
 
454
- ```scss
455
- /* Full flexer stylesheet */
456
- @use "@mastors/flexer/scss";
208
+ Every utility class ships a breakpoint-prefixed responsive variant:
457
209
 
458
- /* Individual partial */
459
- @use "@mastors/flexer/scss/utilities/flex-direction";
210
+ ```html
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>
460
214
  ```
461
215
 
462
- ---
463
-
464
- ## Peer Dependencies
465
-
466
- | Package | Version |
467
- |---|---|
468
- | `@mastors/core` | `>= 1.0.0` |
469
- | `sass` | `>= 1.80.0` |
216
+ Breakpoints: `sm:` `md:` `lg:` `xl:` `2xl:`
470
217
 
471
218
  ---
472
219
 
473
220
  ## Changelog
474
221
 
475
- ### v1.2.0
476
-
477
- - **Added:** `flex-container()` mixin — one-call flex container configuration (direction, wrap, justify, align, gap, inline)
478
- - **Added:** `flex-item()` mixin — one-call flex item configuration (grow, shrink, basis, align-self, order)
479
- - **Added:** `flex-center()` mixin — single-line centering shorthand; also ships `flex-center-x()` and `flex-center-y()` axis variants
480
- - **Added:** `generate-flex-utilities()` generator — emit a complete flex utility set from a config map with per-axis opt-in and a single `responsive` flag
481
- - **Updated dependency:** `@mastors/core@1.2.0`
482
-
483
- ### v1.1.0
484
-
485
- - Updated dependency: `@mastors/core@1.1.0`
486
-
487
- ### v1.0.0
488
-
489
- - Initial public release — full Flexbox utility set, `generate-utilities()` engine, full responsive breakpoint support
490
-
491
- ---
222
+ See the [root CHANGELOG](../../README.md#changelog).
492
223
 
493
224
  ## License
494
225
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastors/flexer",
3
- "version": "1.2.0",
3
+ "version": "1.2.2",
4
4
  "description": "Mastors Flexer — complete flexbox utility class system",
5
5
  "license": "MIT",
6
6
  "author": "Mastors Contributors",