GithubHelp home page GithubHelp logo

primer / react Goto Github PK

View Code? Open in Web Editor NEW
3.1K 3.1K 535.0 360.07 MB

An implementation of GitHub's Primer Design System using React

Home Page: https://primer.style/guides/react

License: MIT License

JavaScript 2.22% TypeScript 96.48% Shell 0.04% Ruby 0.10% CSS 1.15%
component-library design-system primer react

react's Introduction

Primer logo

Primer React

A React implementation of GitHub's Primer Design System

npm package contributors graph last commit license

Documentation

Our documentation site lives at primer.style/react. You'll be able to find detailed documentation on getting started, all of the components, our theme, our principles, and more.

Installation

Install @primer/react in your project with your package manager of choice:

npm install @primer/react
yarn add @primer/react

Template

The fastest way make a prototype or try Primer React without setting up a new project is by using our react template.

Roadmap

You can track our roadmap progress in the Roadmap Project Board, see more detail in the quarterly planning Discussions, and find a list of all the current epic tracking issues.

Contributing

We love collaborating with folks inside and outside of GitHub and welcome contributions!

๐Ÿ‘‰ See the contributing docs for more info on code style, testing, coverage, and troubleshooting.

New Component Proposals

We welcome and encourage new component proposals from internal GitHub teams! Our best work comes from collaborating directly with the teams using Primer React Components in their projects. If you'd like to kick off a new component proposal, please submit an issue using the component proposal issue template and we will get in touch!

react's People

Contributors

binarymuse avatar broccolini avatar broccolinisoup avatar camertron avatar colebemis avatar dependabot[bot] avatar dgreif avatar dmarcey avatar github-actions[bot] avatar green6erry avatar iansan5653 avatar jfuchs avatar jonrohan avatar joshblack avatar keithamus avatar langermank avatar lukasoppermann avatar mattcosta7 avatar mperrotti avatar pksjce avatar primer-css avatar primer[bot] avatar radglob avatar rezrah avatar shawnbot avatar siddharthkp avatar smockle avatar t-hugs avatar tylerjdev avatar vananderson avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

react's Issues

Should fontSize go up or down?

@emplums asked a good question here:

[...] we are inverting the fontSize scale here?

When @broccolini started this repo, fontSize was translated directly to CSS font-size in a styled component. So my goal was to have a prop that mapped increasing numbers to increasing sizes, which is the inverse of our f? classes. ๐Ÿ˜ฑ I have no idea which is "right", though, so let's discuss!

Add Details component

We need Primer-specific <details> + <summary> components for #45 (and #43):

"Show/hide all checks" link

This one is a slightly more complicated version of a native <details>, in that it needs to show different text depending on when it's open or closed.

Dropdown

In this one, the "pressed" state of the arrow changes when you open and close it, and the dropdown content is absolutely positioned. The tricky thing here is using <details> and <summary>, because they require that the latter is nested directly in the former.

I've whipped up an example of how we could do this using the render props pattern, which makes the open and toggle props available to children so that the author can decide what's visible and hidden in the summary without managing state.

Discussion: Autofocus on TextInput component

@shawnbot noticed that the TextInput component include an autofocus prop + attribute. I'm curious if there's a strong use case for needing this here, or if it would be ok to remove it? The reason being that autofocus can have negative a11y consequences as it disorients screen reader users without warning. From MDN:

Warning: Automatically focusing a form control can confuse visually-impaired people who using screen-reading technology. When autofocus is assigned, screen-readers "teleport" their user to the form control without warning them beforehand.

Additionally, only one element per page should have the autofocus attribute and we currently don't have any way of enforcing that.

Curious if there is a strong reason why we decided to add it? cc @jonrohan @shawnbot @broccolini

Flexbox component

Needs to include API for:

  • flex or inline flex option
  • flex direction
  • flex wrap
  • justify content
  • align items
  • align content
  • flex-auto
  • align self
  • responsive flex utilties

The release build doesn't include the dist directory

You can't import the latest version of primer-react because the published package doesn't include the dist/ directory. This is because I put the build step in our preversion run-script instead of prepublishOnly, and since we're not versioning on Travis it never ran. So yeah, I need to fix that. ๐Ÿคฆโ€โ™‚๏ธ

Whitelisting certain props?

This week's work has given us an opportunity to mull over whether components should be "strict" in which props they allow users to pass โ€” or, as an implementation detail, which ones they actually respect. I can think of a couple that we may want to whitelist for some, if not all, Primer components:

  1. id could people to provide deep links without having to wrap another element around their content.
  2. hidden would provide a more systematic way to show and hide things.
  3. Any aria- attribute, because a11y.
  4. Any data- attribute, to provide hooks for JS behaviors implemented by container components.

Thoughts?

Primer-react v1 beta - release tracking

Tracking v0.0.1-beta

Must

Should

Could

  • Flex component
  • Tooltip component

UnderlineNav follow up items

๐Ÿ› Bugs

  • Underline is red-orange when Kit is first loaded, but once you navigate to other tabs, it turns grey.

๐Ÿš€ Enhancements

  • Spread children's props back onto cloned child
  • Move rendersClass into utility file
  • Consider whether or not it's ok to have a circular dependency between UnderlineNav and UnderlineNavLink

Refactor `border` prop

From @emplums in this review:

This is maybe one for another PR, but what do you think about separating the border utilities into two different props? We could have border and borderColor? I think that would make reasoning with the prop a bit more intuitive on the user side & would make it easier to create classes here! It looks like the styleguide docs also encourage using two separate classes for border/border-top/etc and border color utilities

Also curious if we need to allow people to pass in border={0}, and we instead make the Block component have no border by default?

I agree 100%!

prop to describe color theme

We need to come up with a name for a prop that describes a color theme (background color + text color, etc)... theme could easily be mixed up with our themes (light/dark). Maybe colorPattern? colorScheme ? maybe theme is ok? thoughts?

Public Beta Checklist

Items that need to be completed before our first public beta

Must

  • Support documentation for components in markdown format
  • Point site to primer.style/components
  • Default theme for each component?
  • "Good enough" test coverage
  • Index page design
  • Every component documented
    • Simple (default) example
    • Component Props
    • Basic implementation guidelines
  • System props documented
  • Installation guidelines, aka "how to use in your app"
    • confirm what packages are needed
  • Component(s) to import Primer CSS #124
  • Rename the repo to primer/components
  • Scope on npm

Dependency

  • Shipped primer.style

Should

  • Improved doc design #231
  • A way to provide feedback

Could

  • Copy over usage guidelines from style guide
  • Add favicon

Won't

  • Remaining Primer CSS components #100
  • Provide docs for how to use your own theme
  • Ship dev mode

Extend a component

Extend a component (such as buttons) to provide an example of how we'll approach this with any component, such as when do you extend vs add props.

fontSize in Text

The fontSize prop in Text goes from 0-6 and maps them backwards to match up to the primer/primer scale which goes from 6-0. Let's create 1:1 with primer/primer and keep the scale going from 6-0

Publish docs automatically

Currently our process of running npm run build to update the docs directory (so that we can then publish to GitHub Pages) is a bit tedious and error-prone because:

  1. It inevitably causes merge conflicts
  2. It's a manual step that I often forget to run before pushing
  3. It won't happen automatically when we merge branches

I propose that we build the site on CI (which also ensures that the site always builds) and publish it from there, ideally to a branch-specific URL on the gh-pages branch so that the URL would be, for instance, https://primer.github.io/primer-react/preview/my-branch-name/.

Build "full" UMD bundle?

Our UMD build doesn't currently bundle any of the external dependencies, including d3-shape or Octicons. If we want to support CodePen and other, dependency-unaware environments, we'll need to build a browser-ready UMD bundle with all the batteries included.

Clean up the donuts

  1. This line is a mess: child.props.key doesn't exist, which results in un-keyed elements. Maybe calling React.cloneElement() would be better here?
  2. The DonutPropType bit is kind of silly. That PropTypes.shape() call can be wrapped in oneOrMoreOf() from props.js.

Remaining Docs fixes

  • Currently on the static site the top level nav goes to urls like this /primer-react/docs/[page], but clicking on components in the component library changes the url to /docs/[page]/[component]. This is due to a difference between how routing is working locally vs on the static site. Locally, /primer-react is not prefixed to every url (because GH pages is doing that), so in order for HMR to work, the routes need to go to /docs/page/component instead of /primer-react/docs/page/component. Fun times ๐Ÿ™ƒ

  • The url generated by gh pages is /primer-react, but the static site actually lives at /primer-react/docs

Make `shadow` prop only accept string values

Ref: #70 (comment)

What do you think about changing the shadow API here to accept small, medium, large, extra-large and then instead of accepting either a boolean or a string we can just accept strings and this line would be

shadow && ((shadow === 'small') ? 'box-shadow' : `box-shadow-${shadow}`)

Composite Component: Merge Box

This is a tracking issue to detail all the components we need to recreate the merge box.

  • Avatars
    image
  • Dropdown
    image
  • Hide/show details toggle
    image
  • Dismiss review form
    image
  • Branch name
    image
  • This graph thing
    image
  • Status icon
    image
  • Tooltip
    image

Updates to merge box

  • fix pending state
  • rethink API around data structure
  • create a demo container component

Caret API improvements

The Caret component introduced in #58 has some issues that I'd like to address:

  • The combination of edge and align props is kind of confusing, and the align prop is currently ignored. I think that a location prop with values like top, top-left, etc. will be more intuitive, and matches the Popover position naming conventions.
  • As discussed with @jonrohan, it's probably safe to kill off the hacky CSS implementation and just use SVG.
  • It's currently a pain to coordinate the border and background colors between a Box and Caret, so I'd like to introduce a component that combines them. Possible names include: BoxWithCaret, PointyBox, CaretBox, and CarrotBox... :trollface:

We should take this opportunity to address the positioning inconsistencies with Popover, and possibly even re-implement Popover as a Box + Caret!

Example permalinks don't work

Our x0-driven docs site doesn't generate working component permalinks. When we publish to Pages, the index loads from /primer-react/, but the links all go to /{ComponentName} (without the right path prefix). The pages for individual components don't even really exist (there's only an index.html in the docs directory), so I'm not sure what the URLs really should be for a component example. Having working permalinks seems pretty crucial to me.

To reproduce, visit https://primer.github.io/primer-react/ and click on "Details". The URL changes to https://primer.github.io/Details, which doesn't exist. But neither do any of the following:

  • https://primer.github.io/primer-react/Details
  • https://primer.github.io/primer-react/?Details
  • https://primer.github.io/primer-react/#Details

We've already set x0.basename in package.json as described in x0's docs, but the URLs that are getting passed to location.replace() or history.pushState() just aren't right.

Any ideas, @broccolini?

Make a composit component

To act as a template for other composit components. I.e. show how we handle spacing and styling components within a component etc.

Make Primer Sass-only version

I think it makes sense to fork this repo and make a version of react components that uses existing Primer styles only. That allows us to explore how we break down components while we test out CSS-in-JS solution which will take longer to build.

Sharing system utility props across components & component types

I did some testing using primer-react in a project this weekend, and I found some things too inflexible in places that will make it too hard to work with and might cause us some headaches too. I think I'd rather be a little more flexible than constrain stuff too much. Here's some suggestions:

  • Everything should have space (margin/padding) and color (color/bg) utility props
  • Add a CSS prop for applying one-off css styles to any component like this

I think we can group components in categories to help us make the same utility props available, this will make them easier to compose with, and create some standardization across components:

  • Text styles:
    • Props: fontSize, lineHeight
    • Components: Text, Heading, Link, Label, Counter, State Tooltip, Button, Form elements
  • Layout:
    • Props: width (such as width={[1,2/3, 1/2]} mapping to our col-width utilities), container (such as container-lg) (same as breakpoints), border
      • Block (Box), Flex
  • Interactive:
    • Props: onClick handlers
      • Forms, Buttons

Some other areas that need more thought:

  • "Polish", such as box shadows, border-clip etc. - perhaps should be utility props?
  • How should we handle position? Component or props or both?

cc @primer/ds-core

Document how to import custom Primer CSS

We need some "official" way to import Primer CSS. Here's how we've done it in our docs site:

  1. At first, we just linked out to a bunch of unpkg.com URLs. This is okay for demos and sandboxes, but not good for production.
  2. In #238, I set up the Next sass plugin to output a static CSS file as part of the webpack build. This is okay too, but we need to address other use cases.

Utility class mapping

I've been using the Primer mapping from system-classnames in #32, but after looking into Text and Heading components I think we should consider more granular mappings for each, e.g.

import createMapper from 'system-classnames'

const breakpoints = [null, 'sm', 'md', 'lg', 'xl']
// one day? import {breakpoints} from 'primer-primitives'

const createPrimerMapper = props => createMapper({
  breakpoints,
  props,
  getter: ({breakpoint, prop, value}) => breakpoint
    ? [prop, breakpoint, value].join('-')
    : [prop, value].join('-')
})

const textMap = createPrimerMapper(['h', 'f', 'lh', 'text'])
const boxMap = createPrimerMapper([
  'bg', 'text', 'border', 'rounded', 'box-shadow',
  'position', 'top', 'right', 'bottom', 'left',
  'v-align', 'overflow', /* 'float', */
  'width', 'height', 'min-width' // these might need to be handled separately
])

export default createPrimerMapper
export {textMap, boxMap}

Then Box, Text, and Heading would each use them like:

const Box = props => <div {...boxMap(props)} />
const Text = props => <span {...textMap(props)} />
const Heading = props => <h1 {...textMap(props)} />
Heading.h2 = props => <h2 {...textMap(props)} />
// etc.

Does this seem like the right way to go about it?

Do we need individual packages or not?

In primer/primer we have a separate package for each component or group of styles. We set it up like this so that people could only pull in the styles they need so as to avoid unnecessary bloat. Do we need to do this with React components? We don't have quite the same concerns with CSS bloat. I do think we will still have some distinction between dotcom and marketing sites, so perhaps there is an "addons" package, but otherwise maybe we don't need to break it up quite as much. Let me know what you think!

cc @primer/ds-core

Kit updates

Add:

  • PropsForms
  • Top navigation & separate Library components for presentational & demo components
  • v1 Sandbox
  • Primer styles for sidebars and top nav
  • Fix HMR

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.