0
# Utility Functions
1

2
Helper functions for working with typography styles, measurements, and style validation. These functions provide programmatic access to typography data and enable dynamic style generation and validation.
3

4
## Capabilities
5

6
### Measurement Conversion
7

8
Functions for converting between different measurement units, particularly useful for responsive design and custom calculations.
9

10
```scss { .api }
11
/**
12
 * Converts pixel values to rem units based on 16px base
13
 * @param $px - Pixel value to convert (number with px unit)
14
 * @returns Length value in rem units
15
 * @note Supports CSS custom properties as input
16
 */
17
@function px-to-rem($px): length;
18
```
19

20
**Usage Examples:**
21

22
```scss
23
@use "@material/typography";
24

25
.custom-text {
26
  font-size: typography.px-to-rem(18px);    // Result: 1.125rem
27
  margin-bottom: typography.px-to-rem(24px); // Result: 1.5rem
28
  line-height: typography.px-to-rem(28px);   // Result: 1.75rem
29
}
30

31
// Works with variables
32
$custom-size: 20px;
33
.larger-text {
34
  font-size: typography.px-to-rem($custom-size); // Result: 1.25rem
35
}
36

37
// Handles CSS custom properties
38
.themed-text {
39
  font-size: typography.px-to-rem(var(--custom-font-size, 16px));
40
}
41
```
42

43
### Style Validation
44

45
Functions for validating typography style names and working with the available style set.
46

47
```scss { .api }
48
/**
49
 * Checks if a given style name is a valid typography style
50
 * @param $style - Style name to validate (string)
51
 * @returns Boolean indicating if style exists
52
 */
53
@function is-typography-style($style): boolean;
54

55
/**
56
 * Returns a list of all available typography style names
57
 * @returns List of all typography style names
58
 */
59
@function get-typography-styles(): list;
60
```
61

62
**Usage Examples:**
63

64
```scss
65
@use "@material/typography";
66

67
// Validate style before using
68
@if typography.is-typography-style(headline1) {
69
  .valid-headline {
70
    @include typography.typography(headline1);
71
  }
72
}
73

74
// Check invalid style
75
@if not typography.is-typography-style(invalid-style) {
76
  @warn "invalid-style is not a valid typography style";
77
}
78

79
// Get all available styles
80
$all-styles: typography.get-typography-styles();
81
// Result: (headline1, headline2, headline3, headline4, headline5, headline6, subtitle1, subtitle2, body1, body2, caption, button, overline)
82

83
// Generate classes for all styles dynamically
84
@each $style in typography.get-typography-styles() {
85
  .custom-#{$style} {
86
    @include typography.typography($style);
87
    margin-bottom: 16px;
88
  }
89
}
90
```
91

92
### Property Access Functions
93

94
Functions for extracting specific typography properties from style definitions.
95

96
```scss { .api }
97
/**
98
 * Gets the font-family for a typography style
99
 * @param $typography - Typography style name (string)
100
 * @returns Font family value for the style
101
 */
102
@function get-font($typography): string;
103

104
/**
105
 * Gets the line-height for a typography style  
106
 * @param $typography - Typography style name (string)
107
 * @returns Line height value for the style
108
 */
109
@function get-line-height($typography): length;
110

111
/**
112
 * Gets the font-size for a typography style
113
 * @param $typography - Typography style name (string)  
114
 * @returns Font size value for the style
115
 */
116
@function get-size($typography): length;
117

118
/**
119
 * Gets the font-weight for a typography style
120
 * @param $typography - Typography style name (string)
121
 * @returns Font weight value for the style  
122
 */
123
@function get-weight($typography): number;
124

125
/**
126
 * Gets the letter-spacing for a typography style
127
 * @param $typography - Typography style name (string)
128
 * @returns Letter spacing value for the style
129
 */
130
@function get-tracking($typography): length;
131
```
132

133
**Usage Examples:**
134

135
```scss
136
@use "@material/typography";
137

138
// Extract individual properties
139
.custom-heading {
140
  font-family: typography.get-font(headline2);        // "Roboto, sans-serif"
141
  font-size: typography.get-size(headline2);          // 3.75rem
142
  font-weight: typography.get-weight(headline2);      // 300
143
  line-height: typography.get-line-height(headline2); // 3.75rem
144
  letter-spacing: typography.get-tracking(headline2); // -0.0083333333em
145
  
146
  // Add custom properties
147
  color: #1976d2;
148
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
149
}
150

151
// Mix properties from different styles
152
.hybrid-style {
153
  font-size: typography.get-size(headline4);        // Large size
154
  line-height: typography.get-line-height(body1);   // Comfortable line height
155
  font-weight: typography.get-weight(subtitle1);    // Medium emphasis
156
  letter-spacing: typography.get-tracking(button);  // Spacious tracking
157
}
158

159
// Responsive typography using functions
160
.responsive-text {
161
  font-size: typography.get-size(body2);          // Mobile: smaller
162
  line-height: typography.get-line-height(body2);
163
  
164
  @media (min-width: 600px) {
165
    font-size: typography.get-size(body1);        // Tablet+: larger
166
    line-height: typography.get-line-height(body1);
167
  }
168
}
169
```
170

171
### Advanced Usage Patterns
172

173
**Dynamic Style Generation:**
174

175
```scss
176
@use "@material/typography";
177
@use "sass:map";
178
@use "sass:list";
179

180
// Generate utility classes for each style
181
@each $style in typography.get-typography-styles() {
182
  .u-font-size-#{$style} {
183
    font-size: typography.get-size($style) !important;
184
  }
185
  
186
  .u-font-weight-#{$style} {
187
    font-weight: typography.get-weight($style) !important;
188
  }
189
  
190
  .u-line-height-#{$style} {
191
    line-height: typography.get-line-height($style) !important;
192
  }
193
}
194
```
195

196
**Style Comparison and Validation:**
197

198
```scss
199
@use "@material/typography";
200

201
// Create a mixin that validates and applies styles
202
@mixin safe-typography($style) {
203
  @if typography.is-typography-style($style) {
204
    @include typography.typography($style);
205
  } @else {
206
    @error "Invalid typography style: #{$style}. Available styles: #{typography.get-typography-styles()}";
207
  }
208
}
209

210
// Usage
211
.safe-heading {
212
  @include safe-typography(headline1); // Works
213
  // @include safe-typography(invalid);   // Throws error
214
}
215
```
216

217
**Custom Typography Scale:**
218

219
```scss
220
@use "@material/typography";
221
@use "sass:math";
222

223
// Create a custom scale based on existing styles
224
@function create-custom-scale($base-style, $ratio: 1.25) {
225
  $base-size: typography.get-size($base-style);
226
  $base-weight: typography.get-weight($base-style);
227
  $base-line-height: typography.get-line-height($base-style);
228
  
229
  @return (
230
    small: (
231
      font-size: math.div($base-size, $ratio),
232
      font-weight: $base-weight,
233
      line-height: math.div($base-line-height, $ratio)
234
    ),
235
    base: (
236
      font-size: $base-size,
237
      font-weight: $base-weight, 
238
      line-height: $base-line-height
239
    ),
240
    large: (
241
      font-size: $base-size * $ratio,
242
      font-weight: $base-weight,
243
      line-height: $base-line-height * $ratio
244
    )
245
  );
246
}
247

248
$custom-scale: create-custom-scale(body1, 1.2);
249

250
.small-text {
251
  font-size: map.get($custom-scale, small, font-size);
252
  line-height: map.get($custom-scale, small, line-height);
253
}
254
```
255

256
**Typography Inspector (Development Helper):**
257

258
```scss
259
@use "@material/typography";
260

261
// Debug mixin to show typography information
262
@mixin typography-debug($style) {
263
  @if typography.is-typography-style($style) {
264
    &::before {
265
      content: "Style: #{$style}, Size: #{typography.get-size($style)}, Weight: #{typography.get-weight($style)}, Line Height: #{typography.get-line-height($style)}";
266
      display: block;
267
      font-size: 12px;
268
      color: #666;
269
      background: #f0f0f0;
270
      padding: 4px 8px;
271
      margin-bottom: 8px;
272
      font-family: monospace;
273
    }
274
  }
275
  
276
  @include typography.typography($style);
277
}
278

279
// Usage during development
280
.debug-headline {
281
  @include typography-debug(headline1);
282
}
283
```
284

285
**Responsive Typography Helper:**
286

287
```scss
288
@use "@material/typography";
289

290
// Helper function for responsive typography
291
@function responsive-type-size($mobile-style, $desktop-style, $breakpoint: 600px) {
292
  @return clamp(
293
    #{typography.get-size($mobile-style)},
294
    4vw,
295
    #{typography.get-size($desktop-style)}
296
  );
297
}
298

299
.fluid-heading {
300
  font-size: responsive-type-size(headline6, headline2);
301
  font-weight: typography.get-weight(headline4);
302
  line-height: 1.2;
303
}
304
```
305

306
## Function Reference Summary
307

308
| Function | Purpose | Return Type | Example |
309
|----------|---------|-------------|---------|
310
| `px-to-rem($px)` | Convert pixels to rem | length | `1.125rem` |
311
| `is-typography-style($style)` | Validate style name | boolean | `true` |
312
| `get-typography-styles()` | List all styles | list | `(headline1, body1, ...)` |
313
| `get-font($typography)` | Get font-family | string | `"Roboto, sans-serif"` |
314
| `get-size($typography)` | Get font-size | length | `1rem` |
315
| `get-weight($typography)` | Get font-weight | number | `400` |
316
| `get-line-height($typography)` | Get line-height | length | `1.5rem` |
317
| `get-tracking($typography)` | Get letter-spacing | length | `0.01em` |