0
# @react-native-community/eslint-plugin
1

2
ESLint plugin that enforces static analysis requirements for React Native platform color APIs. This plugin ensures that calls to `PlatformColor()` and `DynamicColorIOS()` use only literal arguments, enabling static analysis optimizations for color-related APIs in React Native applications.
3

4
## Package Information
5

6
- **Package Name**: @react-native-community/eslint-plugin
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev @react-native-community/eslint-plugin`
10

11
## Core Imports
12

13
The plugin is used in ESLint configuration rather than imported directly in code:
14

15
```json
16
{
17
  "plugins": ["@react-native-community"]
18
}
19
```
20

21
For programmatic access to rules:
22

23
```javascript
24
const { rules } = require("@react-native-community/eslint-plugin");
25
```
26

27
CommonJS:
28

29
```javascript
30
const plugin = require("@react-native-community/eslint-plugin");
31
const platformColorsRule = plugin.rules["platform-colors"];
32
```
33

34
## Basic Usage
35

36
Add the plugin to your ESLint configuration and enable the rule:
37

38
```json
39
{
40
  "plugins": ["@react-native-community"],
41
  "rules": {
42
    "@react-native-community/platform-colors": "error"
43
  }
44
}
45
```
46

47
The rule will then enforce proper usage of platform color APIs:
48

49
```javascript
50
// ✅ Valid - literal arguments
51
const color1 = PlatformColor('labelColor');
52
const color2 = PlatformColor('controlAccentColor', 'controlColor');
53
const color3 = DynamicColorIOS({light: 'black', dark: 'white'});
54

55
// ❌ Invalid - variable arguments not allowed
56
const colorName = 'labelColor';
57
const color4 = PlatformColor(colorName); // ESLint error
58

59
// ❌ Invalid - no arguments
60
const color5 = PlatformColor(); // ESLint error
61
```
62

63
## Capabilities
64

65
### Plugin Rules Export
66

67
The main plugin export providing access to all ESLint rules.
68

69
```javascript { .api }
70
/**
71
 * Main plugin export containing all ESLint rules
72
 */
73
interface ESLintPlugin {
74
  rules: {
75
    "platform-colors": ESLintRule;
76
  };
77
}
78
```
79

80
### Platform Colors Rule
81

82
ESLint rule that validates `PlatformColor()` and `DynamicColorIOS()` function calls to ensure they use literal arguments for static analysis.
83

84
```javascript { .api }
85
/**
86
 * ESLint rule for platform color validation
87
 */
88
interface ESLintRule {
89
  meta: RuleMeta;
90
  create: (context: ESLintContext) => RuleVisitor;
91
}
92

93
interface RuleMeta {
94
  type: "problem";
95
  docs: {
96
    description: string;
97
  };
98
  messages: {
99
    platformColorArgsLength: string;
100
    platformColorArgTypes: string;  
101
    dynamicColorIOSArg: string;
102
    dynamicColorIOSValue: string;
103
  };
104
  schema: [];
105
}
106

107
interface RuleVisitor {
108
  CallExpression: (node: CallExpressionNode) => void;
109
}
110
```
111

112
The rule enforces the following requirements:
113

114
- **PlatformColor()** must have at least one argument
115
- **PlatformColor()** arguments must all be literal values (strings, numbers, booleans)
116
- **DynamicColorIOS()** must take exactly one object expression argument
117
- **DynamicColorIOS()** object properties must have literal values or `PlatformColor()` calls
118

119
### Rule Messages
120

121
Error messages provided by the platform-colors rule for different validation failures.
122

123
```javascript { .api }
124
interface RuleMessages {
125
  /** Error when PlatformColor() is called with no arguments */
126
  platformColorArgsLength: "PlatformColor() must have at least one argument that is a literal.";
127
  
128
  /** Error when PlatformColor() arguments are not literals */
129
  platformColorArgTypes: "PlatformColor() every argument must be a literal.";
130
  
131
  /** Error when DynamicColorIOS() doesn't take a single object argument */
132
  dynamicColorIOSArg: "DynamicColorIOS() must take a single argument of type Object";
133
  
134
  /** Error when DynamicColorIOS() object properties are not literals or PlatformColor calls */
135
  dynamicColorIOSValue: "DynamicColorIOS() value must be either a literal or a PlatformColor() call.";
136
}
137
```
138

139
## Usage Examples
140

141
### ESLint Configuration
142

143
Basic ESLint configuration with the plugin:
144

145
```json
146
{
147
  "extends": ["@react-native-community"],
148
  "plugins": ["@react-native-community"],
149
  "rules": {
150
    "@react-native-community/platform-colors": "error"
151
  }
152
}
153
```
154

155
### Valid Platform Color Usage
156

157
Examples of platform color usage that pass validation:
158

159
```javascript
160
// Single platform color
161
const labelColor = PlatformColor('labelColor');
162

163
// Multiple fallback colors
164
const accentColor = PlatformColor('controlAccentColor', 'controlColor');
165

166
// Dynamic color with literals
167
const adaptiveColor = DynamicColorIOS({
168
  light: 'black',
169
  dark: 'white'
170
});
171

172
// Dynamic color with PlatformColor calls
173
const systemAdaptiveColor = DynamicColorIOS({
174
  light: PlatformColor('black'),
175
  dark: PlatformColor('white'),
176
  highContrastLight: PlatformColor('black'),
177
  highContrastDark: PlatformColor('white')
178
});
179
```
180

181
### Invalid Usage (ESLint Errors)
182

183
Examples that will trigger ESLint errors:
184

185
```javascript
186
// ❌ No arguments
187
const color1 = PlatformColor();
188

189
// ❌ Variable argument
190
const colorName = 'labelColor';
191
const color2 = PlatformColor(colorName);
192

193
// ❌ Non-object argument to DynamicColorIOS
194
const colorConfig = {light: 'black', dark: 'white'};
195
const color3 = DynamicColorIOS(colorConfig);
196

197
// ❌ Variable property values
198
const lightColor = 'black';
199
const color4 = DynamicColorIOS({
200
  light: lightColor,
201
  dark: 'white'
202
});
203
```
204

205
## Types
206

207
```javascript { .api }
208
/**
209
 * ESLint context object passed to rule create function
210
 */
211
interface ESLintContext {
212
  /** Report a rule violation */
213
  report(descriptor: {
214
    node: ASTNode;
215
    messageId: string;
216
  }): void;
217
}
218

219
/**
220
 * AST node representing a function call expression
221
 */
222
interface CallExpressionNode {
223
  type: "CallExpression";
224
  callee: {
225
    name: string;
226
  };
227
  arguments: ArgumentNode[];
228
}
229

230
/**
231
 * AST node representing function arguments
232
 */
233
interface ArgumentNode {
234
  type: "Literal" | "ObjectExpression" | string;
235
  properties?: PropertyNode[];
236
}
237

238
/**
239
 * AST node representing object properties
240
 */
241
interface PropertyNode {
242
  type: "Property";
243
  value: {
244
    type: "Literal" | "CallExpression" | string;
245
    callee?: {
246
      name: string;
247
    };
248
  };
249
}
250
```