Merge pull request #972 from primer/variables-page

Variables page

.gitignore

@@ -1,14 +1,15 @@
 *.log
 *.tgz
 .DS_Store
-.changelog
+.cache/
+.changelog/
 .next/
 .sass-cache
-.stylelintcache
 .storybuild/
+.stylelintcache
 _site
 dist/
+docs/dist
 node_modules/
-searchIndex.js
-.cache/
 public/
+searchIndex.js

.nowignore

@@ -0,0 +1,5 @@
+.*.sw?
+.changelog/
+dist/
+docs/dist
+docs/public/

docs/.eslintrc.json

@@ -13,5 +13,8 @@
     "react": {
       "version": "detect"
     }
+  },
+  "globals": {
+    "__DEV__": "readonly"
   }
 }

docs/content/support/variables.mdx

@@ -0,0 +1,16 @@
+---
+title: Variables
+path: support/variables
+status: Experimental
+bundle: alerts
+---
+
+import {Variables, DeprecationIcon} from '../../src/variables'
+
+<Variables>
+
+The tables below list all of the global SCSS variables defined in [the `support/variables` directory](https://github.com/primer/css/tree/master/src/support/variables).
+
+Variables with a <DeprecationIcon /> are planned for [deprecation](../tools/deprecations) in a future version of `@primer/css`, and should be avoided.
+
+</Variables>

docs/gatsby-node.js

@@ -0,0 +1,12 @@
+exports.onCreateWebpackConfig = ({actions, stage, plugins}) => {
+  actions.setWebpackConfig({
+    node: {
+      fs: 'empty'
+    },
+    plugins: [
+      plugins.define({
+        __DEV__: stage === 'develop' || stage === 'develop-html'
+      })
+    ]
+  })
+}

docs/package-lock.json

@@ -1,8 +1,7 @@
 {
   "name": "docs",
-  "version": "1.0.0",
-  "lockfileVersion": 1,
   "requires": true,
+  "lockfileVersion": 1,
   "dependencies": {
     "@babel/code-frame": {
       "version": "7.5.5",
@@ -1449,11 +1448,6 @@
         }
       }
     },
-    "@primer/css": {
-      "version": "12.5.0",
-      "resolved": "https://registry.npmjs.org/@primer/css/-/css-12.5.0.tgz",
-      "integrity": "sha512-MyA2hoCY3UAmMKPHPN+LM1HrwGz5VR92fkEkIzAQgHBYMPstT77tjHkO8OPoWW//DShdYMYAgukZdMJ8lnsfbg=="
-    },
     "@primer/gatsby-theme-doctocat": {
       "version": "0.15.0",
       "resolved": "https://registry.npmjs.org/@primer/gatsby-theme-doctocat/-/gatsby-theme-doctocat-0.15.0.tgz",
@@ -6247,11 +6241,18 @@
       }
     },
     "eslint-utils": {
-      "version": "1.4.0",
-      "resolved": "https://registry.npmjs.org/eslint-utils/-/eslint-utils-1.4.0.tgz",
-      "integrity": "sha512-7ehnzPaP5IIEh1r1tkjuIrxqhNkzUJa9z3R92tLJdZIVdWaczEhr3EbhGtsMrVxi1KeR8qA7Off6SWc5WNQqyQ==",
+      "version": "1.4.3",
+      "resolved": "https://registry.npmjs.org/eslint-utils/-/eslint-utils-1.4.3.tgz",
+      "integrity": "sha512-fbBN5W2xdY45KulGXmLHZ3c3FHfVYmKg0IrAKGOkT/464PQsx2UeIzfz1RmEci+KLm1bBaAzZAh8+/E+XAeZ8Q==",
       "requires": {
-        "eslint-visitor-keys": "^1.0.0"
+        "eslint-visitor-keys": "^1.1.0"
+      },
+      "dependencies": {
+        "eslint-visitor-keys": {
+          "version": "1.1.0",
+          "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-1.1.0.tgz",
+          "integrity": "sha512-8y9YjtM1JBJU/A9Kc+SbaOV4y29sSWckBwMHa+FGtVj5gN/sbnKDf6xJUl+8g7FAij9LVaP8C24DUiH/f/2Z9A=="
+        }
       }
     },
     "eslint-visitor-keys": {
@@ -9138,9 +9139,9 @@
       "integrity": "sha512-d4sze1JNC454Wdo2fkuyzCr6aHcbL6PGGuFAz0Li/NcOm1tCHGnWDRmJP85dh9IhQErTc2svWFEX5xHIOo//kQ=="
     },
     "handlebars": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.2.0.tgz",
-      "integrity": "sha512-Kb4xn5Qh1cxAKvQnzNWZ512DhABzyFNmsaJf3OAkWNa4NkaqWcNI8Tao8Tasi0/F4JD9oyG0YxuFyvyR57d+Gw==",
+      "version": "4.5.2",
+      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.5.2.tgz",
+      "integrity": "sha512-29Zxv/cynYB7mkT1rVWQnV7mGX6v7H/miQ6dbEpYTKq5eJBN7PsRB+ViYJlcT6JINTSu4dVB9kOqEun78h6Exg==",
       "requires": {
         "neo-async": "^2.6.0",
         "optimist": "^0.6.1",
@@ -17924,15 +17925,21 @@
       "integrity": "sha512-8OaIKfzL5cpx8eCMAhhvTlft8GYF8b2eQr6JkCyVdrgjcytyOmPCXrqXFcUnhonRpLlh5yxEZVohm6mzaowUOw=="
     },
     "uglify-js": {
-      "version": "3.6.0",
-      "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.6.0.tgz",
-      "integrity": "sha512-W+jrUHJr3DXKhrsS7NUVxn3zqMOFn0hL/Ei6v0anCIMoKC93TjcflTagwIHLW7SfMFfiQuktQyFVCFHGUE0+yg==",
+      "version": "3.6.9",
+      "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.6.9.tgz",
+      "integrity": "sha512-pcnnhaoG6RtrvHJ1dFncAe8Od6Nuy30oaJ82ts6//sGSXOP5UjBMEthiProjXmMNHOfd93sqlkztifFMcb+4yw==",
       "optional": true,
       "requires": {
-        "commander": "~2.20.0",
+        "commander": "~2.20.3",
         "source-map": "~0.6.1"
       },
       "dependencies": {
+        "commander": {
+          "version": "2.20.3",
+          "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz",
+          "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
+          "optional": true
+        },
         "source-map": {
           "version": "0.6.1",
           "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",

docs/package.json

@@ -1,18 +1,16 @@
 {
-  "name": "docs",
   "private": true,
-  "version": "1.0.0",
-  "license": "MIT",
+  "name": "docs",
+  "repository": "primer/css",
   "scripts": {
     "clean": "gatsby clean",
-    "develop": "gatsby develop -H 0.0.0.0",
-    "build": "gatsby build --prefix-paths",
-    "now-build": "npm run build"
+    "develop": "ln -sf ../dist . && gatsby develop -H 0.0.0.0",
+    "build-content": "gatsby build --prefix-paths",
+    "build": "./script/now-build.sh"
   },
   "dependencies": {
     "@loadable/component": "^5.10.2",
     "@primer/components": "^13.2.0",
-    "@primer/css": "^12.4.1",
     "@primer/gatsby-theme-doctocat": "^0.15.0",
     "@primer/octicons": "^9.1.1",
     "@primer/octicons-react": "^9.1.1",
@@ -36,5 +34,7 @@
     "styled-components": "^4.3.2",
     "title-case": "^2.1.1"
   },
-  "repository": "primer/css"
+  "engines": {
+    "node": "12.x"
+  }
 }

docs/script/now-build.sh

@@ -0,0 +1,12 @@
+#!/bin/bash -e
+
+# Build the base project so we can pull out the JSON data
+cd ..
+npm ci
+npm run dist
+cp -rf dist docs
+
+# Now build the docs site using that data
+cd docs
+npm ci
+CI=true npm run build-content

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -16,6 +16,8 @@
       url: /support/typography
     - title: Marketing support
       url: /support/marketing-variables
+    - title: Variables
+      url: /support/variables
 - title: Utilities
   url: /utilities
   children:

docs/src/variables.js

@@ -0,0 +1,206 @@
+import React from 'react'
+import {Flex, Link, Text, Tooltip, Flash} from '@primer/components'
+import Octicon, {Alert} from '@primer/octicons-react'
+import themeGet from '@styled-system/theme-get'
+import DoctocatTable from '@primer/gatsby-theme-doctocat/src/components/table'
+import styled from 'styled-components'
+
+const Table = styled(DoctocatTable)`
+  font-size: ${themeGet('fontSizes.1')}px;
+
+  td,
+  th {
+    text-align: left;
+    vertical-align: top;
+  }
+
+  tr:target {
+    th,
+    td {
+      background-color: ${themeGet('colors.yellow.0')};
+    }
+  }
+`
+
+function useVariables() {
+  const deprecations = useDeprecations()
+
+  return React.useMemo(() => {
+    let variablesByFile = new Map()
+
+    try {
+      const variables = require('../dist/variables.json')
+
+      for (const name of Object.keys(variables)) {
+        if (name.endsWith('-font')) {
+          delete variables[name]
+        }
+      }
+
+      variablesByFile = Object.entries(variables).reduce((map, [name, variable]) => {
+        const {
+          source: {path}
+        } = variable
+
+        variable.name = name
+        variable.deprecated = deprecations.variables.hasOwnProperty(name)
+
+        if (map.has(path)) {
+          map.get(path).push(variable)
+        } else {
+          map.set(path, [variable])
+        }
+
+        return map
+      }, variablesByFile)
+
+      for (const variables of variablesByFile.values()) {
+        variables.sort((a, b) => {
+          return a.deprecated - b.deprecated || a.source.line - b.source.line
+        })
+      }
+    } catch (err) {
+      // do nothing
+    }
+
+    return variablesByFile
+  }, [])
+}
+
+function useDeprecations() {
+  return React.useMemo(() => {
+    try {
+      const deprecations = require('../dist/deprecations.json')
+      return deprecations
+    } catch (err) {
+      return {}
+    }
+  }, [])
+}
+
+function Variables({children, ...props}) {
+  const variablesByFile = useVariables()
+
+  if (variablesByFile.size === 0) {
+    return (
+      <>
+        <h2>No data available</h2>
+        {__DEV__ && (
+          <Flash scheme="red">
+            This probably means that the root project has not been built; run `npm run dist` and restart your
+            development server.
+          </Flash>
+        )}
+      </>
+    )
+  }
+
+  return (
+    <>
+      {children}
+      <VariablesDetails variablesByFile={variablesByFile} {...props} />
+    </>
+  )
+}
+
+function VariablesDetails({variablesByFile, ...props}) {
+  return Array.from(variablesByFile.entries()).map(([path, variables]) => (
+    <React.Fragment key={path}>
+      <h3>
+        Defined in <Link href={`https://github.com/primer/css/tree/master/${path}`}>{path}</Link>
+      </h3>
+      <Table {...props}>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Value</th>
+            <th>Aliases</th>
+          </tr>
+        </thead>
+        <tbody>
+          {variables.map(({name, computed, source, refs}) => (
+            <tr id={name} key={name}>
+              <th scope="row">
+                <Flex justifyContent="space-between">
+                  <Link href={`#${name}`} color="gray.4" mr={2}>
+                    #
+                  </Link>
+                  <Flex.Item flex="1">
+                    <Link href={`https://github.com/primer/css/tree/master/${source.path}#L${source.line}`}>
+                      <Mono nowrap>{name}</Mono>
+                    </Link>
+                  </Flex.Item>
+                  <Flex.Item justifySelf="end">
+                    <DeprecationFlag variable={name} ml={2} />
+                  </Flex.Item>
+                </Flex>
+              </th>
+              <td>
+                <Swatch value={computed} mr={2} />
+                <Mono nowrap>{computed}</Mono>
+              </td>
+              <td>
+                <RefList refs={refs} />
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </Table>
+    </React.Fragment>
+  ))
+}
+
+function Mono({nowrap, ...rest}) {
+  return <Text fontFamily="mono" css={nowrap ? {whiteSpace: 'nowrap'} : null} {...rest} />
+}
+
+function Swatch({value, ...rest}) {
+  return /^(#|rgb|hsl)/.test(value) ? <SwatchBox {...rest} bg={value} /> : null
+}
+
+const SwatchBox = styled(Text)`
+  display: inline-block;
+  vertical-align: baseline;
+  width: ${p => p.size};
+  height: ${p => p.size};
+  border: 1px solid ${themeGet('colors.gray.3')};
+  border-radius: ${themeGet('radii.1')}px;
+  margin-bottom: -2px;
+`
+
+Swatch.defaultProps = {
+  size: '1em'
+}
+
+function RefList({refs}) {
+  const last = refs.length - 1
+  return refs.map((ref, i) => [
+    <Link href={`#${ref}`} key={ref}>
+      <Mono nowrap>{ref}</Mono>
+    </Link>,
+    i < last ? ', ' : ''
+  ])
+}
+
+function DeprecationFlag({variable, ...rest}) {
+  const deprecations = useDeprecations()
+
+  const dep = deprecations.variables[variable]
+  return dep ? (
+    <Text {...rest}>
+      <Tooltip aria-label={`Deprecation planned in version ${dep.version} (${dep.message})`}>
+        <DeprecationIcon />
+      </Tooltip>
+    </Text>
+  ) : null
+}
+
+function DeprecationIcon() {
+  return (
+    <Text color="red.5">
+      <Octicon icon={Alert} />
+    </Text>
+  )
+}
+
+export {Variables, DeprecationIcon}