stylelint-plugin-rhythmguard 3.18.0 → 3.20.0
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.
- package/CHANGELOG.md +68 -0
- package/CONTRIBUTING.md +2 -2
- package/README.md +4 -4
- package/SECURITY.md +14 -0
- package/agents/claude-code/SKILL.md +14 -1
- package/agents/copilot/{copilot-instructions.md → rhythmguard.instructions.md} +7 -1
- package/agents/cursor/rhythmguard.mdc +5 -3
- package/package.json +2 -2
- package/src/audit/args.js +30 -8
- package/src/audit/baseline.js +44 -2
- package/src/audit/codemod.js +2 -0
- package/src/audit/config.js +7 -0
- package/src/audit/contract.js +131 -17
- package/src/audit/next-steps.js +86 -0
- package/src/audit/non-authored.js +1 -0
- package/src/audit/render-github.js +52 -15
- package/src/audit/render-markdown.js +58 -17
- package/src/audit/render-text.js +76 -6
- package/src/audit/render-utils.js +14 -0
- package/src/audit/report.js +235 -10
- package/src/audit/scan/files.js +5 -0
- package/src/audit/scan/stylesheets.js +63 -59
- package/src/audit/scan/templates.js +2 -0
- package/src/audit/shared.js +7 -1
- package/src/audit/token-chains.js +1 -0
- package/src/cli/audit.js +20 -11
- package/src/cli/doctor.js +853 -237
- package/src/cli/first-run.js +210 -0
- package/src/cli/index.js +25 -1
- package/src/cli/index.mjs +3 -0
- package/src/cli/init.js +75 -26
- package/src/cli/quickstart.js +109 -118
- package/src/cli/scale.js +223 -0
- package/src/configs/recommended.js +3 -1
- package/src/configs/strict.js +3 -1
- package/src/configs/tailwind.js +15 -0
- package/src/core/decisions.js +18 -5
- package/src/core/fs-cache.js +1 -0
- package/src/core/options.js +2 -1
- package/src/core/scale-inference.js +72 -52
- package/src/core/tailwind-class-analysis.js +56 -13
- package/src/core/token-index.js +55 -14
- package/src/core/token-map.js +140 -88
- package/src/core/token-sources.js +461 -40
- package/src/core/value-nodes.js +4 -2
- package/src/eslint/class-context.js +330 -0
- package/src/eslint/literal-spans.js +5 -4
- package/src/eslint/rules/tailwind-class-use-scale.js +30 -9
- package/src/presets/default-scale.js +42 -0
- package/src/presets/scales.js +6 -1
- package/src/rules/no-offscale-transform/index.js +17 -5
- package/src/rules/prefer-token/index.js +51 -15
- package/src/rules/use-scale/index.js +7 -4
- package/types/__checks__/consumer.ts +17 -0
- package/types/__checks__/eslint-config.ts +5 -0
- package/types/audit.d.ts +42 -3
- package/types/cli.d.ts +77 -1
- package/types/shared.d.ts +10 -0
package/src/core/options.js
CHANGED
|
@@ -21,7 +21,7 @@ const {
|
|
|
21
21
|
resolveScaleSelection,
|
|
22
22
|
} = require('../presets/scales');
|
|
23
23
|
|
|
24
|
-
const DEFAULT_SCALE =
|
|
24
|
+
const { DEFAULT_SCALE } = require('../presets/default-scale');
|
|
25
25
|
const VALIDATE_ALWAYS = () => true;
|
|
26
26
|
const SUPPORTED_MATH_FUNCTIONS = new Set(Array.from(MATH_FUNCTIONS));
|
|
27
27
|
|
|
@@ -146,6 +146,7 @@ function parseRegexLikeString(value) {
|
|
|
146
146
|
try {
|
|
147
147
|
return new RegExp(pattern, flags);
|
|
148
148
|
} catch {
|
|
149
|
+
// Not a valid regex: validation then rejects the entry as an unknown property.
|
|
149
150
|
return null;
|
|
150
151
|
}
|
|
151
152
|
}
|
|
@@ -9,12 +9,15 @@ const { buildEffectiveTokenMap } = require('./token-map');
|
|
|
9
9
|
const {
|
|
10
10
|
addDefinition,
|
|
11
11
|
collectScssTokens,
|
|
12
|
+
conditionsOfNode,
|
|
13
|
+
scopeOfNode,
|
|
12
14
|
createTokenKindMatcher,
|
|
13
15
|
parseTokenSources,
|
|
14
16
|
parseTokenValueLength,
|
|
15
17
|
} = require('./token-sources');
|
|
16
18
|
const { normalizeTokenSourceEntry } = require('./token-source-entries');
|
|
17
19
|
const { getScalePreset } = require('../presets/scales');
|
|
20
|
+
const { TAILWIND_SPACING_MULTIPLIERS } = require('../presets/default-scale');
|
|
18
21
|
|
|
19
22
|
// Matches the audit default so lint and audit agree on what a spacing token is.
|
|
20
23
|
const DEFAULT_AUTO_TOKEN_PATTERN = '(^--|-)(?<!letter-)(?<!word-)(space|spacing|spacer)(-|$)';
|
|
@@ -27,9 +30,6 @@ const TAILWIND_BASE_TOKENS = new Set(['--spacing']);
|
|
|
27
30
|
// plain lengths (`--space-s`, `--space-m`) next to `--space` is the scale, and
|
|
28
31
|
// `--space` is one more step on it (issue #293).
|
|
29
32
|
const CONDITIONAL_BASE_TOKENS = new Set(['--space']);
|
|
30
|
-
const TAILWIND_SPACING_MULTIPLIERS = [
|
|
31
|
-
0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 96,
|
|
32
|
-
];
|
|
33
33
|
const FALLBACK_PRESET = 'rhythmic-4';
|
|
34
34
|
// Zero plus at least three distinct token values; a one- or two-token scale is worse than the default.
|
|
35
35
|
const MIN_INFERRED_SCALE_LENGTH = 4;
|
|
@@ -53,6 +53,7 @@ function readDirectDependencies(dir) {
|
|
|
53
53
|
...Object.keys(pkg.peerDependencies || {}),
|
|
54
54
|
]);
|
|
55
55
|
} catch {
|
|
56
|
+
// No package.json, or one npm could not read either: no dependencies to discover.
|
|
56
57
|
return null;
|
|
57
58
|
}
|
|
58
59
|
}
|
|
@@ -151,11 +152,11 @@ function pxValuesFromKeys(keys, baseFontSize) {
|
|
|
151
152
|
* do not normalise (a bad format, no path) are skipped with a warning; they
|
|
152
153
|
* never throw out of a lint.
|
|
153
154
|
*/
|
|
154
|
-
function parseSourcesCached(sources, baseFontSize) {
|
|
155
|
+
function parseSourcesCached(sources, baseFontSize, cwd = process.cwd()) {
|
|
155
156
|
const normalized = [];
|
|
156
157
|
const warnings = [];
|
|
157
158
|
for (const entry of sources) {
|
|
158
|
-
const { error, source } = normalizeTokenSourceEntry(entry,
|
|
159
|
+
const { error, source } = normalizeTokenSourceEntry(entry, cwd);
|
|
159
160
|
if (error) {
|
|
160
161
|
warnings.push(error);
|
|
161
162
|
} else {
|
|
@@ -185,14 +186,15 @@ function parseSourcesCached(sources, baseFontSize) {
|
|
|
185
186
|
* spacing names, unless a source sets its own. Fixes and scale inference read
|
|
186
187
|
* the same tokens through this (issue #296).
|
|
187
188
|
*/
|
|
188
|
-
function parseSourcesWithPattern(sources, baseFontSize, tokenPattern = null) {
|
|
189
|
-
const plain = parseSourcesCached(sources, baseFontSize);
|
|
189
|
+
function parseSourcesWithPattern(sources, baseFontSize, tokenPattern = null, cwd = process.cwd()) {
|
|
190
|
+
const plain = parseSourcesCached(sources, baseFontSize, cwd);
|
|
190
191
|
if (!tokenPattern || !plain) {
|
|
191
192
|
return plain;
|
|
192
193
|
}
|
|
193
194
|
const withPattern = parseSourcesCached(
|
|
194
195
|
sources.map((source) => (typeof source === 'string' ? { path: source, tokenPattern } : { tokenPattern, ...source })),
|
|
195
196
|
baseFontSize,
|
|
197
|
+
cwd,
|
|
196
198
|
);
|
|
197
199
|
const definitions = new Map(plain.definitions);
|
|
198
200
|
for (const [token, definition] of withPattern ? withPattern.definitions : []) {
|
|
@@ -209,8 +211,8 @@ function parseSourcesWithPattern(sources, baseFontSize, tokenPattern = null) {
|
|
|
209
211
|
* that are missing or do not parse go into `warnings` either way, so a
|
|
210
212
|
* fallback can say which source failed (issue #270).
|
|
211
213
|
*/
|
|
212
|
-
function scaleFromSources(sources, baseFontSize, warnings = [], tokenPattern = null) {
|
|
213
|
-
const parsed = parseSourcesWithPattern(sources, baseFontSize, tokenPattern);
|
|
214
|
+
function scaleFromSources(sources, baseFontSize, warnings = [], tokenPattern = null, cwd = process.cwd()) {
|
|
215
|
+
const parsed = parseSourcesWithPattern(sources, baseFontSize, tokenPattern, cwd);
|
|
214
216
|
if (!parsed) {
|
|
215
217
|
return null;
|
|
216
218
|
}
|
|
@@ -309,24 +311,6 @@ function scaleWithBase({ baseFontSize, baseKeys, conditionalKeys, keys }) {
|
|
|
309
311
|
return expandTailwindBase(plain, conditionalKeys, baseFontSize);
|
|
310
312
|
}
|
|
311
313
|
|
|
312
|
-
/** The scope of a declaration node: the AST-side twin of customPropertyDeclarations. */
|
|
313
|
-
function scopeOfNode(decl) {
|
|
314
|
-
for (let node = decl.parent; node; node = node.parent) {
|
|
315
|
-
if (node.type === 'rule') {
|
|
316
|
-
return String(node.selector).split(',').every((selector) => ROOT_SELECTOR.test(selector.trim())) ? 'root' : 'component';
|
|
317
|
-
}
|
|
318
|
-
if (node.type === 'atrule') {
|
|
319
|
-
const name = String(node.name).toLowerCase();
|
|
320
|
-
if (name === 'theme') return 'root';
|
|
321
|
-
if (!TRANSPARENT_AT_RULES.has(name)) return 'component';
|
|
322
|
-
}
|
|
323
|
-
}
|
|
324
|
-
return 'root';
|
|
325
|
-
}
|
|
326
|
-
|
|
327
|
-
const ROOT_SELECTOR = /^(?::root|html|:host|:(?:where|is)\(\s*(?::root|html)\s*\))$/i;
|
|
328
|
-
const TRANSPARENT_AT_RULES = new Set(['media', 'supports', 'layer', 'container', 'scope', 'document']);
|
|
329
|
-
|
|
330
314
|
/** Token definitions declared in the linted stylesheet itself: custom properties with their scope, plus Sass variables and maps. */
|
|
331
315
|
function stylesheetDefinitions(root, tokenRegex, baseFontSize) {
|
|
332
316
|
const definitions = new Map();
|
|
@@ -339,7 +323,8 @@ function stylesheetDefinitions(root, tokenRegex, baseFontSize) {
|
|
|
339
323
|
if (!parsed || parsed.number === 0) {
|
|
340
324
|
return;
|
|
341
325
|
}
|
|
342
|
-
|
|
326
|
+
// A component token is in scope only inside its own block (fix-02).
|
|
327
|
+
addDefinition(definitions, { anchor: decl.parent, baseFontSize, conditions: conditionsOfNode(decl), file: 'stylesheet', scope: scopeOfNode(decl), source: 'stylesheet', token: decl.prop, value: decl.value });
|
|
343
328
|
});
|
|
344
329
|
for (const sassToken of sassTokensFromRoot(root)) {
|
|
345
330
|
addDefinition(definitions, { baseFontSize, file: 'stylesheet', scope: 'root', source: 'stylesheet', token: sassToken.token, value: sassToken.value });
|
|
@@ -468,9 +453,13 @@ function scaleFromTokenMap(map, baseFontSize, extraKeys = []) {
|
|
|
468
453
|
* token sources, the linted stylesheet, `tailwindConfigPath`, installed token
|
|
469
454
|
* packages, the fallback preset. `sourceTokenPattern` is the rule's own
|
|
470
455
|
* explicit `tokenPattern`, applied to the token files as fixes apply it.
|
|
456
|
+
* `cwd` is the project directory that relative `scaleSources`, the rc file
|
|
457
|
+
* and installed token packages are read from; the rules leave it to default.
|
|
471
458
|
*/
|
|
472
459
|
function resolveAutoScale({
|
|
473
460
|
baseFontSize = 16,
|
|
461
|
+
cwd = process.cwd(),
|
|
462
|
+
fallbackPreset = FALLBACK_PRESET,
|
|
474
463
|
root,
|
|
475
464
|
scaleSources = [],
|
|
476
465
|
sourceTokenPattern = null,
|
|
@@ -479,22 +468,23 @@ function resolveAutoScale({
|
|
|
479
468
|
} = {}) {
|
|
480
469
|
// Warnings from every source tried, for the fallback note when none yields a scale.
|
|
481
470
|
const warnings = [];
|
|
482
|
-
const fromOption = scaleFromSources(scaleSources, baseFontSize, warnings, sourceTokenPattern);
|
|
471
|
+
const fromOption = scaleFromSources(scaleSources, baseFontSize, warnings, sourceTokenPattern, cwd);
|
|
483
472
|
if (fromOption) {
|
|
484
|
-
return { source: 'scaleSources', ...fromOption };
|
|
473
|
+
return { source: 'scaleSources', ...fromOption, warnings: [...warnings] };
|
|
485
474
|
}
|
|
486
475
|
|
|
487
|
-
const rc = rcTokenSources(
|
|
476
|
+
const rc = rcTokenSources(cwd);
|
|
488
477
|
warnings.push(...rc.warnings);
|
|
489
|
-
const fromRc = scaleFromSources(rc.sources, baseFontSize, warnings, sourceTokenPattern);
|
|
478
|
+
const fromRc = scaleFromSources(rc.sources, baseFontSize, warnings, sourceTokenPattern, cwd);
|
|
490
479
|
if (fromRc) {
|
|
491
|
-
return { source: 'rhythmguardrc', ...fromRc };
|
|
480
|
+
return { source: 'rhythmguardrc', ...fromRc, warnings: [...warnings] };
|
|
492
481
|
}
|
|
493
482
|
|
|
494
483
|
let tokenRegex;
|
|
495
484
|
try {
|
|
496
485
|
tokenRegex = new RegExp(tokenPattern);
|
|
497
486
|
} catch {
|
|
487
|
+
// createTokenRegex reports an invalid tokenPattern; inference reads the default names.
|
|
498
488
|
tokenRegex = new RegExp(DEFAULT_AUTO_TOKEN_PATTERN);
|
|
499
489
|
}
|
|
500
490
|
|
|
@@ -504,35 +494,45 @@ function resolveAutoScale({
|
|
|
504
494
|
if (scale) {
|
|
505
495
|
const assessment = assessScale({ source: 'stylesheet', values: scale });
|
|
506
496
|
if (assessment.plausible) {
|
|
507
|
-
return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [] };
|
|
497
|
+
return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [...warnings] };
|
|
508
498
|
}
|
|
509
499
|
rejected = { reasons: assessment.reasons, source: 'stylesheet', values: scale };
|
|
510
500
|
}
|
|
511
501
|
}
|
|
512
502
|
|
|
513
503
|
if (tailwindConfigPath) {
|
|
514
|
-
const
|
|
515
|
-
options: {
|
|
516
|
-
baseFontSize,
|
|
517
|
-
tailwindConfigPath,
|
|
518
|
-
tokenMap: {},
|
|
519
|
-
tokenMapFromTailwindSpacing: true,
|
|
520
|
-
},
|
|
521
|
-
root,
|
|
522
|
-
tokenRegex,
|
|
523
|
-
});
|
|
524
|
-
const scale = scaleFromTokenMap(tailwindMap, baseFontSize);
|
|
504
|
+
const scale = scaleFromTailwindConfig(tailwindConfigPath, baseFontSize, { root, tokenRegex, warnings });
|
|
525
505
|
if (scale) {
|
|
526
|
-
return { files: [tailwindConfigPath], scale, source: 'tailwind', tokenCount: scale.length - 1, warnings: [] };
|
|
506
|
+
return { files: [tailwindConfigPath], scale, source: 'tailwind', tokenCount: scale.length - 1, warnings: [...warnings] };
|
|
527
507
|
}
|
|
528
508
|
}
|
|
529
509
|
|
|
530
|
-
const fromPackages = scaleFromSources(discoverTokenPackages(
|
|
510
|
+
const fromPackages = scaleFromSources(discoverTokenPackages(cwd), baseFontSize, warnings, sourceTokenPattern, cwd);
|
|
531
511
|
if (fromPackages) {
|
|
532
|
-
return { source: 'token-package', ...fromPackages };
|
|
512
|
+
return { source: 'token-package', ...fromPackages, warnings: [...warnings] };
|
|
533
513
|
}
|
|
534
514
|
|
|
535
|
-
return fallbackInference(rejected, warnings);
|
|
515
|
+
return fallbackInference(rejected, warnings, fallbackPreset);
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
/**
|
|
519
|
+
* The scale in a Tailwind v3 config's `theme.spacing` (and `extend.spacing`),
|
|
520
|
+
* or null. The config is loaded with `require()`, so callers pass a path only
|
|
521
|
+
* when the user configured one.
|
|
522
|
+
*/
|
|
523
|
+
function scaleFromTailwindConfig(tailwindConfigPath, baseFontSize = 16, { root = null, tokenRegex = new RegExp(DEFAULT_AUTO_TOKEN_PATTERN), warnings = [] } = {}) {
|
|
524
|
+
const tailwindMap = buildEffectiveTokenMap({
|
|
525
|
+
options: {
|
|
526
|
+
baseFontSize,
|
|
527
|
+
tailwindConfigPath,
|
|
528
|
+
tokenMap: {},
|
|
529
|
+
tokenMapFromTailwindSpacing: true,
|
|
530
|
+
},
|
|
531
|
+
root,
|
|
532
|
+
tokenRegex,
|
|
533
|
+
warnings,
|
|
534
|
+
});
|
|
535
|
+
return scaleFromTokenMap(tailwindMap, baseFontSize);
|
|
536
536
|
}
|
|
537
537
|
|
|
538
538
|
const TRUSTED_SCALE_SOURCES = new Set(['scaleSources', 'rhythmguardrc', 'token-sources', 'tailwind', 'token-package', 'explicit', 'default']);
|
|
@@ -577,12 +577,18 @@ function assessScale({ files = null, source, values = [] } = {}) {
|
|
|
577
577
|
return { plausible: reasons.length === 0, reasons };
|
|
578
578
|
}
|
|
579
579
|
|
|
580
|
-
|
|
580
|
+
/**
|
|
581
|
+
* The scale when no source gives one: the rule's `preset` when it sets one
|
|
582
|
+
* next to `scale: "auto"` (configs/tailwind falls back to the Tailwind ladder),
|
|
583
|
+
* else `rhythmic-4`.
|
|
584
|
+
*/
|
|
585
|
+
function fallbackInference(rejected = null, warnings = [], preset = FALLBACK_PRESET) {
|
|
586
|
+
const name = getScalePreset(preset) ? preset : FALLBACK_PRESET;
|
|
581
587
|
return {
|
|
582
588
|
files: [],
|
|
583
|
-
preset:
|
|
589
|
+
preset: name,
|
|
584
590
|
...(rejected ? { rejected } : {}),
|
|
585
|
-
scale: getScalePreset(
|
|
591
|
+
scale: getScalePreset(name),
|
|
586
592
|
source: 'fallback',
|
|
587
593
|
tokenCount: 0,
|
|
588
594
|
warnings,
|
|
@@ -598,6 +604,7 @@ function withResolvedScale(options, root) {
|
|
|
598
604
|
if (options.scaleAuto) {
|
|
599
605
|
const inference = resolveAutoScale({
|
|
600
606
|
baseFontSize: options.baseFontSize,
|
|
607
|
+
fallbackPreset: options.preset || FALLBACK_PRESET,
|
|
601
608
|
root,
|
|
602
609
|
scaleSources: options.scaleSources,
|
|
603
610
|
sourceTokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
|
|
@@ -673,14 +680,27 @@ function sourceWarningsNote(warnings) {
|
|
|
673
680
|
return unique.map((warning) => ` ${/[.!?]$/.test(warning) ? warning : `${warning}.`}`).join('');
|
|
674
681
|
}
|
|
675
682
|
|
|
683
|
+
/**
|
|
684
|
+
* The loader warnings a rule adds to its first message in a file, beyond the
|
|
685
|
+
* fallback note: an rc that could not be read, a token map or Tailwind config
|
|
686
|
+
* that could not be loaded, a token source that failed while another gave the
|
|
687
|
+
* scale (cq-05). Empty when nothing failed.
|
|
688
|
+
*/
|
|
689
|
+
function loaderWarningsNote(warnings, inference = null) {
|
|
690
|
+
const fromInference = inference && inference.source !== 'fallback' ? inference.warnings || [] : [];
|
|
691
|
+
return sourceWarningsNote([...(warnings || []), ...fromInference]).trim();
|
|
692
|
+
}
|
|
693
|
+
|
|
676
694
|
module.exports = {
|
|
677
695
|
DEFAULT_AUTO_TOKEN_PATTERN,
|
|
678
696
|
assessScale,
|
|
679
697
|
autoScaleFallbackNote,
|
|
680
698
|
collectTokenDefinitions,
|
|
699
|
+
loaderWarningsNote,
|
|
681
700
|
discoverTokenPackages,
|
|
682
701
|
inferScaleFromDefinitions,
|
|
683
702
|
resolveAutoScale,
|
|
684
703
|
scaleFromDefinitions,
|
|
704
|
+
scaleFromTailwindConfig,
|
|
685
705
|
withResolvedScale,
|
|
686
706
|
};
|
|
@@ -11,16 +11,20 @@ const {
|
|
|
11
11
|
pxOnScale,
|
|
12
12
|
toPx,
|
|
13
13
|
} = require('./length');
|
|
14
|
+
const { TAILWIND_SCALE_NAME, TAILWIND_SPACING_UNIT_REM, tailwindSpacingLadder } = require('../presets/default-scale');
|
|
14
15
|
|
|
15
|
-
// The ESLint rule's and the audit's default scale. It is not the `rhythmic-4`
|
|
16
|
-
// preset (which continues to 40, 48, 64); unifying the defaults changes
|
|
17
|
-
// reports, so it waits for a major (#246).
|
|
18
|
-
const DEFAULT_SCALE = [0, 4, 8, 12, 16, 24, 32];
|
|
19
16
|
const DEFAULT_UNITS = ['px', 'rem', 'em'];
|
|
20
17
|
// Tailwind's numeric spacing utilities are multiples of one unit: `--spacing`
|
|
21
18
|
// (0.25rem) in v4, and the same 0.25rem step in the v3 default scale. In px
|
|
22
19
|
// that is a quarter of the root font size: 4px at 16px, 2.5px at 10px (#247).
|
|
23
|
-
const SPACING_UNIT_REM =
|
|
20
|
+
const SPACING_UNIT_REM = TAILWIND_SPACING_UNIT_REM;
|
|
21
|
+
|
|
22
|
+
// Utilities Tailwind has no negative form for: padding, scroll padding and
|
|
23
|
+
// gap (padding and gap cannot be negative in CSS). `-p-3` and `-gap-3` are
|
|
24
|
+
// never generated, and `p-[-13px]` writes an invalid declaration (cs-08).
|
|
25
|
+
// The class regex still accepts the sign on them so a finding that was
|
|
26
|
+
// reported keeps being reported, now without a fix.
|
|
27
|
+
const NO_NEGATIVE_FORM = /^(?:p[trblxy]?|gap(?:-[xy])?|scroll-p[trblxy]?)$/;
|
|
24
28
|
|
|
25
29
|
const ARBITRARY_SPACING_CLASS = /^(?<utility>-?(?:m(?:[trblxy])?|p(?:[trblxy])?|gap(?:-[xy])?|space-[xy]|inset(?:-[xy])?|top|right|bottom|left|translate-[xy]|scroll-(?:m|p)(?:[trblxy])?))-\[(?<rawValue>[^\]]+)\]$/;
|
|
26
30
|
|
|
@@ -31,16 +35,22 @@ function normalizeTailwindClassOptions(option = {}) {
|
|
|
31
35
|
option.baseFontSize > 0
|
|
32
36
|
? option.baseFontSize
|
|
33
37
|
: 16;
|
|
38
|
+
const spacingUnit = option.spacingUnit === false
|
|
39
|
+
? null
|
|
40
|
+
: typeof option.spacingUnit === 'number' && Number.isFinite(option.spacingUnit) && option.spacingUnit > 0
|
|
41
|
+
? option.spacingUnit
|
|
42
|
+
: baseFontSize * SPACING_UNIT_REM;
|
|
43
|
+
// No `scale`: Tailwind's default ladder on the spacing unit, so a standard
|
|
44
|
+
// step such as p-5 (20px) is on the scale (cs-01). Before 3.20 the default
|
|
45
|
+
// was 0 to 32px.
|
|
46
|
+
const defaultScale = !Array.isArray(option.scale);
|
|
34
47
|
return {
|
|
35
48
|
allowHairlines: option.allowHairlines !== false,
|
|
36
49
|
allowNegative: option.allowNegative !== false,
|
|
37
50
|
baseFontSize,
|
|
38
|
-
scale:
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
: typeof option.spacingUnit === 'number' && Number.isFinite(option.spacingUnit) && option.spacingUnit > 0
|
|
42
|
-
? option.spacingUnit
|
|
43
|
-
: baseFontSize * SPACING_UNIT_REM,
|
|
51
|
+
scale: defaultScale ? tailwindSpacingLadder(spacingUnit || baseFontSize * SPACING_UNIT_REM) : option.scale,
|
|
52
|
+
scaleName: defaultScale ? TAILWIND_SCALE_NAME : null,
|
|
53
|
+
spacingUnit,
|
|
44
54
|
units: Array.isArray(option.units)
|
|
45
55
|
? option.units.map((unit) => String(unit).toLowerCase())
|
|
46
56
|
: DEFAULT_UNITS,
|
|
@@ -154,6 +164,9 @@ function utilityClassFor(utility, px, negative, spacingUnit) {
|
|
|
154
164
|
return null;
|
|
155
165
|
}
|
|
156
166
|
const name = utility.startsWith('-') ? utility.slice(1) : utility;
|
|
167
|
+
if (negative && steps !== 0 && NO_NEGATIVE_FORM.test(name)) {
|
|
168
|
+
return null;
|
|
169
|
+
}
|
|
157
170
|
const sign = negative && steps !== 0 ? '-' : '';
|
|
158
171
|
return `${sign}${name}-${formatNumber(Math.round(quarters) / 4)}`;
|
|
159
172
|
}
|
|
@@ -213,6 +226,26 @@ function analyzeClassToken(token, options, scalePx) {
|
|
|
213
226
|
if (!nearest) {
|
|
214
227
|
return null;
|
|
215
228
|
}
|
|
229
|
+
// Past the top step the nearest step is not a fix: 64px snapped to a 32px
|
|
230
|
+
// top step halves the padding (cs-01). Reported, with no fix.
|
|
231
|
+
const beyondScale = pxValue > scalePx[scalePx.length - 1];
|
|
232
|
+
|
|
233
|
+
// `-p-[13px]`, `p-[-13px]`, `-gap-[13px]`: still reported, as before, but
|
|
234
|
+
// with no fix and no suggested class, since `-p-3` and `-gap-3` do not
|
|
235
|
+
// exist. A double negative (`-p-[-13px]`) is no better: Tailwind has no
|
|
236
|
+
// `-p-*` utility at all. On-scale values were never reported and are not now.
|
|
237
|
+
const bareUtility = match.groups.utility.replace(/^-/, '');
|
|
238
|
+
if (NO_NEGATIVE_FORM.test(bareUtility) && (match.groups.utility.startsWith('-') || parsedLength.number < 0)) {
|
|
239
|
+
return {
|
|
240
|
+
fixedToken: null,
|
|
241
|
+
nearest,
|
|
242
|
+
nearestUtilities: null,
|
|
243
|
+
parsedLength,
|
|
244
|
+
reason: 'no-negative-form',
|
|
245
|
+
rawValue: match.groups.rawValue,
|
|
246
|
+
utility: match.groups.utility,
|
|
247
|
+
};
|
|
248
|
+
}
|
|
216
249
|
|
|
217
250
|
const signedNearest = parsedLength.number < 0
|
|
218
251
|
? -Math.abs(nearest.nearest)
|
|
@@ -235,7 +268,7 @@ function analyzeClassToken(token, options, scalePx) {
|
|
|
235
268
|
const fixedCandidate = utilityFix || parsedToken.candidate.replace(match.groups.rawValue, replacementValue);
|
|
236
269
|
|
|
237
270
|
return {
|
|
238
|
-
fixedToken: wrap(fixedCandidate),
|
|
271
|
+
fixedToken: beyondScale ? null : wrap(fixedCandidate),
|
|
239
272
|
nearest,
|
|
240
273
|
// The utility classes for the two nearest steps, when both are quarter
|
|
241
274
|
// steps of the spacing unit; messages name these instead of px values.
|
|
@@ -276,10 +309,20 @@ function createTailwindClassAnalyzer(option = {}) {
|
|
|
276
309
|
* The message text for an off-scale class: the two nearest utility classes
|
|
277
310
|
* with their px values when the unit makes them, the px steps otherwise.
|
|
278
311
|
*/
|
|
279
|
-
function offScaleClassMessage(token, analysis) {
|
|
312
|
+
function offScaleClassMessage(token, analysis, scaleName = null) {
|
|
313
|
+
const message = offScaleClassText(token, analysis);
|
|
314
|
+
// The ESLint rule names the scale it fell back to, so a reader knows the
|
|
315
|
+
// verdict is Tailwind's default ladder and not the project's tokens.
|
|
316
|
+
return scaleName && analysis.reason === 'off-scale' ? `${message} Scale: ${scaleName}.` : message;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
function offScaleClassText(token, analysis) {
|
|
280
320
|
if (analysis.reason === 'negative') {
|
|
281
321
|
return `Unexpected Tailwind arbitrary spacing value "${token}". Negative values are disabled for this rule.`;
|
|
282
322
|
}
|
|
323
|
+
if (analysis.reason === 'no-negative-form') {
|
|
324
|
+
return `Unexpected Tailwind arbitrary spacing value "${token}". Padding and gap cannot be negative, so this class has no effect.`;
|
|
325
|
+
}
|
|
283
326
|
const lowerPx = analysis.nearest ? formatLength(analysis.nearest.lower, 'px') : 'n/a';
|
|
284
327
|
const upperPx = analysis.nearest ? formatLength(analysis.nearest.upper, 'px') : 'n/a';
|
|
285
328
|
if (analysis.nearestUtilities) {
|
package/src/core/token-index.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
const { propertyKindOf } = require('./css-vocabulary');
|
|
4
4
|
const { fixedLengthValue, numbersEqual, toPx } = require('./length');
|
|
5
|
-
const { createTokenKindMatcher, parseTokenValueLength } = require('./token-sources');
|
|
5
|
+
const { conditionsOfNode, createTokenKindMatcher, parseTokenValueLength } = require('./token-sources');
|
|
6
6
|
|
|
7
7
|
// Dedicated kinds first: a name like --radius-space-1 is a radius token.
|
|
8
8
|
const TOKEN_KINDS = ['radius', 'typography', 'motion', 'size', 'spacing'].map((kind) => [kind, createTokenKindMatcher(kind)]);
|
|
@@ -70,26 +70,65 @@ function tokenIndexFromDefinitions(definitions, baseFontSize = 16) {
|
|
|
70
70
|
for (const { px, raw, unit } of lengths || []) {
|
|
71
71
|
if (px === 0) continue;
|
|
72
72
|
const file = definition.files ? [...definition.files][0] : null;
|
|
73
|
-
|
|
73
|
+
// A definition built without scopes (an older caller) counts as declared at the root.
|
|
74
|
+
const fixScopes = definition.fixScopes || [{ global: true }];
|
|
75
|
+
index.push({ file: file && file !== 'stylesheet' ? file : null, fixScopes, px, raw, token: definition.token, unit });
|
|
74
76
|
}
|
|
75
77
|
}
|
|
76
78
|
return index;
|
|
77
79
|
}
|
|
78
80
|
|
|
81
|
+
/** The conditions and ancestors of a declaration being fixed, computed once per declaration. */
|
|
82
|
+
const placeCache = new WeakMap();
|
|
83
|
+
function placeOf(decl) {
|
|
84
|
+
if (!placeCache.has(decl)) {
|
|
85
|
+
const ancestors = new Set();
|
|
86
|
+
for (let node = decl.parent; node; node = node.parent) ancestors.add(node);
|
|
87
|
+
placeCache.set(decl, { ancestors, conditions: new Set(conditionsOfNode(decl)) });
|
|
88
|
+
}
|
|
89
|
+
return placeCache.get(decl);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Whether a token is defined where a declaration sits (fix-02). A token
|
|
94
|
+
* declared at the root outside every conditional at-rule is defined
|
|
95
|
+
* everywhere. One declared at the root under `@media`, `@supports` or
|
|
96
|
+
* `@container` is defined only under the same conditions, and one declared in
|
|
97
|
+
* a component block only inside that block. Anywhere else the property would
|
|
98
|
+
* be invalid at computed-value time, so the token is never offered there.
|
|
99
|
+
* Without a declaration (`at` undefined) every token counts.
|
|
100
|
+
*/
|
|
101
|
+
function tokenDefinedAt(entry, at) {
|
|
102
|
+
if (!at || !entry.fixScopes) {
|
|
103
|
+
return true;
|
|
104
|
+
}
|
|
105
|
+
return entry.fixScopes.some((scope) => {
|
|
106
|
+
if (scope.global) return true;
|
|
107
|
+
if (scope.anchor) return placeOf(at).ancestors.has(scope.anchor);
|
|
108
|
+
if (scope.conditions) {
|
|
109
|
+
const { conditions } = placeOf(at);
|
|
110
|
+
return scope.conditions.every((condition) => conditions.has(condition));
|
|
111
|
+
}
|
|
112
|
+
return false;
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
|
|
79
116
|
/**
|
|
80
117
|
* Every custom property that holds a length, for one property. The shared
|
|
81
118
|
* resolver behind use-scale's `fixWith: "token"` and prefer-token, so the two
|
|
82
119
|
* rules always know the same tokens. The px value is signed: 8 finds the
|
|
83
120
|
* tokens that hold 8px, -8 the tokens that hold -8px. Same unit first; with
|
|
84
121
|
* `anyUnit`, a token in another unit that holds the same px value counts when
|
|
85
|
-
* none matches the unit.
|
|
122
|
+
* none matches the unit. With `at`, the declaration being fixed, only the
|
|
123
|
+
* tokens defined where it sits count (see tokenDefinedAt). Sorted, so
|
|
124
|
+
* messages are stable.
|
|
86
125
|
*/
|
|
87
|
-
function tokensForLength(index, px, unit, { anyUnit = false, prop = null } = {}) {
|
|
126
|
+
function tokensForLength(index, px, unit, { anyUnit = false, at = null, prop = null } = {}) {
|
|
88
127
|
const wanted = unit || 'px';
|
|
89
128
|
const sameUnit = new Set();
|
|
90
129
|
const otherUnit = new Set();
|
|
91
130
|
for (const entry of index) {
|
|
92
|
-
if (!entry.token.startsWith('--') || !numbersEqual(entry.px, px) || !tokenFitsProperty(entry.token, prop)) {
|
|
131
|
+
if (!entry.token.startsWith('--') || !numbersEqual(entry.px, px) || !tokenFitsProperty(entry.token, prop) || !tokenDefinedAt(entry, at)) {
|
|
93
132
|
continue;
|
|
94
133
|
}
|
|
95
134
|
(entry.unit === wanted ? sameUnit : otherUnit).add(entry.token);
|
|
@@ -114,8 +153,8 @@ function signedTokensForLength(index, px, unit, options = {}) {
|
|
|
114
153
|
return { negate: px < 0, tokens: tokensForLength(index, Math.abs(px), unit, options) };
|
|
115
154
|
}
|
|
116
155
|
|
|
117
|
-
function tokenForLength(index, px, unit, prop = null) {
|
|
118
|
-
const candidates = tokensForLength(index, px, unit, { prop });
|
|
156
|
+
function tokenForLength(index, px, unit, prop = null, at = null) {
|
|
157
|
+
const candidates = tokensForLength(index, px, unit, { at, prop });
|
|
119
158
|
return candidates.length === 1 ? `var(${candidates[0]})` : null;
|
|
120
159
|
}
|
|
121
160
|
|
|
@@ -135,18 +174,19 @@ function negateReplacement(replacement) {
|
|
|
135
174
|
* options ask for one and exactly one qualifies, otherwise the literal. The
|
|
136
175
|
* nearest value is in px, or in the literal's unit with `unitStrategy:
|
|
137
176
|
* "exact"`; tokens are indexed in px, so the lookup converts it (issue #223).
|
|
138
|
-
* `avoidTokens` are the var() names a fallback literal falls back from
|
|
139
|
-
*
|
|
177
|
+
* `avoidTokens` are the var() names a fallback literal falls back from. A
|
|
178
|
+
* fallback is what renders when tokens are missing, so no token is written
|
|
179
|
+
* into one, the literal is (fix-02; issue #240). `at` is the declaration being
|
|
180
|
+
* fixed: a token not defined there is never written (see tokenDefinedAt).
|
|
140
181
|
*/
|
|
141
|
-
function replacementFor(parsedLength, nearest, options, prop = null, avoidTokens = []) {
|
|
142
|
-
if (options.fixWith === 'token' && options.tokenIndex) {
|
|
182
|
+
function replacementFor(parsedLength, nearest, options, prop = null, avoidTokens = [], at = null) {
|
|
183
|
+
if (options.fixWith === 'token' && options.tokenIndex && avoidTokens.length === 0) {
|
|
143
184
|
const unit = parsedLength.unit || 'px';
|
|
144
185
|
const nearestPx = options.unitStrategy === 'exact' ? toPx(Math.abs(nearest), unit, options.baseFontSize) : Math.abs(nearest);
|
|
145
186
|
if (nearestPx !== null) {
|
|
146
187
|
const signedPx = parsedLength.number < 0 ? -nearestPx : nearestPx;
|
|
147
|
-
const { negate, tokens } = signedTokensForLength(options.tokenIndex, signedPx, unit, { prop });
|
|
148
|
-
|
|
149
|
-
if (tokens.length === 1 && !avoidTokens.includes(tokens[0])) {
|
|
188
|
+
const { negate, tokens } = signedTokensForLength(options.tokenIndex, signedPx, unit, { at, prop });
|
|
189
|
+
if (tokens.length === 1) {
|
|
150
190
|
const token = `var(${tokens[0]})`;
|
|
151
191
|
return negate ? negateReplacement(token) : token;
|
|
152
192
|
}
|
|
@@ -173,6 +213,7 @@ module.exports = {
|
|
|
173
213
|
negateReplacement,
|
|
174
214
|
replacementFor,
|
|
175
215
|
signedTokensForLength,
|
|
216
|
+
tokenDefinedAt,
|
|
176
217
|
tokenFitsProperty,
|
|
177
218
|
tokenHoldsNote,
|
|
178
219
|
tokenForLength,
|