Merge pull request #370 from primer/v2

Octicons v2 👀
primer · Jun 10, 2020 · dbf02d1 · dbf02d1 · vercel · Jun 10, 2020
2 parents 12fb159 + 8e7b0cd
commit dbf02d1
Show file tree

Hide file tree

Showing 675 changed files with 16,993 additions and 1,229 deletions.
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
@@ -107,8 +107,15 @@ jobs:
         with:
           name: octicons
           path: ./lib/build
-      - uses: ./.github/actions/build_node
+      - name: Build @primer/octicons-react
+        uses: ./.github/actions/build_node
         env:
           NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
         with:
           args: octicons_react
+      - name: Build @primer/styled-octicons
+        uses: ./.github/actions/build_node
+        env:
+          NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
+        with:
+          args: octicons_styled
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -31,7 +31,7 @@ The octicons node.js library is the main JavaScript library. With [a JavaScript
 
 ### Request a new icon
 
-To request a new icon, open an issue using the [icon request](https://github.com/primer/octicons-v2/issues/new?assignees=&template=icon-request.md&title=%5BIcon+request%5D) template.
+To request a new icon, open an issue using the [icon request](https://github.com/primer/octicons/issues/new?assignees=&template=icon-request.md&title=%5BIcon+request%5D) template.
 
 ### Adding or updating an icon
 

diff --git a/docs/content/index.mdx b/docs/content/index.mdx
@@ -4,15 +4,9 @@ title: Octicons
 
 import {HeroLayout} from '@primer/gatsby-theme-doctocat'
 import Icons from '../src/components/icons'
-import {Flash, Button, Flex} from '@primer/components'
+import {Flash, Button, Flex, Link} from '@primer/components'
+import {Link as GatsbyLink} from 'gatsby'
 
 export default HeroLayout
 
-<Flash mb={4}>
-  <Flex flexDirection={['column', 'row']} alignItems={["flex-start", "center"]} justifyContent="space-between">
-    <Text>We're working on a new look for Octicons</Text>
-    <Button as="a" href="https://primer.style/octicons-v2/" mt={[3, 0]}>Check it out</Button>
-  </Flex>
-</Flash>
-
 <Icons />
diff --git a/docs/content/packages/javascript.mdx b/docs/content/packages/javascript.mdx
@@ -23,19 +23,26 @@ After installing `@primer/octicons` you can access the icons like this:
 ```js
 var octicons = require("@primer/octicons")
 octicons.alert
-// { keywords: [ 'warning', 'triangle', 'exclamation', 'point' ],
-//   path: '<path d="M8.865 1.52c-.18-.31-.51-.5-.87-.5s-.69.19-.87.5L.275 13.5c-.18.31-.18.69 0 1 .19.31.52.5.87.5h13.7c.36 0 .69-.19.86-.5.17-.31.18-.69.01-1L8.865 1.52zM8.995 13h-2v-2h2v2zm0-3h-2V6h2v4z"/>',
-//   height: '16',
-//   width: '16',
-//   symbol: 'alert',
-//   options:
-//    { version: '1.1',
-//      width: '16',
-//      height: '16',
-//      viewBox: '0 0 16 16',
-//      class: 'octicon octicon-alert',
-//      'aria-hidden': 'true' },
-//   toSVG: [Function] }
+// {
+//     symbol: 'alert',
+//     keywords: ['warning', 'triangle', 'exclamation', 'point'],
+//     toSVG: [Function] 
+//     heights: {
+//         16: { 
+//             width: 16,
+//             path: '<path d="M8.865 1.52c-.18-.31-.51-.5-.87-.5s-.69.19-.87.5L.275 13.5c-.18.31-.18.69 0 1 .19.31.52.5.87.5h13.7c.36 0 .69-.19.86-.5.17-.31.18-.69.01-1L8.865 1.52zM8.995 13h-2v-2h2v2zm0-3h-2V6h2v4z"/>',
+//             options: {
+//                 version: '1.1',
+//                 width: '16',
+//                 height: '16',
+//                 viewBox: '0 0 16 16',
+//                 class: 'octicon octicon-alert',
+//                 'aria-hidden': 'true'
+//             },
+//         },
+//         24: ...
+//     }
+// }
 ```
 
 There will be a key for every icon, with [`toSVG`](#octiconsnametosvg) and other properties.
@@ -51,39 +58,71 @@ octicons.x.symbol
 // "x"
 ```
 
-### `octicons[name].path`
+### `octicons[name].keywords`
 
-Returns the string representation of the path of the icon.
+Returns an array of keywords for the icon. The data comes from the [data file in lib](../data.json). Consider contributing more aliases for the icons.
 
 ```js
-octicons.x.path
-// <path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"></path>
+octicons.x.keywords
+// ["remove", "close", "delete"]
 ```
 
-### `octicons[name].options`
+### `octicons[name].heights`
+
+Each icon can have multiple SVGs that are designed for different sizes. The `heights` property allows you to access all the SVGs for an icon using the natural height of the SVG.
 
-This is an object of all the attributes that will be added to the output tag.
 
 ```js
-octicons.x.options
-// { version: '1.1', width: '12', height: '16', viewBox: '0 0 12 16', class: 'octicon octicon-x', 'aria-hidden': 'true' }
+octicons.x.heights
+// {
+//     16: { 
+//         width: 16,
+//         path: '<path d="..."/>',
+//         options: {
+//             version: '1.1',
+//             width: '16',
+//             height: '16',
+//             viewBox: '0 0 16 16',
+//             class: 'octicon octicon-alert',
+//             'aria-hidden': 'true'
+//         },
+//     },
+//     24: {
+//         width: 24,
+//         path: '<path d="..."/>',
+//         options: {
+//             version: '1.1',
+//             width: '24',
+//             height: '24',
+//             viewBox: '0 0 24 24',
+//             class: 'octicon octicon-alert',
+//             'aria-hidden': 'true'
+//         },
+//     },
+// }
 ```
 
-### `octicons[name].width`
+
+### `octicons[name].heights[height].width`
 
 Returns the icon's true width, based on the svg view box width. _Note, this doesn't change if you scale it up with size options, it only is the natural width of the icon._
 
-### `octicons[name].height`
+### `octicons[name].heights[height].path`
 
-Returns the icon's true height, based on the svg view box height. _Note, this doesn't change if you scale it up with size options, it only is the natural height of the icon._
+Returns the string representation of the path of the icon.
 
-### `keywords`
+```js
+octicons.x.heights[16].path
+// <path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"></path>
+```
 
-Returns an array of keywords for the icon. The data comes from the [data file in lib](../data.json). Consider contributing more aliases for the icons.
+### `octicons[name].heights[height].options`
+
+This is an object of all the attributes that will be added to the output tag.
 
 ```js
-octicons.x.keywords
-// ["remove", "close", "delete"]
+octicons.x.heights[16].options
+// { version: '1.1', width: '12', height: '16', viewBox: '0 0 12 16', class: 'octicon octicon-x', 'aria-hidden': 'true' }
 ```
 
 ### `octicons[name].toSVG()`
@@ -117,11 +156,11 @@ octicons.x.toSVG({ "aria-label": "Close the window" })
 
 #### width & height
 
-Size the SVG icon larger using `width` & `height` independently or together.
+Size the SVG icon larger using `width` & `height` independently or together. `.toSVG()` will automatically choose the best SVG to render based on the width or height passed in.
 
 ```js
 octicons.x.toSVG({ "width": 45 })
-// <svg version="1.1" width="45" height="60" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>
+// <svg version="1.1" width="45" height="45" viewBox="0 0 24 24" class="octicon octicon-x" aria-hidden="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>
 ```
 
 [primer]: https://github.com/primer/primer

diff --git a/docs/content/packages/jekyll.mdx b/docs/content/packages/jekyll.mdx
@@ -6,6 +6,7 @@ source: 'https://github.com/primer/octicons/tree/master/lib/octicons_jekyll'
 
 [![Gem version](https://img.shields.io/gem/v/jekyll-octicons.svg)](https://rubygems.org/gems/jekyll-octicons)
 
+
 This jekyll liquid tag is a plugin that will let you easily include svg octicons in your jekyll sites.
 
 ## Install

diff --git a/docs/content/packages/rails.mdx b/docs/content/packages/rails.mdx
@@ -6,7 +6,6 @@ source: 'https://github.com/primer/octicons/tree/master/lib/octicons_helper'
 
 [![Gem version](https://img.shields.io/gem/v/octicons_helper.svg)](https://rubygems.org/gems/octicons_helper)
 
-
 This rails helper lets you easily include svg octicons in your rails apps.
 
 ## Install

diff --git a/docs/content/packages/react.mdx b/docs/content/packages/react.mdx
@@ -14,117 +14,52 @@ npm install @primer/octicons-react
 
 ## Usage
 
-### `<Octicon>`
-The `<Octicon>` component is really just the "shell" of an Octicon that renders
-the `<svg>` element and all of its attributes. To render a specific icon, you
-must pass it either via the `icon` prop, or as the only child:
-
-```jsx
-/**
- * The prop form is shorter, but doesn't allow you to pass icon props.
- */
-<Octicon icon={Icon} />
-
-/**
- * The child form allows you to pass props.
- */
-<Octicon><Icon x={10}/></Octicon>
-```
-
-Note that none of our builtin icons take props, so unless you're creating
-[custom icons](#custom-icons) you'll probably want to use the `icon` prop form.
-
 ### Icons
-The `@primer/octicons-react` module exports the `Octicon` component as
-`default` and the individual icon symbols as separate [named
+The `@primer/octicons-react` module exports individual icons as [named
 exports](https://ponyfoo.com/articles/es6-modules-in-depth#named-exports). This
 allows you to import only the icons that you need without blowing up your
 bundle:
 
 ```jsx
 import React from 'react'
-import Octicon, {Beaker, Zap} from '@primer/octicons-react'
+import {BeakerIcon, ZapIcon} from '@primer/octicons-react'
 
 export default function Icon({boom}) {
-  return <Octicon icon={boom ? Zap : Beaker}/>
+  return boom ? <ZapIcon /> : <BeakerIcon />
 }
 ```
 
 If you were to compile this example with a tool that supports [tree-shaking][]
 (such as Webpack, Rollup, or Parcel) the resulting bundle would only include
 the "zap" and "beaker" icons.
 
-### All icons
-If you don't mind your bundle being huge or you need to be able to render
-arbitrarily named icons at runtime, you can import either of the following
-named exports:
-
-#### `getIconByName()`
-The `getIconByName` export is a function that takes a lowercase octicon name
-(such as `arrow-right`) and returns the corresponding icon class. Using this
-helper, it's possible to create an Octicon class that takes a `name` prop and
-resolves it to the right component:
-
-```jsx
-import React from 'react'
-import Octicon, {getIconByName} from '@primer/octicons-react'
-
-export default function OcticonByName({name, ...props}) {
-  return <Octicon {...props} icon={getIconByName(name)} />
-}
-```
-
-#### `iconsByName`
-The `iconsByName` export is an object that maps keys (such as `arrow-right` or
-`zap`) to component functions, which you can use to generate listings of all
-the octicons:
-
-```jsx
-import React from 'react'
-import Octicon, {iconsByName} from '@primer/octicons-react'
-
-export default function OcticonsList() {
-  return (
-    <ul>
-      {Object.keys(iconsByName).map(key => (
-        <li key={key}>
-          <tt>{key}</tt>
-          <Octicon icon={iconsByName[key]}/>
-        </li>
-      ))}
-    </ul>
-  )
-}
-```
-
 ### Vertical alignment
 By default the octicons have `vertical-align: text-bottom;` applied as inline
 styles. You can change the alignment via the `verticalAlign` prop, which can be
 either `middle`, `text-bottom`, `text-top`, or `top`.
 
 ```js
-import Octicon, {Repo} from '@primer/octicons-react'
+import {RepoIcon} from '@primer/octicons-react'
 
 export default () => (
   <h1>
-    <Octicon icon={Repo} size='large' verticalAlign='middle' /> github/github
+    <RepoIcon verticalAlign='middle' /> github/github
   </h1>
 )
 ```
 
 
-### `ariaLabel`
+### `aria-label`
 You have the option of adding accessibility information to the icon with the
-[`aria-label` attribute][aria-label] via the `ariaLabel` prop (note the
-capitalization of `L`!).
+[`aria-label` attribute][aria-label] via the `aria-label` prop.
 
 ```js
 // Example usage
-import Octicon, {Plus} from '@primer/octicons-react'
+import {PlusIcon} from '@primer/octicons-react'
 
 export default () => (
   <button>
-    <Octicon icon={Plus} ariaLabel="Add new item" /> New
+    <PlusIcon aria-label="Add new item" /> New
   </button>
 )
 ```
@@ -142,44 +77,31 @@ render octicons at standard sizes:
 
 ```js
 // Example usage
-import Octicon, {LogoGithub} from '@primer/octicons-react'
+import {LogoGithubIcon} from '@primer/octicons-react'
 
 export default () => (
   <h1>
     <a href='https://github.com'>
-      <Octicon icon={LogoGithub} size='large' ariaLabel='GitHub'/>
+      <LogoGithubIcon size='large' aria-label='GitHub'/>
     </a>
   </h1>
 )
 ```
 
+### `Octicon` (DEPRECATED)
 
-## Custom icons
-Each of our icon components is really just a function that renders its SVG
-`<path>`. To accommodate icons varying aspect ratios, the `Octicon` component
-determines the `viewBox` of the `<svg>` element by first looking for a `size`
-array on the icon component class. For instance, if you wanted to create a
-custom icon that consisted of three circles side by side, you could do this:
-
-```jsx
-import React from 'react'
-import Octicon from '@primer/octicons-react'
-
-function CirclesIcon() {
-  return (
-    <React.Fragment>
-      <circle r={5} cx={5} cy={5}/>
-      <circle r={5} cx={15} cy={5}/>
-      <circle r={5} cx={25} cy={5}/>
-    </React.Fragment>
-  )
-}
+> ⚠️ The `Octicon` component is deprecated. Use icon components on their own instead:
+> ```diff
+- <Octicon icon={AlertIcon} />
++ <AlertIcon />
+```
 
-CirclesIcon.size = [30, 10]
+The `Octicon` component is wrapper that passes props to its icon component. To render a specific icon, you
+can pass it either via the `icon` prop, or as the only child:
 
-export default CirclesOcticon(props) {
-  return <Octicon {...props} icon={CirclesIcon} />
-}
+```jsx
+<Octicon icon={Icon} />
+<Octicon><Icon x={10}/></Octicon>
 ```
 
 [octicons]: https://octicons.github.com/