├── .github ├── CODEOWNERS ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── FUNDING.yml ├── ISSUE_TEMPLATE │ ├── bug_report.md │ ├── config.yml │ ├── feature_request.md │ └── support_request.md ├── MAINTAINING.md ├── PULL_REQUEST_TEMPLATE.md └── SUPPORT.md ├── LICENSE ├── README.md ├── _config.yml ├── current-version.json ├── postcss.alfredworkflow ├── screenshots ├── alfred.png └── postcss.png └── src ├── data.json ├── icon.png ├── postcss.php ├── update.json └── workflows.php /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @iamnewton 2 | -------------------------------------------------------------------------------- /.github/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | Open source software is thriving. Large corporations are building on software that rests on open collaboration, enjoying the many benefits of significant community adoption. Free and open source software is amazing for its ability to bring together many people from all over the world, and join their efforts and skills by their interests. 4 | 5 | That said, and because we come from so many different backgrounds, it’s worth taking a moment to reflect on how we work together. The manner in which you conduct yourself while working with others can sometimes impact whether your work is merged, whether someone works on your issue, or in some cases, why you might be blocked from participating in the repository in the future. This post was written to guide people as best as possible on how to keep these communications running smoothly. Here’s a bullet point list of etiquette in open source to help you have a more enjoyable time in the community and contribute to making it a better place. 6 | 7 | ## Our Pledge 8 | 9 | In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. 10 | 11 | ## Our Standards 12 | 13 | Examples of behavior that contributes to creating a positive environment include: 14 | 15 | * Using welcoming and inclusive language 16 | * Being respectful of differing viewpoints and experiences 17 | * Gracefully accepting constructive criticism 18 | * Focusing on what is best for the community 19 | * Showing empathy towards other community members 20 | 21 | Examples of unacceptable behavior by participants include: 22 | 23 | * The use of sexualized language or imagery and unwelcome sexual attention or advances 24 | * Trolling, insulting/derogatory comments, and personal or political attacks 25 | * Public or private harassment 26 | * Publishing others' private information, such as a physical or electronic address, without explicit permission 27 | * Other conduct which could reasonably be considered inappropriate in a professional setting 28 | 29 | ## Our Responsibilities 30 | 31 | Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. 32 | 33 | Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. 34 | 35 | ## Scope 36 | 37 | This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. 38 | 39 | ## Enforcement 40 | 41 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting us. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. 42 | 43 | Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. 44 | 45 | ## Attribution 46 | 47 | This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org/), version 1.4, available at . For more information read the [TODO groups site](http://todogroup.org/opencodeofconduct/). 48 | 49 | ## For the Maintainer 50 | 51 | * Use labels like help wanted or good first issue to guide people to issues they can work on if they are new to the project. 52 | * When running benchmarks, show the authors of the framework/library/etc the code you’re going to run to benchmark on before running it. Allow them to PR (it’s ok to give a deadline). That way when your benchmark is run you know they have your approval and it’s as fair as possible. This also fixes issues like benchmarking dev instead of prod or some user errors. 53 | * When you ask someone for help or label an issue help wanted and someone PRs, please write a comment explaining why you are closing it if you decide not to merge. It’s disrespectful of their time otherwise, as they were following your call to action. I would even go so far as to say it would be nice to comment on any PR that you close OR merge, to explain why or say thank you, respectively. 54 | * Don’t close a PR from an active contributor and reimplement the same thing yourself. Just… don’t do this. 55 | * If a fight breaks out on an issue that gets personal, shut it down to core maintainers as soon as possible. Lock the issue and ensure to enforce the code of conduct if necessary. 56 | 57 | ## For the User 58 | 59 | * Saying thank you for the project before making an inquiry about a new feature or filing a bug is usually appreciated. 60 | * When opening an issue, create a small, isolated, simple, reproduction of the issue using an online code editor (like codepen or codesandbox) if possible and a GitHub repository if not. The process may help you discover the underlying issue (or realize that it’s not an issue with the project). It will also make it easier for maintainers to help you resolve the problem. 61 | * When opening an issue, please suggest a solution to the problem. Take a few minutes to do a little digging. This [blog post](https://blog.kentcdodds.com/what-open-source-project-should-i-contribute-to-7d50ecfe1cb4) has a few suggestions for how to dive into the source code a little. If you’re not sure, explain you’re unsure what to do. 62 | * When opening an issue, if you’re unable to resolve it yourself, please explain that. The expectation is that you resolve the issues you bring up. If someone else does it, that’s a gift they’re giving to you (so you should express the appropriate gratitude in that case). 63 | * Don’t file issues that say things like “is this even maintained anymore?” A comment like this is insulting to the time they have put in, it reads as though the project is not valid anymore just because they needed a break, or were working on something else, or their parent died or they had a kid or any other myriad human reasons for not being at the beck and call of code. It’s totally ok to ask if there’s a roadmap for the future, or to decide based on past commits that it’s not maintained enough for your liking. It’s not ok to be passive aggressive to someone who created something for you for free. 64 | * If someone respectfully declines a PR because, though valid code, it’s not the direction they’d like to take the project, don’t keep commenting on the pull request. 65 | * When you want to submit a really large pull request to a project you’re not a core contributor on, it’s a good idea to ask via an issue if the direction you’d like to go makes sense. This also means you’re more likely to get the pull request merged because you have given them a heads up and communicated the plan. Better yet, break it into smaller pull requests so that it’s not too much to grok at one time. 66 | * Avoid entitlement. The maintainers of the project don’t owe you anything. When you start using the project, it becomes your responsibility to help maintain it. If you don’t like the way the project is being maintained, be respectful when you provide suggestions and offer help to improve the situation. 67 | * Before doing anything on a project, familiarize yourself with the contributor guidelines. 68 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to Contribute 2 | 3 | :bangbang: This project has a [Code of Conduct](./CODE_OF_CONDUCT.md). By interacting with this repository, organization, and/or community you agree to abide by its terms. 4 | 5 | Third-party patches are essential for keeping open-source software great. In the spirit of keeping it as simple as possible to contribute changes that get things working in your environment, here are a few guidelines that contributors should follow. As [Nicholas Gallagher](http://github.com/necolas/normalize.css/blob/master/CONTRIBUTING.md) put it in his contributing guidelines: 6 | 7 | > Following these guidelines helps to communicate that you respect the time of the developers managing and developing […]. In return, they should reciprocate that respect in addressing your issue or assessing your patches and features. 8 | 9 | ## How do I… 10 | 11 | 1. [Get Started](#get-started) 12 | 2. [Create an Issue](#create-a-good-issue) 13 | 3. [Create a Feature Request](#creating-a-good-feature-request) 14 | 4. [Contribute Documentation](#contributing-to-documentation) 15 | 5. [Create a Pull Request](#create-a-pull-request) 16 | 6. [Additional Resources](#additional-resources) 17 | 18 | ## Get Started 19 | 20 | 1. Make sure you have a GitHub account. 21 | 2. Please ask the [CODEOWNERS](./CODEOWNERS) before making significant changes. I'd hate for you to put in a lot of work for something that doesn't align with the vision of this project. 22 | 3. Search on Github within the repo for the issue or Pull Request. This means you have to read through the issue(s) in order to determine if your particular issue has already been created. Don't forget to look through the closed ones as well. 23 | 4. If the issue has not been fixed then try to reproduce the issue in a fresh clone of the repository off the master branch. Read below on [how to set up your environment](#create-a-pull-request). 24 | 5. Create a [reduced test case](http://css-tricks.com/reduced-test-cases/) as outlined by Chris Coyier of [CSS Tricks](http://css-tricks.com/). Link to the [Code Pen](http://codepen.io), [JS Bin](http://jsbin.com), or whatever you use, as long as its publicly accessible. 25 | 6. Read our [branching strategy](#branching-strategy), [commit conventions](#commit-conventions) below for tips on how to contribute. We won't accept any pull request that doesn't adhere, so be forewarned. 26 | 27 | If this seems like a lot or you aren't able to do all this setup, you might also be able to [edit the files directly](https://help.github.com/articles/editing-files-in-another-user-s-repository/) without having to do any of this setup. Yes, [even code](#create-a-pull-request). 28 | 29 | ## Create a Good Issue 30 | 31 | The easiest way to contribute is to help improve the library by finding bugs within the system. Bugs are small, testable and demonstrate problems caused by the code. A good report will be able to easily outline the problem and provide steps to recreate. If you're going to submit a bug, please verify you've done everything on the list above. Don't be afraid to go into detail; no one ever said too much detail was a problem, and if they did, it wasn't us. 32 | 33 | ### Filling Out a Ticket 34 | 35 | Now its time to submit a ticket. Bug reports should be thorough and not leave anyone wondering or questioning what you were thinking. No one should have to ask you anything or require further clarification. When creating a ticket, use the [Bug Report template](/issues/new?template=bug_report.md) to populate a lot of the information required. Below is a brief description of the parts of a bug report: 36 | 37 | * **title** (required): should be concise and descriptive. Anyone should be able to know what you're issue is at a glance and doesn't need the complete issue in it; try to keep it under 80 characters. 38 | * **description**: create a short summary of what is happening or what you're seeing. 39 | * **to reproduce** (required): the steps you followed to find this bug. This will make life so much easier to help fix the issue. Don't make any assumptions that someone will be on the same page or do the same thing as you. Nice and direct steps of what happened, what you clicked on can ease the time for us to debug. 40 | * **expected behavior** (required): let us know what you were expecting to happen. This may or may not align with the project, so be very detailed with this part; the more detail the better. 41 | * **screenshots**: a picture is worth a thousand words. 42 | * **device details** (required): for most of the information you can look at ; for others check out below for how to find them. 43 | * **OS & version**: Always include the OS(es) and version(s) where you found the issue. If, for example its Mavericks, you can put OSX 10.9.1. 44 | * **Browser(s) Version(s)**: Which browsers have you tested this in? What version are you running? 45 | * **Node Version(s)**: Not always required, but if there is something erring in the console, this is quite helpful. 46 | * **NPM Version(s)**: Not always required, but if there is something erring in the console, this is quite helpful. 47 | * **Browser Resolution**: Include resolutions as more of a range rather than an absolute. For example, < 768px or >= 768px && <= 1024th 48 | * **Library Version**: Required; please include which version of this library you're using 49 | 50 | ### Example Ticket 51 | 52 | Follow the example below and you'll be on the right path. Let's assume that a you're trying build a new page on your application and the icons aren't showing up: 53 | 54 | ```markdown 55 | Title: Icons are not showing up 56 | 57 | **Describe the bug** 58 | 59 | Developing my application and when it loads up 60 | the browser, I don't see any of the SVG icons loading up. 61 | 62 | **To Reproduce** 63 | 64 | 1. Open http://example.com/new-app 65 | 2. There is a blue button in the right side of the toolbar that says "Edit" 66 | 3. Notice there should be a pencil icon, and there is nothing. 67 | 68 | **Expected Behavior** 69 | 70 | When loading any page that contains an icon, I expect the icon to load alongside 71 | the other assets on the page, ie text, components, modules, etc 72 | 73 | **OS**: OSX 10.8.3 74 | **Browser(s) Version(s)**: All browsers, but founded initially in Chrome 38.0.2125.111 75 | **Node Version(s)**: v.7.8.0 76 | **NPM Version(s)**: 4.2.0 77 | **Browser Resolution(s)**: initially found at 1920 x 2063, but appears >768 78 | **Library Version**: 2.15.5 79 | 80 | **Additional context** 81 | 82 | - **Results**: Passed 83 | - **Line(s) of Code**: n/a 84 | - **Message**: n/a 85 | - **Console Errors**: 404 error on "svg/symbol-defs.svg" 86 | ``` 87 | 88 | ### Testing 89 | 90 | It's helpful, but not required to run the test suite locally. If you have the time and energy it can increase the efficiency and decrease the effort required for us to fix things. 91 | 92 | There are 2 sides to test, CSS and JS. For the CSS, you can can run `npm run lint:css` to check for syntax errors that may cause issues, or you can run `npm run test:css` to test the mixins and/or CSS. With regard to JS, the same applies; run `npm run lint:js` to check syntax errors and `npm run test:js` to test the JS components. You can also run linting and testing on both sides by running `npm run lint` and `npm test` respectively. 93 | 94 | 1. **Results**: If there is a fail in a particular test, include the name of the test, otherwise list as "Passed". 95 | 2. **Line(s) of Code**: Definitely not a requirement, but doesn't hurt if you've already pin pointed the issue. 96 | 3. **Message**: When the tests fail, a stack trace or message is typically output, so copy/paste that into the issue. 97 | 98 | Now that you've created an issue, maybe you want to try your hand at fixing the issue? Set up your environment. 99 | 100 | ## Create a Good Feature Request 101 | 102 | Another way to contribute is to help improve the library by suggesting new ideas within the system. While we may not accept every feature, it doesn't hurt to suggest improvements, but please stop and think about the intent of the project. Maybe its better in another independent project, or maybe not; there is no harm in asking, or filling out a feature request. Before you do submit, please look at my [road map](/roadmap.md) to see if I've already thought of your feature. And remember, if I don't like the idea, doesn't mean you can't fork the project. 103 | 104 | ### Filling Out a Feature Request 105 | 106 | Now its time to submit a ticket. Feature requests should be thorough and not leave anyone wondering or questioning what you were thinking. No one should have to ask you anything or require further clarification. When creating a ticket, use the [Feature Request template](/issues/new?template=feature_request.md) to populate a lot of the information required. Below is a brief description of the parts of a feature request: 107 | 108 | * **Is your feature request related to a problem?**: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 109 | * **Describe the solution you'd like**: A clear and concise description of what you want to happen.  Acceptance criteria are important for us to ensure a proper and complete feature. 110 | * **Describe alternatives you've considered**: A clear and concise description of any alternative solutions or features you've considered. 111 | * **Additional context**: Add any other context or screenshots about the feature request here. 112 | 113 | ### Example Feature Request 114 | 115 | Follow the example below and you'll be on the right path. 116 | 117 | ```markdown 118 | Title: Progress bar component 119 | 120 | **Is your feature request related to a problem? Please describe.** 121 | Not related to a problem. I would like to see an indicator of impressions to ad requests 122 | so that I can visualize the loss. 123 | 124 | **Describe the solution you'd like** 125 | I think a progress bar where the total value shown is the full width of 126 | the contained area, and the part that is filled in is the impressions. 127 | 128 | **Describe alternatives you've considered** 129 | A funnel chart was considered but its too similar to Googles design and 130 | Legal fears repercussions. 131 | 132 | **Additional context** 133 | N/A 134 | ``` 135 | 136 | ## Contributing to Documentation 137 | 138 | Documentation is a super important, critical part of this project. Docs are how we keep track of the what, how, and why of we're doing; it's how we stay on the same page about our policies. And it's how we tell others everything they need in order to be able to use this project -- or contribute to it. So thank you in advance. 139 | 140 | Contributions of any size are welcome! Feel free to file a PR even if you're just rewording a sentence to be more clear, or fixing a spelling mistake! 141 | 142 | To contribute: 143 | 144 | * [Set up the project](#get-started). 145 | * Edit or add any relevant documentation. 146 | * Make sure your changes are formatted correctly and consistently with the rest of the documentation. 147 | * Re-read what you wrote, and run a spellchecker on it to make sure you didn't miss anything. Check out [Grammerly](https://www.grammarly.com) for spelling and grammar mistakes as well as tone of writing. 148 | * In your commit message(s), begin the first line with `chore(docs): `. For example: `chore(docs): Adding a doc contrib section to CONTRIBUTING.md`. 149 | * Write clear, concise commit message(s) using the [convention described below](#commit-convention). Documentation commits should use `chore(docs): `. 150 | * Go to and open a new pull request with your changes and fill out the template with the appropriate information. 151 | * If your PR is connected to an open issue, add a line in your PR's description that says `Fixes: #123`, where `#123` is the number of the issue you're fixing. 152 | 153 | Once you've filed the PR: 154 | 155 | * One or more maintainers will use GitHub's review feature to review your PR. 156 | * If the maintainer asks for any changes, edit your changes, push, and ask for another review. 157 | * If the maintainer decides to pass on your PR, they will thank you for the contribution and explain why they won't be accepting the changes. That's ok! We still really appreciate you taking the time to do it, and we don't take that lightly. 158 | * If your PR gets accepted, it will be marked as such with the `next-release` label, and merged soon after. Your contribution will be distributed to the masses next time the maintainers [tag a release](./MAINTAINING.md#tag-a-release) 159 | 160 | ## Create a Pull Request 161 | 162 | If you're unfamiliar with the Github flow, please [read this guide](https://guides.github.com/introduction/flow/index.html) as an introduction. Make sure you reach out to someone on the team before you start any work to ensure that what you're doing is aligned with the teams' vision. Read Ilya Grigorik's great article [Don't "Push" Your Pull Requests](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/). The following passage sums up some great points: 163 | 164 | > Contributions are always welcome, but surprise patches are mostly just a burden. Yes, you are offering your help, but someone else will have to maintain your code over the long term - get their buy-in first, avoid surprises. Even worse, a localized change to address a specific problem will often miss the full implications to the project: other existing use cases, future roadmap plans, or overall architectural decisions. A good idea can be implemented inappropriately for the specific project; it can be invalidated by another effort that you may not even be aware of; the timing may be wrong, and a dozen other reasons can conspire against you. 165 | 166 | **IMPORTANT**: By submitting a patch, you agree to the same license as that used by the project. 167 | 168 | For those of you willing to help out, that's great!!! Here's a quick how-to with regarding to submitting your changes to Github. This requires no need for access, rights or privileges and can be done without any help from a team member. 169 | 170 | 1. Fork It by pressing the "Fork" button in the top right corner. 171 | 2. Clone your newly forked repo (`git clone https://github.com//`). 172 | 3. Change into the directory you cloned (`cd `) 173 | 4. Add your fork as a remote (`git remote add https://github.com//`) where `` is your actual Github username and `` is the repository with which you're looking to contribute. 174 | 5. Create your feature branch (`git checkout -b `); checkout the guide below for our [branching strategy](#branching-strategy) 175 | 6. Commit your changes (`git commit`), following the [format suggested below](#commit-conventions). Please don't use the shortcut flag `git commit -m ` as there is more detail required than what is allowed by only using that flag. 176 | 7. Push to the branch (`git push `) 177 | 8. Create a new Pull Request; make sure you fill in the Pull Request template. 178 | a. Most of the time the Reviewers sections provides suggestions and you should include them; in cases when it doesn't add the core team. 179 | b. Don't forget to [update the CODEOWNERS](#code-owners) file adding the directory and your name to the end of the list. 180 | 181 | **IMPORTANT**: Every patch and subsequent message should have a bug attached. If there is no ticket, no work should be done. 182 | 183 | ### Gotchas 184 | 185 | - Please avoid working directly on the `master` branch. 186 | - Make commits of logical units. 187 | - Check for unnecessary whitespace with `git diff --check` before committing. 188 | - Make sure your commit messages are in the [proper format](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), also listed below in our guides. 189 | 190 | ### Branching Strategy 191 | 192 | **ALL WORK REQUIRES A BRANCH. WE DO NOT PUSH DIRECTLY TO MASTER!** 193 | 194 | There are a lot of [various](http://nvie.com/posts/a-successful-git-branching-model/) [opinions](https://docs.microsoft.com/en-us/vsts/git/concepts/git-branching-guidance) on [branching](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow) [strategies](https://barro.github.io/2016/02/a-succesful-git-branching-model-considered-harmful/) and while all of them are great and have their place, they all tend to add a lot of overhead and maintenance with little value to the workflow. We prefer to use the simplified strategy known as [Github flow](https://guides.github.com/introduction/flow/). So when working with the library, there's no need to prefix it with `feature/` or `hotfix/` or anything like that; Github's PR-style workflow allows for quick and disposable branches. Create branches off `master` and use descriptive names such as `create-donut-chart`, `refactor-dropdown` so that users can easily see what's being worked on.  195 | 196 | #### Naming 197 | 198 | Branch names should short, concise and easy to understand the work that is being done. While not a necessity, setting up `` completion for git branches can speed up the discovery of branch names. The following tips are designed to speed up your workflow with the addition of tab completion. 199 | 200 | * **Use only lower case letters**. Lowercasing makes it quicker to type by providing fewer letters to get working. Avoid upper case letters as it requires a higher level of dexterity that can decrease the speed of workflow 201 | * **Use dashes instead of underscores**. The same is true as above, they're are easier to type and require less dexterity. 202 | * **Don't prefix the branch name with any particular pattern**. Unless you regularly clean up your local branches, it's likely to increase the number of characters and tabbing through in order to complete the branch name you seek 203 | * **Don't include the ticket number**. Adding it falls into the same faults as suggestion 2 above; it requires a lot more typing in order to tab complete through to the branch you may want 204 | 205 | When searching through a bunch of branches, `issue-123` doesn't provide any inherent value to the developer in hopes to find the feature they want to help out on; however seeing `modal-trigger-open` gives the developer some insight into what work is being done. 206 | 207 | #### Example Branches 208 | 209 | ``` 210 | // good 211 | git checkout -b fix-bug-x 212 | git checkout -b new-component 213 | 214 | // bad 215 | git checkout -b JIRA_1234 216 | git checkout -b tests 217 | ``` 218 | 219 | _The only exception, at the time of this writing, is for tagging and releasing_ 220 | 221 | ### Commit Conventions 222 | 223 | Commits should be small, concise and logical units of code. The goal is not to overwhelm reviewers with superfluous changes; do not add any unrelated changes to a commit in case the change needs to be reverted or backed out.  The entirety of your code should answer the question: 224 | 225 | **Which problem am I trying to solve today?** 226 | 227 | All changes should be connected and without 1 change your entire commit would fall apart. If you find that you can keep a commit out and your code still makes sense, runs successfully, and fixes an issue then you're likely in a good condition to commit some code and create a pull request. Contributors are required to follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification on all commit messages. If you're ready, follow below to create a good commit message in the proper format. 228 | 229 | A few tips to consider: 230 | 231 | * Absolutely no working directly on the master branch!!! 232 | * Check for unnecessary whitespace with `git diff --check` before committing. 233 | * And be sure to run git commit and NOT `git commit -m ` so that you can fill out the body of the message 234 | 235 | #### Parts of a Commit 236 | 237 | A commit should consist of a required title, optional but recommended body and an optional but recommended footer. Below is the desired format with an example: 238 | 239 | ``` 240 | (): 241 | 242 | 243 | 244 |