added z-index soft scale

.nx/version-plans/version-plan-1784663569372.md

@@ -0,0 +1,8 @@
+---
+eslint-plugin-gamut: minor
+gamut-styles: major
+variance: minor
+gamut: major
+---
+
+Adding new zIndex scale to Gamut. Inclues a new eslint rule for avoiding raw z-index values. Allows variance scales to include raw values if need be.

packages/eslint-plugin-gamut/src/index.tsx

@@ -2,6 +2,7 @@ import gamutImportPaths from './gamut-import-paths';
 import noCssStandalone from './no-css-standalone';
 import noInlineStyle from './no-inline-style';
 import noKbdElement from './no-kbd-element';
+import noRawZIndex from './no-raw-z-index';
 import preferThemed from './prefer-themed';
 import recommended from './recommended';
 
@@ -10,6 +11,7 @@ const rules = {
   'no-css-standalone': noCssStandalone,
   'no-inline-style': noInlineStyle,
   'no-kbd-element': noKbdElement,
+  'no-raw-z-index': noRawZIndex,
   'prefer-themed': preferThemed,
 };
 

packages/eslint-plugin-gamut/src/no-raw-z-index.test.ts

@@ -0,0 +1,55 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+import rule from './no-raw-z-index';
+
+const ruleTester = new ESLintUtils.RuleTester({
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+});
+
+ruleTester.run('no-raw-z-index', rule, {
+  valid: [
+    // Semantic tokens are the expected usage.
+    `const styles = { zIndex: zIndexes.modal };`,
+    `<Box zIndex={zIndexes.stickyHeader} />;`,
+    // Arithmetic on a token is allowed (e.g. Tip's shadow).
+    `const styles = { zIndex: zIndexes.foreground - 2 };`,
+    `<Box zIndex={zIndexes.modal + 5} />;`,
+    // Variables / non-literal expressions are not flagged.
+    `<Box zIndex={zIndex} />;`,
+    `const styles = { zIndex };`,
+    // Unrelated properties.
+    `const styles = { padding: 0 };`,
+    `<Box top={0} />;`,
+  ],
+  invalid: [
+    {
+      code: `const styles = { zIndex: 1 };`,
+      errors: [{ messageId: 'noRawZIndex' }],
+    },
+    {
+      code: `const styles = { zIndex: 0 };`,
+      errors: [{ messageId: 'noRawZIndex' }],
+    },
+    {
+      code: `const styles = { zIndex: -1 };`,
+      errors: [{ messageId: 'noRawZIndex' }],
+    },
+    {
+      code: `const styles = { 'z-index': 100 };`,
+      errors: [{ messageId: 'noRawZIndex' }],
+    },
+    {
+      code: `<Box zIndex={2} />;`,
+      errors: [{ messageId: 'noRawZIndex' }],
+    },
+    {
+      code: `<Box zIndex={-1} />;`,
+      errors: [{ messageId: 'noRawZIndex' }],
+    },
+  ],
+});

packages/eslint-plugin-gamut/src/no-raw-z-index.ts

@@ -0,0 +1,62 @@
+import { AST_NODE_TYPES, TSESTree } from '@typescript-eslint/utils';
+
+import { createRule } from './createRule';
+
+/**
+ * True for a numeric literal, including a negated one like `-1`.
+ */
+const isNumericLiteral = (node: TSESTree.Node | null | undefined): boolean => {
+  if (!node) return false;
+  if (node.type === AST_NODE_TYPES.Literal && typeof node.value === 'number') {
+    return true;
+  }
+  return (
+    node.type === AST_NODE_TYPES.UnaryExpression &&
+    (node.operator === '-' || node.operator === '+') &&
+    isNumericLiteral(node.argument)
+  );
+};
+
+const isZIndexKey = (key: TSESTree.Node): boolean =>
+  (key.type === AST_NODE_TYPES.Identifier && key.name === 'zIndex') ||
+  (key.type === AST_NODE_TYPES.Literal && key.value === 'zIndex') ||
+  (key.type === AST_NODE_TYPES.Literal && key.value === 'z-index');
+
+export default createRule({
+  create(context) {
+    return {
+      // Style objects: `{ zIndex: 1 }` / `{ 'z-index': 1 }`
+      Property(node) {
+        if (isZIndexKey(node.key) && isNumericLiteral(node.value)) {
+          context.report({ messageId: 'noRawZIndex', node: node.value });
+        }
+      },
+      // JSX props: `<Box zIndex={1} />`
+      JSXAttribute(node) {
+        if (
+          node.name.type === AST_NODE_TYPES.JSXIdentifier &&
+          node.name.name === 'zIndex' &&
+          node.value?.type === AST_NODE_TYPES.JSXExpressionContainer &&
+          isNumericLiteral(node.value.expression as TSESTree.Node)
+        ) {
+          context.report({ messageId: 'noRawZIndex', node: node.value });
+        }
+      },
+    };
+  },
+  defaultOptions: [],
+  meta: {
+    docs: {
+      description:
+        'Discourage raw numeric z-index values which can lead to z-index stacking issues and encourage usage of semantic tokens from the `zIndexes` scale.',
+      recommended: 'error',
+    },
+    messages: {
+      noRawZIndex:
+        'Semantic tokens from the `zIndexes` scale (e.g. `zIndexes.modal`) are recommendedinstead of a raw z-index number. For a deliberate in-between value, disable this rule inline with a justifying comment.',
+    },
+    type: 'suggestion',
+    schema: [],
+  },
+  name: 'no-raw-z-index',
+});

packages/eslint-plugin-gamut/src/recommended.ts

@@ -2,6 +2,7 @@ export default {
   rules: {
     'gamut/no-css-standalone': 'error',
     'gamut/no-inline-style': 'error',
+    'gamut/no-raw-z-index': 'error',
     'gamut/prefer-themed': 'off',
     'gamut/gamut-import-paths': 'error',
   },