@allxsmith/eslint-plugin-bestax 0.0.0-development → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -24,6 +24,73 @@ export function collectImport(node, into) {
24
24
  // A default import is not a thing this package has; ignore it.
25
25
  }
26
26
  }
27
+ /**
28
+ * Record the library's bindings from a CommonJS `require`.
29
+ *
30
+ * The preset matches `.cjs`, and flat config parses those as `sourceType:
31
+ * 'commonjs'` where `import` is a syntax error — so without this every rule
32
+ * was permanently silent on exactly the JavaScript projects the README sells
33
+ * the plugin to. A CJS `.js` file in a `"type": "commonjs"` package is the
34
+ * same shape.
35
+ *
36
+ * const { Box } = require('@allxsmith/bestax-bulma'); → named
37
+ * const { Box: MyBox } = require(…); → aliased
38
+ * const B = require(…); → namespace
39
+ */
40
+ /**
41
+ * Does this binding pattern bind `name` anywhere inside it?
42
+ *
43
+ * A shadow does not have to be a plain identifier: `const { require } = shim`
44
+ * and `const [require] = shims` bind the name just as well, and the first
45
+ * version of the shadow guard read only `id.name` and missed both.
46
+ */
47
+ export function patternBinds(pattern, name) {
48
+ if (!pattern || typeof pattern !== 'object')
49
+ return false;
50
+ switch (pattern.type) {
51
+ case 'Identifier':
52
+ return pattern.name === name;
53
+ case 'ObjectPattern':
54
+ return (pattern.properties ?? []).some((prop) => prop?.type === 'RestElement'
55
+ ? patternBinds(prop.argument, name)
56
+ : patternBinds(prop?.value, name));
57
+ case 'ArrayPattern':
58
+ return (pattern.elements ?? []).some((el) => patternBinds(el, name));
59
+ case 'AssignmentPattern':
60
+ return patternBinds(pattern.left, name);
61
+ case 'RestElement':
62
+ return patternBinds(pattern.argument, name);
63
+ default:
64
+ return false;
65
+ }
66
+ }
67
+ export function isLibraryRequire(declarator) {
68
+ const init = declarator?.init;
69
+ return (init?.type === 'CallExpression' &&
70
+ init.callee?.name === 'require' &&
71
+ init.arguments?.length === 1 &&
72
+ init.arguments[0]?.value === PACKAGE);
73
+ }
74
+ export function collectRequire(node, into) {
75
+ if (!isLibraryRequire(node))
76
+ return;
77
+ const id = node.id;
78
+ if (id?.type === 'Identifier') {
79
+ into.namespaces.add(id.name);
80
+ return;
81
+ }
82
+ if (id?.type !== 'ObjectPattern')
83
+ return;
84
+ for (const prop of id.properties ?? []) {
85
+ // A rest element carries no name to bind.
86
+ if (prop?.type !== 'Property')
87
+ continue;
88
+ const imported = prop.key?.name;
89
+ const local = prop.value?.type === 'Identifier' ? prop.value.name : null;
90
+ if (typeof imported === 'string' && local)
91
+ into.named.set(local, imported);
92
+ }
93
+ }
27
94
  /**
28
95
  * The canonical library name for a JSX element, or null when the element did
29
96
  * not come from the library. Returns null rather than guessing.
@@ -61,6 +128,138 @@ export function resolveElement(nameNode, imports, bindsToImport = () => true) {
61
128
  const resolved = walk(nameNode);
62
129
  return typeof resolved === 'string' ? resolved : null;
63
130
  }
131
+ /**
132
+ * A numeric JSX attribute value, or null.
133
+ *
134
+ * Every tuple the library validates against holds strings, and its membership
135
+ * check is a plain `includes`, so `m={2}` never matches `'2'` and emits
136
+ * nothing. That is a knowably wrong value rather than an unreadable one, and
137
+ * `m={2}` is the natural spelling in exactly the JavaScript and JSX projects
138
+ * this package exists for, so it must not be lumped in with the values a rule
139
+ * declines to judge.
140
+ */
141
+ export function numericValue(attr) {
142
+ const v = attr?.value;
143
+ if (v?.type !== 'JSXExpressionContainer')
144
+ return null;
145
+ const e = v.expression;
146
+ if (e?.type === 'Literal' && typeof e.value === 'number')
147
+ return e.value;
148
+ // `m={-1}` parses as a unary minus over a literal, not as a negative
149
+ // literal, and the spacing scale is exactly where someone reaches for a
150
+ // negative (see the negative-gutter pattern in #678).
151
+ if (e?.type === 'UnaryExpression' &&
152
+ (e.operator === '-' || e.operator === '+') &&
153
+ e.argument?.type === 'Literal' &&
154
+ typeof e.argument.value === 'number') {
155
+ return e.operator === '-' ? -e.argument.value : e.argument.value;
156
+ }
157
+ return null;
158
+ }
159
+ /**
160
+ * Attributes with only the LAST occurrence of each name kept, in source order.
161
+ *
162
+ * Duplicate JSX attributes are legal JavaScript and React resolves them
163
+ * last-wins, so judging every occurrence reports a value the element does not
164
+ * render: `<Box m="bogus" m="4" />` renders `m="4"` and was reported anyway.
165
+ */
166
+ export function winningAttributes(opening) {
167
+ const attrs = attributesOf(opening);
168
+ const lastIndex = new Map();
169
+ attrs.forEach((a, i) => lastIndex.set(a.name.name, i));
170
+ return attrs.filter((a, i) => lastIndex.get(a.name.name) === i);
171
+ }
172
+ /**
173
+ * Attributes whose VALUE is the one that renders.
174
+ *
175
+ * `winningAttributes` settles duplicate names; this also drops anything a
176
+ * LATER spread could overwrite. JSX is last-wins throughout, spreads included,
177
+ * so "an explicit attribute wins over a spread" — which this package asserted
178
+ * in three places — holds only for a spread that comes FIRST.
179
+ * `<Box textAlign="center" {...rest} />` renders whatever `rest.textAlign`
180
+ * says, so the written value is not necessarily a value that renders at all.
181
+ *
182
+ * Only rules that judge a value need this. A rule reporting that a PROP is
183
+ * deprecated is right either way, because the author wrote the deprecated
184
+ * prop whether or not its value survives.
185
+ */
186
+ export function valuesThatRender(opening) {
187
+ const all = (opening?.attributes ?? []);
188
+ const lastSpread = all.reduce((found, a, i) => (a?.type === 'JSXSpreadAttribute' ? i : found), -1);
189
+ return winningAttributes(opening).filter(a => all.indexOf(a) > lastSpread);
190
+ }
191
+ /**
192
+ * True only when the attribute's value cannot be read at all.
193
+ *
194
+ * This is the predicate every "say nothing" guard should use, and having three
195
+ * rounds of review find the same defect one rule at a time is what earned it a
196
+ * name. The rules kept conflating two different reasons to stay quiet:
197
+ *
198
+ * - the value is genuinely unknown (`{mode}`, an interpolated template) —
199
+ * it could be anything, including the right thing, so silence is correct
200
+ * - the value is readable but of a type no tuple entry can ever be (`true`,
201
+ * `{false}`, a number) — the library drops it, so it is knowably wrong
202
+ *
203
+ * Only the first is unreadable. Any guard that returns early on "not a string
204
+ * literal" swallows the second, which is how a bare `display` bought an
205
+ * element silence on its inert flex props.
206
+ */
207
+ export function isUnreadableValue(attr) {
208
+ const v = attr?.value;
209
+ // A bare attribute is `true`, which is a value, not an absence.
210
+ if (v === null || v === undefined)
211
+ return false;
212
+ if (v.type === 'Literal')
213
+ return false;
214
+ if (v.type === 'JSXExpressionContainer') {
215
+ const e = v.expression;
216
+ if (e?.type === 'Literal')
217
+ return false;
218
+ if (e?.type === 'TemplateLiteral' && e.quasis?.length === 1)
219
+ return false;
220
+ return true;
221
+ }
222
+ return true;
223
+ }
224
+ /**
225
+ * True when the value is readable AND knowably not nullish.
226
+ *
227
+ * `isUnreadableValue` is the wrong predicate in front of a `??`, and this is
228
+ * the one call site in the package that has one: the library resolves
229
+ * `color: textColor ?? color`, so `color` is ignored only when `textColor` is
230
+ * non-nullish. A readable `null` is readable and still nullish, which made the
231
+ * `redundant` report claim `color` was ignored on an element that renders it.
232
+ *
233
+ * `{undefined}` needs no case of its own: it parses as an identifier, so it is
234
+ * unreadable and falls out above.
235
+ */
236
+ export function isKnownNonNullish(attr) {
237
+ if (isUnreadableValue(attr))
238
+ return false;
239
+ const v = attr?.value;
240
+ // A bare attribute is `true`.
241
+ if (v === null || v === undefined)
242
+ return true;
243
+ const expr = v.type === 'JSXExpressionContainer' ? v.expression : v;
244
+ return !(expr?.type === 'Literal' && expr.value === null);
245
+ }
246
+ /**
247
+ * True when the attribute's value is `true`, either spelling.
248
+ *
249
+ * `<Box mt />` and `<Box mt={true} />` are the same value, both reach the
250
+ * library as `true`, and neither matches a tuple of strings — the bare one
251
+ * was reported and the explicit one was not. `{false}` is deliberately not
252
+ * included: it reads as switching the prop off, and the library skips a falsy
253
+ * value either way, so reporting it would be noise.
254
+ */
255
+ export function isTrueValue(attr) {
256
+ const v = attr?.value;
257
+ if (v === null || v === undefined)
258
+ return true;
259
+ return (v.type === 'JSXExpressionContainer' &&
260
+ v.expression?.type === 'Literal' &&
261
+ v.expression.value === true);
262
+ }
64
263
  /**
65
264
  * The string value of a JSX attribute, or null when it is not a plain string
66
265
  * literal. Anything computed is skipped by every rule here: a value the rule
@@ -82,10 +281,49 @@ export function literalValue(attr) {
82
281
  }
83
282
  return null;
84
283
  }
284
+ /**
285
+ * The attribute that WINS for `name`, or undefined.
286
+ *
287
+ * Duplicate JSX attributes are legal JavaScript (only TypeScript rejects
288
+ * them) and React resolves them last-wins, so a first-match lookup read the
289
+ * losing one: `<Box color="primary" color="danger" />` renders
290
+ * `has-text-danger`, and hoisting the first to `textColor` changed that to
291
+ * `has-text-primary`.
292
+ */
293
+ export function namedAttr(attrs, name) {
294
+ for (let i = attrs.length - 1; i >= 0; i--) {
295
+ if (attrs[i]?.name?.name === name)
296
+ return attrs[i];
297
+ }
298
+ return undefined;
299
+ }
85
300
  /** Plain-named attributes of an opening element, skipping spreads. */
86
301
  export function attributesOf(opening) {
87
302
  return (opening?.attributes ?? []).filter((a) => a?.type === 'JSXAttribute' && a.name?.type === 'JSXIdentifier');
88
303
  }
304
+ /**
305
+ * Attribute names written more than once on this element.
306
+ *
307
+ * Duplicates are legal JavaScript and React resolves them last-wins, so a
308
+ * rule can read the winner with `winningAttributes`. An AUTOFIX cannot: it
309
+ * edits one occurrence and leaves the other, which turned
310
+ * `<Tabs isFullWidth isFullWidth />` into `<Tabs isFullWidth isFullwidth />`,
311
+ * still carrying the deprecated prop. Every fix that rewrites an attribute
312
+ * name has to withhold itself here, so the check is a reader rather than a
313
+ * block copied into each rule.
314
+ */
315
+ export function doubledNames(opening) {
316
+ const counts = new Map();
317
+ const doubled = new Set();
318
+ for (const a of attributesOf(opening)) {
319
+ const name = a.name.name;
320
+ const n = (counts.get(name) ?? 0) + 1;
321
+ counts.set(name, n);
322
+ if (n > 1)
323
+ doubled.add(name);
324
+ }
325
+ return doubled;
326
+ }
89
327
  /** Does this element carry a spread, making its full prop set unknowable? */
90
328
  export function hasSpread(opening) {
91
329
  return (opening?.attributes ?? []).some((a) => a?.type === 'JSXSpreadAttribute');
@@ -109,7 +347,11 @@ export function bindsToImportAt(context, node) {
109
347
  while (scope) {
110
348
  const variable = scope.variables.find((v) => v.name === name);
111
349
  if (variable) {
112
- return (variable.defs ?? []).some((d) => d.type === 'ImportBinding');
350
+ // An import binding, or the `const { Box } = require(…)` form, which
351
+ // is the same binding by another spelling. Anything else is a local
352
+ // that shadows ours.
353
+ return (variable.defs ?? []).some((d) => d.type === 'ImportBinding' ||
354
+ (d.type === 'Variable' && isLibraryRequire(d.node)));
113
355
  }
114
356
  scope = scope.upper;
115
357
  }
@@ -139,10 +381,36 @@ export function withImports() {
139
381
  imports,
140
382
  visitor: {
141
383
  Program(node) {
142
- for (const stmt of node.body ?? []) {
384
+ // A module that declares its own `require` is not calling the
385
+ // CommonJS one, so a call to it says nothing about our package. Read
386
+ // straight off the program body rather than through the scope API:
387
+ // `getScope(Program)` answers with the OUTERMOST scope, and a
388
+ // top-level `const require` lives in a child of it, so walking `upper`
389
+ // never saw the shadow. The collector only reads top-level
390
+ // declarations, so a top-level binding is the only shadow that can
391
+ // reach them.
392
+ const body = (node.body ?? []);
393
+ const requireShadowed = body.some(stmt => {
394
+ if (stmt?.type === 'FunctionDeclaration') {
395
+ return stmt.id?.name === 'require';
396
+ }
397
+ if (stmt?.type === 'VariableDeclaration') {
398
+ return (stmt.declarations ?? []).some((d) => patternBinds(d?.id, 'require'));
399
+ }
143
400
  if (stmt?.type === 'ImportDeclaration') {
401
+ return (stmt.specifiers ?? []).some((sp) => sp?.local?.name === 'require');
402
+ }
403
+ return false;
404
+ });
405
+ for (const stmt of body) {
406
+ const s = stmt;
407
+ if (s?.type === 'ImportDeclaration') {
144
408
  collectImport(stmt, imports);
145
409
  }
410
+ else if (s?.type === 'VariableDeclaration' && !requireShadowed) {
411
+ for (const d of s.declarations ?? [])
412
+ collectRequire(d, imports);
413
+ }
146
414
  }
147
415
  },
148
416
  },
@@ -9,16 +9,88 @@
9
9
  *
10
10
  * KEYED BY PROP, NOT BY ELEMENT, and that is a real limitation rather than a
11
11
  * simplification. A few components widen `bgColor` with the scheme colours
12
- * (`Box`, `Card`, `Container`, `Hero`, `Section`, `Footer`) and the rest do
13
- * not, so `<Block bgColor="scheme-main-bis" />` renders nothing and this table
14
- * accepts it. Every such gap points the same way — silence on a wrong value,
15
- * never a report on a right one — which is the direction to be wrong in, and
16
- * TypeScript catches this particular one. Closing it properly means a
17
- * per-element table, which the MCP index already extracts; that is a change
18
- * with its own dogfooding, not a tweak here. The hand-written `color`
19
- * exclusion above is the same limitation showing through.
12
+ * and the rest do not, so `<Block bgColor="scheme-main-bis" />` renders
13
+ * nothing and this table accepts it. That gap points the safe way: silence on
14
+ * a wrong value, never a report on a right one, and TypeScript catches this
15
+ * particular one anyway. Closing it properly means a per-element table, which
16
+ * the MCP index already extracts; that is a change with its own dogfooding,
17
+ * not a tweak here. The hand-written `color` exclusion above is the same
18
+ * limitation showing through.
19
+ *
20
+ * Where a prop name means something else ENTIRELY on some element, the safe
21
+ * direction is not available and the table has to be told: see
22
+ * `NOT_A_HELPER_PROP` below.
23
+ *
24
+ * KEYED BY PROP also means each prop is judged ALONE, and the shade props are
25
+ * where that shows. `<Box textColor="white-bis" colorShade="15" />` passes
26
+ * both entries and renders `has-text-white-bis-15`, which the stylesheet does
27
+ * not carry, and `bgColor` with `backgroundColorShade` is the same shape:
28
+ * only the colours with a live component modifier take a shade, in either
29
+ * family, which is the same set `UNSTYLED_MODIFIER_COLORS` is the complement
30
+ * of. Pre-existing for the greys and the black pair, widened by two when the
31
+ * white shades were added, and a false negative either way.
32
+ *
33
+ * A cross-prop check would close most of it off the partition
34
+ * `scripts/color-tuple-css.test.mjs` asserts, but not all: `inherit` and
35
+ * `current` are accepted by the same props, are live unshaded, and have no
36
+ * shaded class either, and they are not in `validColors` for that partition
37
+ * to cover. So the rule would need those two named as well.
38
+ *
39
+ * The scheme colours are NOT another case of it: they emit no class at all,
40
+ * arriving as an inline `background-color` instead, with the shade documented
41
+ * as ignored, and only a few components widen `bgColor` to accept them in the
42
+ * first place.
43
+ *
44
+ * Left open because a rule reading two attributes at once is a different
45
+ * shape from the rest of this table, and wants its own dogfooding rather than
46
+ * riding along.
20
47
  */
21
48
  export declare const HELPER_VALUES: ReadonlyMap<string, readonly string[]>;
49
+ /**
50
+ * Props whose only value REMOVES the thing the prop names, and what to call
51
+ * that thing in a message.
52
+ *
53
+ * `radius` and `shadow` read like switches for "give this a radius" and "give
54
+ * this a shadow", and their one value does the reverse: `radiusless`,
55
+ * `shadowless`. The generic shorthand remedy, "give it a value:
56
+ * `shadowless`", therefore tells an author who wrote `<Box shadow />` to do
57
+ * the opposite of what they meant, on an element whose shadow is on by
58
+ * default. The report is right either way; only the remedy needed separating.
59
+ *
60
+ * The rule pairs this with a `valid.length === 1` check rather than trusting
61
+ * it alone, so "its only value" cannot become false by a value being added to
62
+ * one of those tuples.
63
+ */
64
+ export declare const REMOVES_ONLY: ReadonlyMap<string, string>;
65
+ /**
66
+ * Elements on which one of the names above is NOT a helper prop, so the table
67
+ * must not be applied to it.
68
+ *
69
+ * `Theme` mints a prop for every Bulma CSS variable, and `--bulma-radius`
70
+ * collides with the `radius` helper. On `Theme` the variable wins at runtime
71
+ * while the declared type stays the helper union, so the two disagree and the
72
+ * rule cannot say anything true about the pair (#694). Both readings:
73
+ * `<Theme radius="6px" />` does not typecheck and does set the variable, so
74
+ * reporting it is a false positive in the JS and JSX projects this rule is
75
+ * for; `<Theme radius="radiusless" />` typechecks and renders
76
+ * `style="--bulma-radius: radiusless"`, so the value the rule would call
77
+ * correct is the one that does nothing. Silence is the only honest answer
78
+ * until #694 picks a meaning.
79
+ *
80
+ * `--bulma-shadow` would collide the same way and is filtered out of that map
81
+ * for exactly this reason, which is why `shadow` is a helper prop on `Theme`
82
+ * and needs no entry here. That filter is the precedent #694 would follow.
83
+ *
84
+ * This is the one-way invariant above being held rather than abandoned:
85
+ * silence on a wrong value is the direction to be wrong in, and a report on a
86
+ * right one is not. Declared rather than derived, and held to the library by
87
+ * `scripts/helper-prop-collisions.test.mjs`, which recomputes the collision
88
+ * from the library's own variable list and fails if this map and the real one
89
+ * disagree. Same shape as `SIBLING_RUNTIME_DEPS` in check-conformance.mjs,
90
+ * and for the same reason: a declaration no test can falsify becomes a
91
+ * fiction.
92
+ */
93
+ export declare const NOT_A_HELPER_PROP: ReadonlyMap<string, ReadonlySet<string>>;
22
94
  /** Props that emit a class only when a flex `display` is also set. */
23
95
  export declare const FLEX_CONTAINER_PROPS: readonly string[];
24
96
  /** Every `display*` prop name, in declaration order. */
@@ -1 +1 @@
1
- {"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/lib/values.ts"],"names":[],"mappings":"AAgFA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CA6B/D,CAAC;AAEH,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAMjD,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAG1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAA4B,CAAC"}
1
+ {"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/lib/values.ts"],"names":[],"mappings":"AA4FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAoC/D,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAGnD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CACzC,MAAM,EACN,WAAW,CAAC,MAAM,CAAC,CACwB,CAAC;AAE9C,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAMjD,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAG1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAA4B,CAAC"}
@@ -3,12 +3,17 @@
3
3
  * tuples rather than a copy of them.
4
4
  *
5
5
  * This import is why the package depends on `@allxsmith/bestax-bulma` at
6
- * runtime: the rule then validates against the tuples belonging to the
7
- * version the consumer actually installed, so it cannot drift. The
8
- * `/constants` subpath carries the tuples with no React and no component
9
- * code, so linting does not load the library proper.
6
+ * runtime: the rule validates against the library's own tuples rather than a
7
+ * copy of them. The `/constants` subpath carries those tuples with no React
8
+ * and no component code, so linting does not load the library proper.
9
+ *
10
+ * Be precise about the version it reads, because an earlier draft of this
11
+ * comment overclaimed it: the tuples come from the copy THIS PACKAGE resolves,
12
+ * which an ordinary deduped install makes the app's, but a major-version split
13
+ * does not. See eslint-plugin/CLAUDE.md, which also records why the dependency
14
+ * is a runtime one and must stay that way.
10
15
  */
11
- import { validAlignContents, validAlignItems, validAlignSelfs, validAlignments, validColorShades, validColors, validDisplays, validFlexDirections, validFlexGrowShrink, validFlexWraps, validFontFamilies, validJustifyContents, validSchemeColors, validSizes, validTextSizes, validTextTransforms, validTextWeights, validViewports, validVisibilities, } from '@allxsmith/bestax-bulma/constants';
16
+ import { validAlignContents, validAlignItems, validAlignSelfs, validAlignments, validColorShades, validColors, validCursors, validDisplays, validFlexDirections, validFlexGrowShrink, validFlexWraps, validFloats, validFontFamilies, validInteractions, validJustifyContents, validOverflows, validRadii, validResponsives, validSchemeColors, validShadows, validSizes, validTextSizes, validTextTransforms, validTextWeights, validViewports, validVisibilities, } from '@allxsmith/bestax-bulma/constants';
12
17
  const SPACING_PROPS = [
13
18
  'm',
14
19
  'mt',
@@ -60,14 +65,41 @@ const family = (base, bands, values) => [
60
65
  *
61
66
  * KEYED BY PROP, NOT BY ELEMENT, and that is a real limitation rather than a
62
67
  * simplification. A few components widen `bgColor` with the scheme colours
63
- * (`Box`, `Card`, `Container`, `Hero`, `Section`, `Footer`) and the rest do
64
- * not, so `<Block bgColor="scheme-main-bis" />` renders nothing and this table
65
- * accepts it. Every such gap points the same way — silence on a wrong value,
66
- * never a report on a right one — which is the direction to be wrong in, and
67
- * TypeScript catches this particular one. Closing it properly means a
68
- * per-element table, which the MCP index already extracts; that is a change
69
- * with its own dogfooding, not a tweak here. The hand-written `color`
70
- * exclusion above is the same limitation showing through.
68
+ * and the rest do not, so `<Block bgColor="scheme-main-bis" />` renders
69
+ * nothing and this table accepts it. That gap points the safe way: silence on
70
+ * a wrong value, never a report on a right one, and TypeScript catches this
71
+ * particular one anyway. Closing it properly means a per-element table, which
72
+ * the MCP index already extracts; that is a change with its own dogfooding,
73
+ * not a tweak here. The hand-written `color` exclusion above is the same
74
+ * limitation showing through.
75
+ *
76
+ * Where a prop name means something else ENTIRELY on some element, the safe
77
+ * direction is not available and the table has to be told: see
78
+ * `NOT_A_HELPER_PROP` below.
79
+ *
80
+ * KEYED BY PROP also means each prop is judged ALONE, and the shade props are
81
+ * where that shows. `<Box textColor="white-bis" colorShade="15" />` passes
82
+ * both entries and renders `has-text-white-bis-15`, which the stylesheet does
83
+ * not carry, and `bgColor` with `backgroundColorShade` is the same shape:
84
+ * only the colours with a live component modifier take a shade, in either
85
+ * family, which is the same set `UNSTYLED_MODIFIER_COLORS` is the complement
86
+ * of. Pre-existing for the greys and the black pair, widened by two when the
87
+ * white shades were added, and a false negative either way.
88
+ *
89
+ * A cross-prop check would close most of it off the partition
90
+ * `scripts/color-tuple-css.test.mjs` asserts, but not all: `inherit` and
91
+ * `current` are accepted by the same props, are live unshaded, and have no
92
+ * shaded class either, and they are not in `validColors` for that partition
93
+ * to cover. So the rule would need those two named as well.
94
+ *
95
+ * The scheme colours are NOT another case of it: they emit no class at all,
96
+ * arriving as an inline `background-color` instead, with the shade documented
97
+ * as ignored, and only a few components widen `bgColor` to accept them in the
98
+ * first place.
99
+ *
100
+ * Left open because a rule reading two attributes at once is a different
101
+ * shape from the rest of this table, and wants its own dogfooding rather than
102
+ * riding along.
71
103
  */
72
104
  export const HELPER_VALUES = new Map([
73
105
  ...SPACING_PROPS.map(p => [p, validSizes]),
@@ -88,6 +120,13 @@ export const HELPER_VALUES = new Map([
88
120
  ['flexGrow', validFlexGrowShrink],
89
121
  ['flexShrink', validFlexGrowShrink],
90
122
  ['viewport', validViewports],
123
+ ['float', validFloats],
124
+ ['overflow', validOverflows],
125
+ ['interaction', validInteractions],
126
+ ['cursor', validCursors],
127
+ ['radius', validRadii],
128
+ ['shadow', validShadows],
129
+ ['responsive', validResponsives],
91
130
  ['colorShade', validColorShades],
92
131
  ['backgroundColorShade', validColorShades],
93
132
  // The colour props take the tuple plus the two CSS-wide keywords that
@@ -99,6 +138,54 @@ export const HELPER_VALUES = new Map([
99
138
  [...validColors, ...validSchemeColors, 'inherit', 'current'],
100
139
  ],
101
140
  ]);
141
+ /**
142
+ * Props whose only value REMOVES the thing the prop names, and what to call
143
+ * that thing in a message.
144
+ *
145
+ * `radius` and `shadow` read like switches for "give this a radius" and "give
146
+ * this a shadow", and their one value does the reverse: `radiusless`,
147
+ * `shadowless`. The generic shorthand remedy, "give it a value:
148
+ * `shadowless`", therefore tells an author who wrote `<Box shadow />` to do
149
+ * the opposite of what they meant, on an element whose shadow is on by
150
+ * default. The report is right either way; only the remedy needed separating.
151
+ *
152
+ * The rule pairs this with a `valid.length === 1` check rather than trusting
153
+ * it alone, so "its only value" cannot become false by a value being added to
154
+ * one of those tuples.
155
+ */
156
+ export const REMOVES_ONLY = new Map([
157
+ ['radius', 'border radius'],
158
+ ['shadow', 'shadow'],
159
+ ]);
160
+ /**
161
+ * Elements on which one of the names above is NOT a helper prop, so the table
162
+ * must not be applied to it.
163
+ *
164
+ * `Theme` mints a prop for every Bulma CSS variable, and `--bulma-radius`
165
+ * collides with the `radius` helper. On `Theme` the variable wins at runtime
166
+ * while the declared type stays the helper union, so the two disagree and the
167
+ * rule cannot say anything true about the pair (#694). Both readings:
168
+ * `<Theme radius="6px" />` does not typecheck and does set the variable, so
169
+ * reporting it is a false positive in the JS and JSX projects this rule is
170
+ * for; `<Theme radius="radiusless" />` typechecks and renders
171
+ * `style="--bulma-radius: radiusless"`, so the value the rule would call
172
+ * correct is the one that does nothing. Silence is the only honest answer
173
+ * until #694 picks a meaning.
174
+ *
175
+ * `--bulma-shadow` would collide the same way and is filtered out of that map
176
+ * for exactly this reason, which is why `shadow` is a helper prop on `Theme`
177
+ * and needs no entry here. That filter is the precedent #694 would follow.
178
+ *
179
+ * This is the one-way invariant above being held rather than abandoned:
180
+ * silence on a wrong value is the direction to be wrong in, and a report on a
181
+ * right one is not. Declared rather than derived, and held to the library by
182
+ * `scripts/helper-prop-collisions.test.mjs`, which recomputes the collision
183
+ * from the library's own variable list and fails if this map and the real one
184
+ * disagree. Same shape as `SIBLING_RUNTIME_DEPS` in check-conformance.mjs,
185
+ * and for the same reason: a declaration no test can falsify becomes a
186
+ * fiction.
187
+ */
188
+ export const NOT_A_HELPER_PROP = new Map([['Theme', new Set(['radius'])]]);
102
189
  /** Props that emit a class only when a flex `display` is also set. */
103
190
  export const FLEX_CONTAINER_PROPS = [
104
191
  'flexDirection',
@@ -14,10 +14,17 @@
14
14
  *
15
15
  * Two things it must not do, both found by linting the library's own docs:
16
16
  *
17
- * - Fire when the element also sets a background. `<Box backgroundColor="light"
18
- * color="dark">` is a deliberate, correct pairing — surface from one prop,
19
- * text from the other — and telling that author "color is not a background"
20
- * is nonsense.
17
+ * - Fire when the element also sets a background. `<Box bgColor="light"
18
+ * color="primary">` is a deliberate, correct pairing — surface from one
19
+ * prop, text from the other — and telling that author "color is not a
20
+ * background" is nonsense.
21
+ *
22
+ * `backgroundColor` counts as a background here too, and is checked,
23
+ * because it reaches `useColorClasses` at runtime on every element: the
24
+ * components spread `...props` into `useBulmaClasses` last. But most of
25
+ * the text-alias elements `Omit` it from their PROPS, so that spelling is
26
+ * a type error on them even though it renders. `bgColor` is the one to
27
+ * write, and the one this comment names.
21
28
  * - Fire on elements with a real `is-<color>` modifier. Those are absent from
22
29
  * the generated set, so `<Button color="primary">` never reports.
23
30
  *
@@ -1 +1 @@
1
- {"version":3,"file":"no-color-as-surface.d.ts","sourceRoot":"","sources":["../../src/rules/no-color-as-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAenC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAgEhB,CAAC;AAEF,eAAe,IAAI,CAAC"}
1
+ {"version":3,"file":"no-color-as-surface.d.ts","sourceRoot":"","sources":["../../src/rules/no-color-as-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AA+BnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAyGhB,CAAC;AAEF,eAAe,IAAI,CAAC"}