Skip to content

Commit 42e2a8c

Browse files
mdomdo
authored
Make spacing docs less annoying to update (twbs#42454)
1 parent ea71b3b commit 42e2a8c

7 files changed

Lines changed: 221 additions & 241 deletions

File tree

‎scss/_utilities.scss‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -471,6 +471,7 @@ $utilities: map.merge(
471471
// scss-docs-end utils-flex
472472
// Margin utilities
473473
// scss-docs-start utils-spacing
474+
// scss-docs-start utils-margin
474475
"margin": (
475476
responsive: true,
476477
property: margin,
@@ -513,7 +514,9 @@ $utilities: map.merge(
513514
class: ms,
514515
values: map-merge-multiple($spacers, $negative-spacers, (auto: auto))
515516
),
517+
// scss-docs-end utils-margin
516518
// Padding utilities
519+
// scss-docs-start utils-padding
517520
"padding": (
518521
responsive: true,
519522
property: padding,
@@ -556,7 +559,9 @@ $utilities: map.merge(
556559
class: ps,
557560
values: $spacers
558561
),
562+
// scss-docs-end utils-padding
559563
// Gap utility
564+
// scss-docs-start utils-gap
560565
"gap": (
561566
responsive: true,
562567
property: gap,
@@ -575,6 +580,7 @@ $utilities: map.merge(
575580
class: column-gap,
576581
values: $spacers
577582
),
583+
// scss-docs-end utils-gap
578584
// scss-docs-end utils-spacing
579585
// scss-docs-start utils-space
580586
"space-x": (

‎site/src/components/shortcodes/SpacingNotation.astro‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
interface PropertyItem {
3+
/**
4+
* The class abbreviation, e.g. `p`, `m`, `gap`, `row-gap`.
5+
*/
6+
class: string
7+
/**
8+
* The CSS property the class sets, e.g. `padding`, `margin`, `gap`.
9+
*/
10+
property: string
11+
}
12+
13+
interface SideItem {
14+
/**
15+
* The side abbreviation, e.g. `t`, `b`, `x`, `y`. Use `blank` to render the
16+
* "blank" (all sides) entry without code formatting.
17+
*/
18+
abbr: string
19+
/**
20+
* The trailing description rendered after the abbreviation. May contain HTML
21+
* (e.g. `<code>` spans) and is injected as-is.
22+
*/
23+
desc: string
24+
}
25+
26+
interface Props {
27+
/**
28+
* The spacing noun used throughout the copy, e.g. `gap`, `padding`, `margin`.
29+
*/
30+
noun: string
31+
/**
32+
* The class-name format, e.g. `{property}-{size}` or `{property}{sides}-{size}`.
33+
*/
34+
format: string
35+
/**
36+
* The "Where *property* is" list entries.
37+
*/
38+
properties: PropertyItem[]
39+
/**
40+
* The optional "Where *sides* is one of" list entries. Omit for utilities
41+
* without sides (e.g. gap).
42+
*/
43+
sides?: SideItem[]
44+
/**
45+
* Appends the `auto` entry to the size list (margin only).
46+
* @default false
47+
*/
48+
includeAuto?: boolean
49+
}
50+
51+
const { noun, format, properties, sides, includeAuto = false } = Astro.props
52+
53+
const capitalizedNoun = noun.charAt(0).toUpperCase() + noun.slice(1)
54+
55+
// Multipliers for sizes `1` through `9`, mirroring the default `$spacers` map.
56+
const sizeValues = [
57+
'$spacer * .25',
58+
'$spacer * .5',
59+
'$spacer * .75',
60+
'$spacer',
61+
'$spacer * 1.25',
62+
'$spacer * 1.5',
63+
'$spacer * 2',
64+
'$spacer * 2.5',
65+
'$spacer * 3'
66+
]
67+
---
68+
69+
<p>
70+
{capitalizedNoun} utilities that apply to all breakpoints, from <code>xs</code> to <code>2xl</code>, have no breakpoint
71+
prefix in them. This is because those classes are applied from <code>min-width: 0</code> and up, and thus are not
72+
bound by a media query. The remaining breakpoints, however, do include a breakpoint prefix.
73+
</p>
74+
75+
<p>
76+
The classes are named using the format <code>{format}</code> for <code>xs</code> and{' '}
77+
<code>{`{breakpoint}:${format}`}</code> for <code>sm</code>, <code>md</code>, <code>lg</code>, <code>xl</code>, and{' '}
78+
<code>2xl</code>.
79+
</p>
80+
81+
<p>Where <em>property</em> {properties.length > 1 ? 'is one of' : 'is'}:</p>
82+
83+
<ul>
84+
{
85+
properties.map((item) => (
86+
<li>
87+
<code>{item.class}</code> - for classes that set <code>{item.property}</code>
88+
</li>
89+
))
90+
}
91+
</ul>
92+
93+
{
94+
sides && (
95+
<Fragment>
96+
<p>
97+
Where <em>sides</em> is one of:
98+
</p>
99+
<ul>
100+
{sides.map((side) => (
101+
<li>
102+
{side.abbr === 'blank' ? 'blank' : <code>{side.abbr}</code>} - <Fragment set:html={side.desc} />
103+
</li>
104+
))}
105+
</ul>
106+
</Fragment>
107+
)
108+
}
109+
110+
<p>Where <em>size</em> is one of:</p>
111+
112+
<ul>
113+
<li>
114+
<code>0</code> - for classes that eliminate the <code>{noun}</code> by setting it to <code>0</code>
115+
</li>
116+
{
117+
sizeValues.map((value, index) => (
118+
<li>
119+
<code>{index + 1}</code> - (by default) for classes that set the <code>{noun}</code> to <code>{value}</code>
120+
</li>
121+
))
122+
}
123+
{
124+
includeAuto && (
125+
<li>
126+
<code>auto</code> - for classes that set the <code>{noun}</code> to auto
127+
</li>
128+
)
129+
}
130+
</ul>
131+
132+
<p>(You can add more sizes by adding entries to the <code>$spacers</code> Sass map variable.)</p>

‎site/src/components/shortcodes/SpacingResponsive.astro‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
import { getData } from '@libs/data'
3+
4+
interface Props {
5+
/**
6+
* The class abbreviations to document, one `<ul>` per entry. For example
7+
* `['gap', 'row-gap', 'column-gap']` or `['p']`.
8+
*/
9+
classes: string[]
10+
/**
11+
* Appends `and .{abbr}{class}-auto` to each entry (margin only).
12+
* @default false
13+
*/
14+
includeAuto?: boolean
15+
}
16+
17+
const { classes, includeAuto = false } = Astro.props
18+
19+
const breakpoints = getData('breakpoints')
20+
---
21+
22+
{
23+
classes.map((className) => (
24+
<ul>
25+
{breakpoints.map((breakpoint) => (
26+
<li>
27+
{/* prettier-ignore */}
28+
<code>.{breakpoint.abbr}{className}-0</code> through <code>.{breakpoint.abbr}{className}-9</code>
29+
{includeAuto && (
30+
<Fragment> and <code>.{breakpoint.abbr}{className}-auto</code></Fragment>
31+
)}
32+
</li>
33+
))}
34+
</ul>
35+
))
36+
}

‎site/src/content/docs/utilities/gap.mdx‎

Lines changed: 11 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,6 @@ utility:
99
- column-gap
1010
---
1111

12-
import { getData } from '@libs/data'
13-
1412
## Overview
1513

1614
Use gap utilities to control the space between children in flexbox and grid layouts. Gap utilities are built from a default Sass map ranging from `0` to `3rem` (`.gap-0` through `.gap-9`). Use utilities like `.gap-3` and `.gap-5` to control the gap between all children:
@@ -36,30 +34,15 @@ Use gap utilities to control the space between children in flexbox and grid layo
3634

3735
## Notation
3836

39-
Gap utilities that apply to all breakpoints, from `xs` to `2xl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation.
40-
41-
The classes are named using the format `{property}-{size}` for `xs` and `{breakpoint}:{property}-{size}` for `sm`, `md`, `lg`, `xl`, and `2xl`.
42-
43-
Where *property* is one of:
44-
45-
- `gap` - for classes that set `gap`
46-
- `row-gap` - for classes that set `row-gap`
47-
- `column-gap` - for classes that set `column-gap`
48-
49-
Where *size* is one of:
50-
51-
- `0` - for classes that eliminate the `gap` by setting it to `0`
52-
- `1` - (by default) for classes that set the `gap` to `$spacer * .25`
53-
- `2` - (by default) for classes that set the `gap` to `$spacer * .5`
54-
- `3` - (by default) for classes that set the `gap` to `$spacer * .75`
55-
- `4` - (by default) for classes that set the `gap` to `$spacer`
56-
- `5` - (by default) for classes that set the `gap` to `$spacer * 1.25`
57-
- `6` - (by default) for classes that set the `gap` to `$spacer * 1.5`
58-
- `7` - (by default) for classes that set the `gap` to `$spacer * 2`
59-
- `8` - (by default) for classes that set the `gap` to `$spacer * 2.5`
60-
- `9` - (by default) for classes that set the `gap` to `$spacer * 3`
61-
62-
(You can add more sizes by adding entries to the `$spacers` Sass map variable.)
37+
<SpacingNotation
38+
noun="gap"
39+
format="{property}-{size}"
40+
properties={[
41+
{ class: 'gap', property: 'gap' },
42+
{ class: 'row-gap', property: 'row-gap' },
43+
{ class: 'column-gap', property: 'column-gap' }
44+
]}
45+
/>
6346

6447
## Examples
6548

@@ -155,53 +138,12 @@ You can also use `row-gap` and `column-gap` utilities with flexbox layouts that
155138

156139
All gap utilities are responsive and include all breakpoints.
157140

158-
<ul>
159-
{getData('breakpoints').map((breakpoint) => {
160-
return (
161-
<li><code>.{breakpoint.abbr}gap-0</code> through <code>.{breakpoint.abbr}gap-9</code></li>
162-
)
163-
})}
164-
</ul>
165-
166-
<ul>
167-
{getData('breakpoints').map((breakpoint) => {
168-
return (
169-
<li><code>.{breakpoint.abbr}row-gap-0</code> through <code>.{breakpoint.abbr}row-gap-9</code></li>
170-
)
171-
})}
172-
</ul>
173-
174-
<ul>
175-
{getData('breakpoints').map((breakpoint) => {
176-
return (
177-
<li><code>.{breakpoint.abbr}column-gap-0</code> through <code>.{breakpoint.abbr}column-gap-9</code></li>
178-
)
179-
})}
180-
</ul>
141+
<SpacingResponsive classes={['gap', 'row-gap', 'column-gap']} />
181142

182143
## CSS
183144

184145
### Sass utilities API
185146

186147
Gap utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]])
187148

188-
```scss
189-
"gap": (
190-
responsive: true,
191-
property: gap,
192-
class: gap,
193-
values: $spacers
194-
),
195-
"row-gap": (
196-
responsive: true,
197-
property: row-gap,
198-
class: row-gap,
199-
values: $spacers
200-
),
201-
"column-gap": (
202-
responsive: true,
203-
property: column-gap,
204-
class: column-gap,
205-
values: $spacers
206-
),
207-
```
149+
<ScssDocs name="utils-gap" file="scss/_utilities.scss" />

0 commit comments

Comments
 (0)