adds first draft of primer/box-shadow plugin

Author: mperrotti

__tests__/box-shadow.js

@@ -1,30 +1,53 @@
-import dedent from 'dedent'
-import stylelint from 'stylelint'
-import pluginPath from '../plugins/box-shadow.js'
+import plugin from '../plugins/box-shadow.js'
 
-const ruleName = 'primer/box-shadow'
-const configWithOptions = args => ({
-  plugins: [pluginPath],
-  rules: {
-    [ruleName]: args,
-  },
-})
+const plugins = [plugin]
+const {
+  ruleName,
+  rule: {messages},
+} = plugin
 
-describe(ruleName, () => {
-  it('does not report properties with valid shadow', () => {
-    return stylelint
-      .lint({
-        code: dedent`
-          .x { box-shadow: var(--color-shadow-primary); }
-          .y { box-shadow: var(--color-btn-shadow-hover); }
-          .z { box-shadow: var(--color-diff-deletion-shadow); }
-          .a { box-shadow: var(--color-shadow); }
-        `,
-        config: configWithOptions(true),
-      })
-      .then(data => {
-        expect(data).not.toHaveErrored()
-        expect(data).toHaveWarningsLength(0)
-      })
-  })
+// General Tests
+testRule({
+  plugins,
+  ruleName,
+  config: [true, {}],
+  fix: true,
+  cache: false,
+  accept: [
+    {
+      code: '.x { box-shadow: var(--shadow-resting-medium); }',
+      description: 'CSS > Accepts box shadow variables',
+    },
+  ],
+  reject: [
+    {
+      code: '.x { box-shadow: 1px 2px 3px 4px #000000; }',
+      unfixable: true,
+      message: messages.rejected('1px 2px 3px 4px #000000'),
+      line: 1,
+      column: 18,
+      endColumn: 41,
+      description: 'CSS > Errors on value not in box-shadow list',
+    },
+    // Light mode shadow replacement
+    {
+      code: '.x { box-shadow: 0px 3px 6px 0px #424a531f; }',
+      fixed: '.x { box-shadow: var(--shadow-resting-medium); }',
+      message: messages.rejected('0px 3px 6px 0px #424a531f', {name: '--shadow-resting-medium'}),
+      line: 1,
+      column: 18,
+      endColumn: 43,
+      description: "CSS > Replaces '0px 3px 6px 0px #424a531f' with 'var(--shadow-resting-medium)'.",
+    },
+    // Dark mode shadow replacement
+    {
+      code: '.x { box-shadow: 0px 3px 6px 0px #010409cc; }',
+      fixed: '.x { box-shadow: var(--shadow-resting-medium); }',
+      message: messages.rejected('0px 3px 6px 0px #010409cc', {name: '--shadow-resting-medium'}),
+      line: 1,
+      column: 18,
+      endColumn: 43,
+      description: "CSS > Replaces '0px 3px 6px 0px #010409cc' with 'var(--shadow-resting-medium)'.",
+    },
+  ],
 })

plugins/box-shadow.js

@@ -1,22 +1,102 @@
-import {createVariableRule} from './lib/variable-rules.js'
-
-export default createVariableRule(
-  'primer/box-shadow',
-  {
-    'box shadow': {
-      expects: 'a box-shadow variable',
-      props: 'box-shadow',
-      values: [
-        '$box-shadow*',
-        '$*-shadow',
-        'none',
-        // Match variables in any of the following formats: --color-shadow-*, --color-*-shadow-*, --color-*-shadow, --shadow-*, *shadow*
-        /var\(--color-(.+-)*shadow(-.+)*\)/,
-        /var\(--shadow(-.+)*\)/,
-        /var\((.+-)*shadow(-.+)*\)/,
-      ],
-      singular: true,
-    },
+import stylelint from 'stylelint'
+import declarationValueIndex from 'stylelint/lib/utils/declarationValueIndex.cjs'
+import {primitivesVariables} from './lib/utils.js'
+
+const {
+  createPlugin,
+  utils: {report, ruleMessages, validateOptions},
+} = stylelint
+
+export const ruleName = 'primer/box-shadow'
+export const messages = ruleMessages(ruleName, {
+  rejected: (value, replacement) => {
+    // TODO: Decide if we just want to link to Storybook, or if we want to add new pages to https://primer.style/foundations/primitives
+    if (!replacement) {
+      return `Please use a Primer box-shadow variable instead of '${value}'. Consult the primer docs for a suitable replacement. https://primer.style/primitives/storybook/?path=/story/color-functional-shadows--shadows`
+    }
+
+    return `Please replace '${value}' with a Primer box-shadow variable '${replacement['name']}'. https://primer.style/primitives/storybook/?path=/story/color-functional-shadows--shadows`
   },
-  'https://primer.style/css/utilities/box-shadow',
-)
+})
+
+const variables = primitivesVariables('box-shadow')
+const shadows = []
+
+for (const variable of variables) {
+  const name = variable['name']
+
+  // TODO: Decide if this is safe. Someday we might have variables that
+  // have 'shadow' in the name but aren't full box-shadows.
+  if (name.includes('shadow')) {
+    shadows.push(variable)
+  }
+}
+
+console.log(shadows)
+
+/** @type {import('stylelint').Rule} */
+const ruleFunction = (primary, secondaryOptions, context) => {
+  return (root, result) => {
+    const validOptions = validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    })
+    const validValues = shadows
+
+    if (!validOptions) return
+
+    // TODO: determine if it's safe to look at the whole declaration value
+    // instead of each node in the value
+    root.walkDecls(declNode => {
+      const {prop, value} = declNode
+
+      if (prop !== 'box-shadow') return
+
+      const problems = []
+
+      const checkForVariable = (vars, nodeValue) => {
+
+        return vars.some(variable =>
+          new RegExp(`${variable['name'].replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(nodeValue),
+        )
+      }
+
+      if (checkForVariable(validValues, value)) {
+        return
+      }
+
+      const replacement = validValues.find(variable => variable.values.includes(value))
+
+      if (replacement && context.fix) {
+        declNode.value = value.replace(value, `var(${replacement['name']})`)
+      } else {
+        problems.push({
+          index: declarationValueIndex(declNode),
+          endIndex: declarationValueIndex(declNode) + value.length,
+          message: messages.rejected(value, replacement),
+        })
+      }
+
+      if (problems.length) {
+        for (const err of problems) {
+          report({
+            index: err.index,
+            endIndex: err.endIndex,
+            message: err.message,
+            node: declNode,
+            result,
+            ruleName,
+          })
+        }
+      }
+    })
+  }
+}
+
+ruleFunction.ruleName = ruleName
+ruleFunction.messages = messages
+ruleFunction.meta = {
+  fixable: true,
+}
+
+export default createPlugin(ruleName, ruleFunction)

plugins/lib/utils.js

@@ -0,0 +1,53 @@
+import {createRequire} from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+export function primitivesVariables(type) {
+  const variables = []
+
+  const files = []
+  switch (type) {
+    case 'spacing':
+      files.push('base/size/size.json')
+      break
+    case 'border':
+      files.push('functional/size/border.json')
+      break
+    case 'typography':
+      files.push('base/typography/typography.json')
+      files.push('functional/typography/typography.json')
+      break
+    case 'box-shadow':
+      files.push('functional/themes/dark.json')
+      files.push('functional/themes/light.json')
+      break
+}
+
+  for (const file of files) {
+    // eslint-disable-next-line import/no-dynamic-require
+    const data = require(`@primer/primitives/dist/styleLint/${file}`)
+
+    for (const key of Object.keys(data)) {
+      const size = data[key]
+      const values = typeof size['value'] === 'string' ? [size['value']] : size['value']
+
+      variables.push({
+        name: `--${size['name']}`,
+        values,
+      })
+    }
+  }
+
+  return variables
+}
+
+export function walkGroups(root, validate) {
+  for (const node of root.nodes) {
+    if (node.type === 'function') {
+      walkGroups(node, validate)
+    } else {
+      validate(node)
+    }
+  }
+  return root
+}