UNPKG

@atlaskit/eslint-plugin-design-system

Version:

The essential plugin for use with the Atlassian Design System.

347 lines (333 loc) • 12.9 kB
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;