0
# Material Feature Targeting
1

2
Material Feature Targeting provides infrastructure to allow CSS styles to be included or excluded categorically in Material Design Components Web (MDC Web). It enables developers to conditionally emit styles based on features like structure, animation, color, and typography through a systematic approach using Sass mixins and functions.
3

4
## Package Information
5

6
- **Package Name**: @material/feature-targeting
7
- **Package Type**: npm (Sass library)
8
- **Language**: Sass/SCSS
9
- **Installation**: `npm install @material/feature-targeting`
10

11
## Core Imports
12

13
Modern Sass modules (recommended):
14

15
```scss
16
@use "@material/feature-targeting";
17
```
18

19
Legacy import (deprecated):
20

21
```scss
22
@import "@material/feature-targeting/functions";
23
@import "@material/feature-targeting/mixins";
24
@import "@material/feature-targeting/variables";
25
```
26

27
Prefixed import pattern:
28

29
```scss
30
@import "@material/feature-targeting/functions.import";
31
@import "@material/feature-targeting/mixins.import";
32
@import "@material/feature-targeting/variables.import";
33
```
34

35
## Basic Usage
36

37
```scss
38
@use "@material/feature-targeting";
39

40
@mixin my-component-core-styles($query: feature-targeting.all()) {
41
  $feat-structure: feature-targeting.create-target($query, structure);
42
  $feat-color: feature-targeting.create-target($query, color);
43

44
  @include feature-targeting.targets($feat-structure) {
45
    display: block;
46
    padding: 16px;
47
  }
48

49
  @include feature-targeting.targets($feat-color) {
50
    color: blue;
51
    background-color: white;
52
  }
53
}
54

55
// Usage - include all styles (default)
56
@include my-component-core-styles;
57

58
// Usage - include only specific features
59
@include my-component-core-styles(structure);
60
@include my-component-core-styles(feature-targeting.any(color, typography));
61
@include my-component-core-styles(feature-targeting.without(animation));
62
```
63

64
## Architecture
65

66
Material Feature Targeting is built around three core concepts:
67

68
- **Features**: Cross-cutting categories of styles (structure, animation, color, typography)
69
- **Feature Queries**: Structures representing queries for features or combinations of features
70
- **Feature Targets**: Maps containing the targeted feature and current query, passed to the `targets` mixin
71

72
The system uses a query-based approach where styles are conditionally emitted based on feature matching logic.
73

74
## Capabilities
75

76
### Feature Target Creation
77

78
Creates feature targets from queries and targeted features for use with the `targets` mixin.
79

80
```scss { .api }
81
/**
82
 * Creates a feature target from the given feature query and targeted feature
83
 * @param $feature-query - A feature query (string or map)
84
 * @param $targeted-feature - The feature being targeted (string)
85
 * @returns Feature target map with query and target keys
86
 */
87
@function create-target($feature-query, $targeted-feature);
88
```
89

90
### Target Parsing
91

92
Parses feature targets to extract query information and available features.
93

94
```scss { .api }
95
/**
96
 * Parses a list of feature targets to produce a map containing the feature query and list of available features
97
 * @param $feature-targets - List of feature target maps
98
 * @returns Map with available and query keys
99
 */
100
@function parse-targets($feature-targets);
101
```
102

103
### Query Composition
104

105
Functions for composing complex feature queries using logical operators.
106

107
```scss { .api }
108
/**
109
 * Creates a feature query that is satisfied iff all of its sub-queries are satisfied
110
 * @param $feature-queries... - Variadic list of feature queries
111
 * @returns Query map with op: all and queries list
112
 */
113
@function all($feature-queries...);
114

115
/**
116
 * Creates a feature query that is satisfied iff any of its sub-queries are satisfied  
117
 * @param $feature-queries... - Variadic list of feature queries
118
 * @returns Query map with op: any and queries list
119
 */
120
@function any($feature-queries...);
121

122
/**
123
 * Creates a feature query that is satisfied iff its sub-query is not satisfied
124
 * @param $feature-query - A single feature query
125
 * @returns Query map with op: without and queries list
126
 */
127
@function without($feature-query);
128
```
129

130
### Conditional Style Emission
131

132
Mixin for conditionally emitting styles based on feature targets.
133

134
```scss { .api }
135
/**
136
 * Conditionalizes content to only be emitted if the given feature target(s) is/are queried
137
 * @param $feature-targets... - Variadic list of feature target maps
138
 * @content - Sass content block that will be conditionally emitted
139
 * @note Cannot be nested inside another targets mixin call
140
 */
141
@mixin targets($feature-targets...);
142
```
143

144
### Feature Constants
145

146
Pre-defined lists of supported features and query operators.
147

148
```scss { .api }
149
/**
150
 * List of all supported features
151
 * @type List
152
 * @value (structure, color, typography, animation)
153
 */
154
$all-features: (structure, color, typography, animation);
155

156
/**
157
 * List of all supported query operators
158
 * @type List  
159
 * @value (any, all, without)
160
 */
161
$all-query-operators: (any, all, without);
162
```
163

164
## Supported Features
165

166
The library supports four main feature categories:
167

168
- **`structure`** - All baseline styles that don't fit into any other category
169
- **`animation`** - Styles responsible for causing animations and transitions to occur
170
- **`color`** - Color-specific styles which rely on `mdc-theme` variables  
171
- **`typography`** - Typography-specific styles which rely on `mdc-typography`
172

173
## Usage Examples
174

175
**Basic Feature Targeting:**
176

177
```scss
178
@use "@material/feature-targeting";
179

180
@mixin button-styles($query: feature-targeting.all()) {
181
  $feat-structure: feature-targeting.create-target($query, structure);
182
  $feat-color: feature-targeting.create-target($query, color);
183
  $feat-animation: feature-targeting.create-target($query, animation);
184

185
  @include feature-targeting.targets($feat-structure) {
186
    display: inline-block;
187
    padding: 8px 16px;
188
    border: none;
189
    border-radius: 4px;
190
  }
191

192
  @include feature-targeting.targets($feat-color) {
193
    background-color: #1976d2;
194
    color: white;
195
  }
196

197
  @include feature-targeting.targets($feat-animation) {
198
    transition: background-color 0.2s ease;
199
    
200
    &:hover {
201
      background-color: #1565c0;
202
    }
203
  }
204
}
205

206
// Note: targets mixin cannot be nested
207
// This will cause an error:
208
// @include feature-targeting.targets($feat-structure) {
209
//   @include feature-targeting.targets($feat-color) { // ERROR!
210
//     color: red;
211
//   }
212
// }
213
```
214

215
**Query Composition:**
216

217
```scss
218
// Include multiple features
219
@include button-styles(feature-targeting.any(structure, color));
220

221
// Include all except animations
222
@include button-styles(feature-targeting.without(animation));
223

224
// Include all features (default)
225
@include button-styles(feature-targeting.all());
226

227
// Include only structure
228
@include button-styles(structure);
229
```
230

231
**Complex Queries:**
232

233
```scss
234
// Multiple exclusions
235
@include button-styles(
236
  feature-targeting.without(
237
    feature-targeting.any(animation, typography)
238
  )
239
);
240

241
// All features explicitly
242
@include button-styles(
243
  feature-targeting.all(structure, color, typography, animation)
244
);
245
```
246

247
## Legacy Import Patterns
248

249
For codebases still using `@import`, the library provides backward compatibility:
250

251
**Functions only (prefixed):**
252
```scss
253
@import "@material/feature-targeting/functions.import";
254

255
$target: mdc-feature-create-target(structure, structure);
256
$query: mdc-feature-all(structure, color);
257
```
258

259
**Mixins only (prefixed):**
260
```scss
261
@import "@material/feature-targeting/mixins.import";
262

263
@include mdc-feature-targets($target) {
264
  display: block;
265
}
266
```
267

268
**Variables only (prefixed):**
269
```scss
270
@import "@material/feature-targeting/variables.import";
271

272
$features: $mdc-feature-all-features;
273
$operators: $mdc-feature-all-query-operators;
274
```
275

276
**Legacy individual imports (deprecated):**
277
```scss
278
@import "@material/feature-targeting/functions";
279
@import "@material/feature-targeting/mixins";
280
@import "@material/feature-targeting/variables";
281

282
$target: create-target(structure, structure);
283
$query: all(structure, color);
284
@include targets($target) { display: block; }
285
```