@atlaskit/eslint-plugin-design-system
Version:
The essential plugin for use with the Atlassian Design System.
347 lines (333 loc) • 12.9 kB
JavaScript
import { getSourceCode } from '@atlaskit/eslint-utils/context-compat';
import { findVariable } from '@atlaskit/eslint-utils/find-variable';
import { createLintRule } from '../utils/create-lint-rule';
/**
* Values at or below this are local ordering within a component (a badge over an avatar,
* a sticky header cell). Values above it are reaching for a global win.
*/
const MAX_LOCAL_Z_INDEX = 10;
/**
* Stops runaway resolution of `const a = b; const b = a;` style chains.
*/
const MAX_RESOLVE_DEPTH = 5;
const NUMERIC_STRING = /^\s*([+-]?\d+)\s*(!important)?\s*$/;
const CALC_INFINITY = /^\s*calc\(\s*infinity\s*\)\s*(!important)?\s*$/i;
/**
* Matches `z-index: <value>` inside a CSS string. The value stops at `;`, `}`, or a new line.
* The lookbehind keeps the match index on `z-index`, so reports can point at it.
*/
const CSS_Z_INDEX = /(?<=^|[\s;{])z-index\s*:\s*([^;}\n]*)/gi;
/**
* The static name of a key or string argument: `zIndex`, `'zIndex'`, or `` `zIndex` ``.
*/
const getStaticName = node => {
if (node.type === 'Identifier') {
return node.name;
}
if (node.type === 'Literal' && typeof node.value === 'string') {
return node.value;
}
if (node.type === 'TemplateLiteral' && node.expressions.length === 0) {
var _node$quasis$0$value$;
return (_node$quasis$0$value$ = node.quasis[0].value.cooked) !== null && _node$quasis$0$value$ !== void 0 ? _node$quasis$0$value$ : null;
}
return null;
};
const isZIndexName = name => name === 'zIndex' || name === 'z-index';
const parseCssValue = text => {
if (CALC_INFINITY.test(text)) {
return {
value: Infinity,
label: 'calc(infinity)'
};
}
const match = NUMERIC_STRING.exec(text);
if (!match) {
return null;
}
const value = Number(match[1]);
return {
value,
label: String(value)
};
};
const getRange = node => {
var _withRange$range, _withRange$start, _withRange$end;
const withRange = node;
return (_withRange$range = withRange.range) !== null && _withRange$range !== void 0 ? _withRange$range : [(_withRange$start = withRange.start) !== null && _withRange$start !== void 0 ? _withRange$start : 0, (_withRange$end = withRange.end) !== null && _withRange$end !== void 0 ? _withRange$end : 0];
};
/**
* `expect(el).toHaveStyle({ zIndex: 700 })` asserts on a value, it doesn't set one.
*/
const isInExpectCall = node => {
let outermost = node;
while (((_outermost$parent = outermost.parent) === null || _outermost$parent === void 0 ? void 0 : _outermost$parent.type) === 'Property' && ((_outermost$parent$par = outermost.parent.parent) === null || _outermost$parent$par === void 0 ? void 0 : _outermost$parent$par.type) === 'ObjectExpression' || ((_outermost$parent2 = outermost.parent) === null || _outermost$parent2 === void 0 ? void 0 : _outermost$parent2.type) === 'ObjectExpression') {
var _outermost$parent, _outermost$parent$par, _outermost$parent2;
outermost = outermost.parent;
}
const call = outermost.parent;
if ((call === null || call === void 0 ? void 0 : call.type) !== 'CallExpression' || !call.arguments.includes(outermost)) {
return false;
}
let callee = call.callee;
while (callee.type === 'MemberExpression' || callee.type === 'CallExpression') {
if (callee.type === 'CallExpression' && callee.callee.type === 'Identifier' && callee.callee.name === 'expect') {
return true;
}
callee = callee.type === 'MemberExpression' ? callee.object : callee.callee;
}
// `expect.objectContaining({ zIndex: 700 })`
return callee.type === 'Identifier' && callee.name === 'expect';
};
/**
* Resolves a node to the numbers it can be, where that is knowable from the file alone.
* Anything that can't be resolved (imports, function calls, `calc()`) is skipped.
*/
const resolveValues = (node, context, depth = 0) => {
if (depth > MAX_RESOLVE_DEPTH) {
return [];
}
switch (node.type) {
case 'Literal':
{
const {
value
} = node;
if (typeof value === 'number') {
return [{
node,
value,
label: String(value)
}];
}
if (typeof value === 'string') {
const parsed = parseCssValue(value);
return parsed ? [{
node,
...parsed
}] : [];
}
return [];
}
case 'TemplateLiteral':
{
var _template$quasis$0$va;
const template = node;
if (template.expressions.length > 0) {
return [];
}
const parsed = parseCssValue((_template$quasis$0$va = template.quasis[0].value.cooked) !== null && _template$quasis$0$va !== void 0 ? _template$quasis$0$va : '');
return parsed ? [{
node,
...parsed
}] : [];
}
case 'UnaryExpression':
{
const unary = node;
if (unary.operator !== '-' && unary.operator !== '+') {
return [];
}
const sign = unary.operator === '-' ? -1 : 1;
return resolveValues(unary.argument, context, depth + 1).map(found => {
const value = sign * found.value;
return {
node,
value,
label: Number.isFinite(value) ? String(value) : found.label
};
});
}
case 'ConditionalExpression':
{
const conditional = node;
return [...resolveValues(conditional.consequent, context, depth + 1), ...resolveValues(conditional.alternate, context, depth + 1)];
}
case 'LogicalExpression':
{
const logical = node;
// `a && 500` can only be 500 (or a falsy `a`, which isn't a z-index)
if (logical.operator === '&&') {
return resolveValues(logical.right, context, depth + 1);
}
// `options.zIndex ?? 1000` and `options.zIndex || 200` can be either side
return [...resolveValues(logical.left, context, depth + 1), ...resolveValues(logical.right, context, depth + 1)];
}
case 'TSAsExpression':
case 'TSSatisfiesExpression':
case 'TSNonNullExpression':
case 'TSTypeAssertion':
return resolveValues(node.expression, context, depth);
case 'Identifier':
{
var _definition$parent;
const variable = findVariable({
identifier: node,
sourceCode: getSourceCode(context)
});
const definition = (variable === null || variable === void 0 ? void 0 : variable.defs.length) === 1 ? variable.defs[0] : undefined;
if (!definition || definition.type !== 'Variable' || ((_definition$parent = definition.parent) === null || _definition$parent === void 0 ? void 0 : _definition$parent.kind) !== 'const' || definition.node.id.type !== 'Identifier' || !definition.node.init) {
return [];
}
// Report on the usage, not the declaration, so the message lands where z-index is set
return resolveValues(definition.node.init, context, depth + 1).map(found => ({
...found,
node
}));
}
default:
return [];
}
};
const rule = createLintRule({
meta: {
name: 'no-global-z-index',
type: 'problem',
docs: {
description: 'Disallow `z-index` values above 10. Global layer ordering is handled by the browser top layer.',
recommended: false,
severity: 'warn'
},
messages: {
noGlobalZIndex: "`z-index: {{value}}` looks like it competes in the global stack. Top layer surfaces ignore `z-index`, so this ordering won't hold against them. Use a Design System layering component or `@atlaskit/top-layer`. Values of 10 or less are fine for local ordering."
}
},
create(context) {
const sourceCode = getSourceCode(context);
const reportValues = node => {
for (const found of resolveValues(node, context)) {
if (found.value > MAX_LOCAL_Z_INDEX) {
context.report({
node: found.node,
messageId: 'noGlobalZIndex',
data: {
value: found.label
}
});
}
}
};
return {
// css({ zIndex: 500 }), styled.div({ zIndex: 500 }), style={{ zIndex: 500 }},
// react-select `styles` overrides, and any other object style
Property(node) {
if (node.type !== 'Property' || node.parent.type !== 'ObjectExpression') {
return;
}
// Getters and methods named `zIndex` compute a value we can't know
if (node.kind !== 'init' || node.method) {
return;
}
// `{ [key]: 500 }` is a variable lookup, not a `zIndex` property
if (node.computed && node.key.type === 'Identifier') {
return;
}
if (!isZIndexName(getStaticName(node.key))) {
return;
}
if (isInExpectCall(node.parent)) {
return;
}
reportValues(node.value);
},
// <Portal zIndex={500} />
JSXAttribute(node) {
const attribute = node;
if (attribute.name.type !== 'JSXIdentifier' || attribute.name.name !== 'zIndex') {
return;
}
if (!attribute.value) {
return;
}
if (attribute.value.type === 'JSXExpressionContainer') {
reportValues(attribute.value.expression);
return;
}
reportValues(attribute.value);
},
// element.style.zIndex = '9999'
AssignmentExpression(node) {
if (node.type !== 'AssignmentExpression' || node.operator !== '=' || node.left.type !== 'MemberExpression') {
return;
}
const {
object,
property,
computed
} = node.left;
// `style[key]` is a variable lookup, not a `zIndex` property
if (computed && property.type === 'Identifier') {
return;
}
if (!isZIndexName(getStaticName(property))) {
return;
}
// Only `<something>.style.zIndex`. Other `.zIndex` writes are not CSS.
if (object.type !== 'MemberExpression' || object.computed && object.property.type === 'Identifier' || getStaticName(object.property) !== 'style') {
return;
}
reportValues(node.right);
},
// element.style.setProperty('z-index', '9999')
CallExpression(node) {
if (node.type !== 'CallExpression' || node.callee.type !== 'MemberExpression' || node.callee.property.type !== 'Identifier' || node.callee.property.name !== 'setProperty') {
return;
}
const [name, value] = node.arguments;
if (!name || !value || name.type === 'SpreadElement' || value.type === 'SpreadElement' || getStaticName(name) !== 'z-index') {
return;
}
reportValues(value);
},
// css`z-index: 500;`, styled.div`z-index: ${Z};`, createGlobalStyle`...`
TaggedTemplateExpression(node) {
if (node.type !== 'TaggedTemplateExpression') {
return;
}
const {
quasis,
expressions
} = node.quasi;
quasis.forEach((quasi, index) => {
const text = quasi.value.raw;
const isLastQuasi = index === quasis.length - 1;
// Where `text` starts in the file. Parsers differ on whether the quasi's range
// includes the `` ` ``, `${` and `}` delimiters, so find it in the quasi's own text.
const [quasiStart] = getRange(quasi);
const textStart = quasiStart + sourceCode.getText(quasi).indexOf(text);
for (const match of text.matchAll(CSS_Z_INDEX)) {
var _match$index;
const valueText = match[1];
const matchIndex = (_match$index = match.index) !== null && _match$index !== void 0 ? _match$index : 0;
const endsQuasi = matchIndex + match[0].length === text.length;
// `z-index: ${value}` — the value is the next expression
if (endsQuasi && !isLastQuasi && valueText.trim() === '') {
reportValues(expressions[index]);
continue;
}
// `z-index: 1${x}` — the value runs into an expression, so we can't know it
if (endsQuasi && !isLastQuasi) {
continue;
}
const parsed = parseCssValue(valueText);
if (parsed && parsed.value > MAX_LOCAL_Z_INDEX) {
const start = textStart + matchIndex;
const end = start + match[0].trimEnd().length;
context.report({
loc: {
start: sourceCode.getLocFromIndex(start),
end: sourceCode.getLocFromIndex(end)
},
messageId: 'noGlobalZIndex',
data: {
value: parsed.label
}
});
}
}
});
}
};
}
});
export default rule;