Skip to content

Commit 6a12e1d

Browse files
aghontpiaghontpi
authored
Merge pull request #1 from aghontpi/feature/css-scoping
feat: Implement Optional CSS Scoping
2 parents 3631f35 + 27bc961 commit 6a12e1d

15 files changed

Lines changed: 250 additions & 130 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,20 @@ Import the `style.scss` file in your main SCSS file:
8787
@import 'minimal-css-utility/scss/style.scss';
8888
```
8989

90+
### CSS Scoping
91+
92+
You can scope all the generated CSS under a specific parent selector (e.g., `.my-app`) by configuring the `$css-scope` variable. Since this project uses Sass modules, you need to configure the variables module before loading the styles.
93+
94+
```scss
95+
// Configure the variables module
96+
@use 'minimal-css-utility/scss/abstracts/variables' with (
97+
$css-scope: '.my-app'
98+
);
99+
100+
// Load the styles
101+
@use 'minimal-css-utility/scss/style';
102+
```
103+
90104
## Building from source
91105

92106
If you want to build the CSS from the source SCSS files, you can do so by following these steps:

‎docs/.vitepress/config.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ export default {
1818
{ text: 'Introduction', link: '/getting-started/introduction' },
1919
{ text: 'Breakpoints', link: '/getting-started/breakpoints' },
2020
{ text: 'CSS Reset', link: '/getting-started/reset' },
21+
{ text: 'CSS Scoping', link: '/getting-started/scoping' },
2122
],
2223
},
2324
{

‎docs/getting-started/scoping.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# CSS Scoping
2+
3+
Minimal CSS Utility provides an option to scope all generated styles under a specific parent selector. This is particularly useful when you are using the library in an embedded context (e.g., a widget or a micro-frontend) and want to avoid style conflicts with the host application.
4+
5+
## Configuration
6+
7+
To enable scoping, you need to configure the `$css-scope` variable in the `abstracts/variables` module.
8+
9+
### Using Sass Modules
10+
11+
Since this library uses Sass modules, you should use the `@use ... with` syntax to configure the variable.
12+
13+
```scss
14+
// main.scss
15+
16+
// 1. Configure the variables module with your desired scope selector
17+
@use 'minimal-css-utility/scss/abstracts/variables' with (
18+
$css-scope: '.my-custom-scope'
19+
);
20+
21+
// 2. Load the styles
22+
@use 'minimal-css-utility/scss/style';
23+
```
24+
25+
### Result
26+
27+
The above configuration will wrap all generated CSS rules (including reset, grid, and utilities) inside the `.my-custom-scope` selector.
28+
29+
```css
30+
.my-custom-scope {
31+
/* Reset styles */
32+
margin: 0;
33+
padding: 0;
34+
/* ... */
35+
}
36+
37+
.my-custom-scope .row {
38+
display: flex;
39+
/* ... */
40+
}
41+
42+
.my-custom-scope .text-center {
43+
text-align: center !important;
44+
}
45+
```
46+
47+
## HTML Usage
48+
49+
In your HTML, simply wrap your application content with the configured class.
50+
51+
```html
52+
<div class="my-custom-scope">
53+
<div class="container">
54+
<h1 class="text-center">Scoped Content</h1>
55+
<!-- ... -->
56+
</div>
57+
</div>
58+
```
59+
60+
## Framework Examples
61+
62+
### React
63+
64+
In a React application, you can import the configured SCSS file in your root component (e.g., `App.jsx`) and wrap your application with the scope class.
65+
66+
**1. Create a SCSS file (e.g., `App.scss`)**
67+
68+
```scss
69+
// App.scss
70+
@use 'minimal-css-utility/scss/abstracts/variables' with (
71+
$css-scope: '.my-react-app'
72+
);
73+
@use 'minimal-css-utility/scss/style';
74+
```
75+
76+
**2. Import and use in `App.jsx`**
77+
78+
```jsx
79+
// App.jsx
80+
import './App.scss';
81+
82+
function App() {
83+
return (
84+
<div className="my-react-app">
85+
<div className="container">
86+
<h1>Hello React!</h1>
87+
{/* Your app components */}
88+
</div>
89+
</div>
90+
);
91+
}
92+
93+
export default App;
94+
```

‎scss/abstracts/_mixins.scss‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,20 @@
22
@use 'variables' as v;
33

44
@mixin generate-classes($infix) {
5-
// --- Display ---
5+
// --- Display Utilities ---
66
@each $value in v.$displays {
77
.d#{$infix}-#{$value} {
88
display: $value !important;
99
}
1010
}
1111

12-
// --- Flex Alignment ---
12+
// --- Flex Alignment Utilities ---
1313
@each $key, $value in v.$align-items {
1414
.align-items#{$infix}-#{$key} {
1515
align-items: $value !important;
1616
}
1717

18-
// --- Align Self ---
18+
// --- Align Self Utilities ---
1919
.align-self#{$infix}-#{$key} {
2020
align-self: $value !important;
2121
}
@@ -41,7 +41,7 @@
4141
flex-shrink: 1 !important;
4242
}
4343

44-
// --- Spacing (Margin & Padding) ---
44+
// --- Spacing Utilities (Margin & Padding) ---
4545
@each $key, $value in v.$spacers {
4646
// Margin
4747
.m#{$infix}-#{$key} {
@@ -108,17 +108,15 @@
108108

109109
@each $key, $value in v.$spacers {
110110
@if $key != 'auto' {
111-
// .gap-1, .gap-lg-3, etc.
111+
// Gap Utilities
112112
.gap#{$infix}-#{$key} {
113113
gap: $value !important;
114114
}
115115

116-
// .row-gap-1, .row-gap-lg-3, etc.
117116
.row-gap#{$infix}-#{$key} {
118117
row-gap: $value !important;
119118
}
120119

121-
// .col-gap-1, .col-gap-lg-3, etc.
122120
.col-gap#{$infix}-#{$key} {
123121
column-gap: $value !important;
124122
}

‎scss/abstracts/_variables.scss‎

Lines changed: 44 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,20 @@
1-
// Breakpoints
1+
// --- Breakpoints ---
2+
// Define the breakpoints for responsive design.
23
$breakpoint-xl: 1200px;
34
$breakpoint-xxl: 1440px;
45
$container-max-width: 1200px;
56

6-
// Grid
7+
// --- CSS Scoping Configuration ---
8+
// Set this to a selector (e.g., '.my-app') to scope all styles under that selector.
9+
// Leave as null for global styles.
10+
$css-scope: null !default;
11+
12+
// --- Grid System Configuration ---
713
$grid-columns: 12;
8-
$grid-gutter-width: 1.5rem; // ~24px, the space BETWEEN columns
14+
$grid-gutter-width: 1.5rem; // Space between columns (~24px)
915

10-
// A Sass Map to define all breakpoints we want to generate classes for
11-
// (xs, sm, md, lg, xl, xxl). 'xs' (0px) is the mobile-first default.
16+
// Map of breakpoints used to generate responsive utility classes.
17+
// 'xs' (0px) is the default mobile-first breakpoint.
1218
$grid-breakpoints: (
1319
xs: 0,
1420
sm: 576px,
@@ -18,26 +24,25 @@ $grid-breakpoints: (
1824
xxl: $breakpoint-xxl,
1925
);
2026

21-
// Spacing map (for m-1, p-3, mx-auto, etc.)
27+
// --- Spacing Configuration ---
28+
// Map of spacing values used for margin and padding utilities.
2229
$spacers: (
2330
0: 0,
24-
1: 0.25rem,
25-
// 4px
26-
2: 0.5rem,
27-
// 8px
28-
3: 1rem,
29-
// 16px
30-
4: 1.5rem,
31-
// 24px
32-
5: 3rem,
33-
// 48px
31+
1: 0.25rem, // 4px
32+
2: 0.5rem, // 8px
33+
3: 1rem, // 16px
34+
4: 1.5rem, // 24px
35+
5: 3rem, // 48px
3436
auto: auto,
3537
);
3638

37-
// Display properties (for d-flex, d-none, etc.)
39+
// --- Display Configuration ---
40+
// List of display property values.
3841
$displays: (none, block, flex, inline-flex, grid, inline-block);
3942

40-
// Flex alignment properties (for align-items-center, etc.)
43+
// --- Flexbox Configuration ---
44+
45+
// Map of flexbox alignment values (align-items).
4146
$align-items: (
4247
start: flex-start,
4348
end: flex-end,
@@ -46,7 +51,7 @@ $align-items: (
4651
stretch: stretch,
4752
);
4853

49-
// Justify content properties (for justify-content-between, etc.)
54+
// Map of flexbox justification values (justify-content).
5055
$justify-content: (
5156
start: flex-start,
5257
end: flex-end,
@@ -56,42 +61,31 @@ $justify-content: (
5661
evenly: space-evenly,
5762
);
5863

59-
// Flex direction properties (for flex-column, etc.)
64+
// Map of flexbox direction values.
6065
$flex-direction: (
6166
row: row,
6267
row-reverse: row-reverse,
6368
column: column,
6469
column-reverse: column-reverse,
6570
);
6671

67-
// --- Typography Maps ---
72+
// --- Typography Configuration ---
6873

69-
// 1. Font Size "Tokens"
70-
// Defines all the font sizes available in the system.
74+
// Map of available font sizes.
7175
$font-sizes: (
72-
xs: 0.75rem,
73-
// 12px
74-
sm: 0.875rem,
75-
// 14px
76-
base: 1rem,
77-
// 16px
78-
lg: 1.125rem,
79-
// 18px
80-
xl: 1.25rem,
81-
// 20px
82-
'2xl': 1.5rem,
83-
// 24px
84-
'3xl': 1.875rem,
85-
// 30px
86-
'4xl': 2.25rem,
87-
// 36px
88-
'5xl': 3rem,
89-
// 48px
90-
'6xl': 4rem, // 64px
76+
xs: 0.75rem, // 12px
77+
sm: 0.875rem, // 14px
78+
base: 1rem, // 16px
79+
lg: 1.125rem, // 18px
80+
xl: 1.25rem, // 20px
81+
'2xl': 1.5rem, // 24px
82+
'3xl': 1.875rem,// 30px
83+
'4xl': 2.25rem, // 36px
84+
'5xl': 3rem, // 48px
85+
'6xl': 4rem, // 64px
9186
);
9287

93-
// 2. Heading Element Styles
94-
// Maps elements (h1-h6) to the size keys from the $font-sizes map.
88+
// Map linking heading elements to font sizes.
9589
$heading-sizes: (
9690
h1: '5xl',
9791
h2: '4xl',
@@ -101,7 +95,7 @@ $heading-sizes: (
10195
h6: 'lg',
10296
);
10397

104-
// 3. Font Weights
98+
// Map of font weights.
10599
$font-weights: (
106100
light: 300,
107101
normal: 400,
@@ -111,7 +105,7 @@ $font-weights: (
111105
black: 900,
112106
);
113107

114-
// --- Border and Border Radius ---
108+
// --- Border Configuration ---
115109
$border-width: 1px;
116110
$border-color: #dee2e6;
117111

@@ -123,12 +117,12 @@ $border-radius: (
123117
circle: 50%,
124118
);
125119

126-
// --- Shadows ---
120+
// --- Box Shadow Configuration ---
127121
$box-shadow-sm: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
128122
$box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
129123
$box-shadow-lg: 0 1rem 3rem rgba(0, 0, 0, 0.175);
130124

131-
// --- Opacity ---
125+
// --- Opacity Levels ---
132126
$opacities: (
133127
0: 0,
134128
25: 0.25,
@@ -137,7 +131,7 @@ $opacities: (
137131
100: 1,
138132
);
139133

140-
// --- Positioning ---
134+
// --- Positioning Configuration ---
141135
$positions: (static, relative, absolute, fixed, sticky);
142136

143137
$position-values: (
@@ -146,5 +140,5 @@ $position-values: (
146140
100: 100%,
147141
);
148142

149-
// --- Text Alignment ---
143+
// --- Text Alignment Values ---
150144
$text-alignments: (start, end, left, right, center, justify);

‎scss/base/_grid-base.scss‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,21 @@
22

33
.row {
44
display: flex;
5-
flex-wrap: wrap; // Allows columns to wrap to the next line
5+
flex-wrap: wrap; // Enable flex wrapping for multi-line columns.
66

7-
// The "negative margin" trick:
8-
// This pulls the row's edges outward to perfectly align
9-
// the content of the first and last columns with the .container.
7+
// Apply negative margins to align row content with the container edges.
108
margin-left: calc(var(--grid-gutter-width) / -2);
119
margin-right: calc(var(--grid-gutter-width) / -2);
1210
}
1311

1412
[class^='col-'] {
15-
// This is the gutter padding on the sides of each column
13+
// Apply gutter padding to columns.
1614
padding-left: calc(var(--grid-gutter-width) / 2);
1715
padding-right: calc(var(--grid-gutter-width) / 2);
1816

19-
// Ensures padding doesn't affect the width calculation
17+
// Use border-box sizing for consistent width calculations.
2018
box-sizing: border-box;
2119

22-
// Mobile-first: default to 100% width
20+
// Default to full width for mobile-first responsiveness.
2321
width: 100%;
2422
}

‎scss/reset.scss‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,7 @@ table {
127127
border-spacing: 0;
128128
}
129129

130+
// Apply border-box sizing to all elements.
130131
* {
131132
box-sizing: border-box;
132133
}

0 commit comments

Comments
 (0)