diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index abae83dd79..7c0fd77fa1 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -5,31 +5,31 @@ 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, sex characteristics, gender identity and expression, -level of experience, education, socio-economic status, nationality, personal -appearance, race, religion, or sexual identity and orientation. +size, disability, ethnicity, sex characteristics, gender identity and +expression, level of experience, education, socio-economic status, nationality, +personal appearance, race, religion, or sexual identity and orientation. ## Our Standards Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting ## Our Responsibilities @@ -37,11 +37,11 @@ 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. -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. +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. ## Scope @@ -55,11 +55,13 @@ further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at [frontend@phase2technology.com](mailto:frontend@phase2technology.com). All +reported by contacting the project team at +[frontend@phase2technology.com](mailto:frontend@phase2technology.com). 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. +obligated to maintain confidentiality with regard to the reporter of an +incident. Further details of specific enforcement policies may be posted +separately. 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 @@ -67,8 +69,9 @@ members of the project's leadership. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 1.4, available at +https://www.contributor-covenant.org/version/1/4/code-of-conduct.html [homepage]: https://www.contributor-covenant.org diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index dd84ea7824..8bc4a7ed86 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -4,35 +4,33 @@ about: Create a report to help us improve title: '' labels: '' assignees: '' - --- -**Describe the bug** -A clear and concise description of what the bug is. +**Describe the bug** A clear and concise description of what the bug is. + +**To Reproduce** Steps to reproduce the behavior: -**To Reproduce** -Steps to reproduce the behavior: 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' 4. See error -**Expected behavior** -A clear and concise description of what you expected to happen. +**Expected behavior** A clear and concise description of what you expected to +happen. -**Screenshots** -If applicable, add screenshots to help explain your problem. +**Screenshots** If applicable, add screenshots to help explain your problem. **Desktop (please complete the following information):** - - OS: [e.g. iOS] - - Browser [e.g. chrome, safari] - - Version [e.g. 22] + +- OS: [e.g. iOS] +- Browser [e.g. chrome, safari] +- Version [e.g. 22] **Smartphone (please complete the following information):** - - Device: [e.g. iPhone6] - - OS: [e.g. iOS8.1] - - Browser [e.g. stock browser, safari] - - Version [e.g. 22] -**Additional context** -Add any other context about the problem here. +- Device: [e.g. iPhone6] +- OS: [e.g. iOS8.1] +- Browser [e.g. stock browser, safari] +- Version [e.g. 22] + +**Additional context** Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bbcbbe7d61..2866f790fa 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -4,17 +4,16 @@ about: Suggest an idea for this project title: '' labels: '' assignees: '' - --- -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] +**Is your feature request related to a problem? Please describe.** A clear and +concise description of what the problem is. Ex. I'm always frustrated when [...] -**Describe the solution you'd like** -A clear and concise description of what you want to happen. +**Describe the solution you'd like** A clear and concise description of what you +want to happen. -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. +**Describe alternatives you've considered** A clear and concise description of +any alternative solutions or features you've considered. -**Additional context** -Add any other context or screenshots about the feature request here. +**Additional context** Add any other context or screenshots about the feature +request here. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e9aed7b24d..fdd475049e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -21,5 +21,5 @@ Describe what problem you're solving. Link the issue from the issues tab. ## Summary of Changes diff --git a/README.md b/README.md index 261c87ed6f..5bb0b02129 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,26 @@ # Particle: A design system integrating to Pattern Lab and a Drupal 8 theme -[![GitHub (pre-)release](https://img.shields.io/github/release/phase2/particle/all.svg)](https://github.com/phase2/particle/releases) [![Build Status](https://travis-ci.org/phase2/particle.svg?branch=master)](https://travis-ci.org/phase2/particle) [![Greenkeeper badge](https://badges.greenkeeper.io/phase2/particle.svg)](https://greenkeeper.io/) +[![GitHub (pre-)release](https://img.shields.io/github/release/phase2/particle/all.svg)](https://github.com/phase2/particle/releases) +[![Build Status](https://travis-ci.org/phase2/particle.svg?branch=master)](https://travis-ci.org/phase2/particle) +[![Greenkeeper badge](https://badges.greenkeeper.io/phase2/particle.svg)](https://greenkeeper.io/) -![Particle mascot: Astrogoat](apps/node-pl/pattern-lab/_patterns/01-atoms-demo/image/astrogoat.png?raw=true 'Astrogoat') +![Particle mascot: Astrogoat](apps/pl-default/pattern-lab/_patterns/01-atoms-demo/image/astrogoat.png?raw=true 'Astrogoat') Particle is an opinionated set of tools and examples to: 1. Build an application-agnostic **design system** -1. Apply that design system to a locally-served **Pattern Lab** for rapid prototyping +1. Apply that design system to a locally-served **Pattern Lab** for rapid + prototyping 1. Apply that design system to a **Drupal theme** -In depth documentation about frontend approach using this project at [Phase2 Frontend Docs](https://phase2.gitbook.io/frontend/) +In depth documentation about frontend approach using this project at +[Phase2 Frontend Docs](https://phase2.gitbook.io/frontend/) ## Prerequisites -- [Node `^8`, `^10`](https://nodejs.org) +- [Node `^8`, `^10`, `^12`](https://nodejs.org) - [NPM `^5`, `^6`](https://www.npmjs.com/) -- [PHP `^7.0.0`](https://php.net) +- [PHP `^7`](https://php.net) [Step-by-step instructions to install all dependencies for OSX can be found in this Gist.](https://gist.github.com/illepic/efd6ab9f452af2a99b7ade78257e6b96) @@ -24,17 +28,25 @@ In depth documentation about frontend approach using this project at [Phase2 Fro - Drupal theme, Grav theme, and Pattern Lab app - Strict [Atomic Design](http://atomicdesign.bradfrost.com/) component structure -- Webpack bundling of all CSS, javascript, font, and static image assets for multiple targets (Drupal theme, Grav theme, Pattern Lab) -- [Webpack Dev Server](https://github.com/webpack/webpack-dev-server) for local hosting and hot reloading of assets into Pattern Lab -- [Twig namespaced paths](https://symfony.com/doc/current/templating/namespaced_paths.html) automatically added into Drupal theme and Pattern Lab config. Within any twig file, `@atoms/thing.twig` means the same thing to Drupal theme and Pattern Lab. +- Webpack bundling of all CSS, javascript, font, and static image assets for + multiple targets (Drupal theme, Grav theme, Pattern Lab) +- [Webpack Dev Server](https://github.com/webpack/webpack-dev-server) for local + hosting and hot reloading of assets into Pattern Lab +- [Twig namespaced paths](https://symfony.com/doc/current/templating/namespaced_paths.html) + automatically added into Drupal theme and Pattern Lab config. Within any twig + file, `@atoms/thing.twig` means the same thing to Drupal theme and Pattern + Lab. - Iconfont auto-generation -- Auto-linting against the [AirBnB JavaScript Style Guide](https://github.com/airbnb/javascript) +- Auto-linting against the + [AirBnB JavaScript Style Guide](https://github.com/airbnb/javascript) - All Webpack files are fully configurable -- Simple [Yeoman](http://yeoman.io/) generator for Design System component creation +- Simple [Yeoman](http://yeoman.io/) generator for Design System component + creation ## Quickstart -Particle builds design systems in dev mode for local hosting, or production mode for optimized asset generation. +Particle builds design systems in dev mode for local hosting, or production mode +for optimized asset generation. ### Quickstart A @@ -53,7 +65,8 @@ Particle builds design systems in dev mode for local hosting, or production mode ### Quickstart B 1. [Download the latest release](https://github.com/phase2/particle/releases) -1. Extract anywhere (i.e. this readme should be at `any/where/particle/README.md`) +1. Extract anywhere (i.e. this readme should be at + `any/where/particle/README.md`) 1. Within the extracted folder run: ```bash @@ -62,6 +75,19 @@ npm run setup npm start ``` -Simply wait until the webpack bundle output appears then visit [http://0.0.0.0:8080/app-node-pl/pl/](http://0.0.0.0:8080/app-node-pl/pl/) (or [http://localhost:8080/app-node-pl/pl/](http://localhost:8080/app-node-pl/pl/)) and start working. +Simply wait until the webpack bundle output appears then visit +[http://0.0.0.0:8080/app-pl/pl/](http://0.0.0.0:8080/app-pl/pl/) (or +[http://localhost:8080/app-pl/pl/](http://localhost:8080/app-pl/pl/)) and start +working. -That's it. For **much** greater detail on the frontend approach using this project, check out the [Phase2 Frontend Docs](https://phase2.gitbook.io/frontend/). +That's it. For **much** greater detail on the frontend approach using this +project, check out the +[Phase2 Frontend Docs](https://phase2.gitbook.io/frontend/). + +## Design System Naming + +The Design System Source folder is named default `./source/default`. It's handy +in multi-design setups to name this per design system and post-fix `apps` with +that design system name. For example, `apps/drupal-default/` contains the +implementation of the `default` source directory. These are intended to be +updated by the needs of your project. diff --git a/apps/drupal/.eslintrc.js b/apps/drupal-default/.eslintrc.js similarity index 100% rename from apps/drupal/.eslintrc.js rename to apps/drupal-default/.eslintrc.js diff --git a/apps/drupal-default/README.md b/apps/drupal-default/README.md new file mode 100644 index 0000000000..0441db75b0 --- /dev/null +++ b/apps/drupal-default/README.md @@ -0,0 +1,50 @@ +# Particle Drupal + +This directory contains Webpack config for Drupal apps within Particle. In +addition it contains a Drupal theme integration and optional helpers module. +This readme assumes Particle is installed inside your Drupal theme. Check +[the Particle docs](https://phase2.gitbook.io/frontend/) for complete details. + +If you'd like to separate your Particle tooling from Drupal's theme, see +[Decoupled Drupal Installation](#decoupling) below. + +## Drupal Integration + +This folder contains two additional directories: `particle_helper` and +`particle_theme`. Due to the process by which Drupal loads services, several +optional Particle-specific functions are expected to exist within a module +separate from the theme. This module can then specify various requirements and +dependencies, which Drupal 8 themes still cannot declare. + +**Important**! The Drupal `particle_helper` module is optional template for +additional integration work you may wish to do. However its Twig extension is +required if you are making use of the `attributify` twig filter. This is needed +to manage the separate requirements of Pattern Lab and Drupal's Twig +environments for common HTML attributes. + +### Standard Drupal Installation: + +1. Move the contents of the `particle_helper` folder to your Drupal + `modules/contrib` directory (optional). +1. Ensure the module is enabled: `drush en particle_helper` (optional). +1. Ensure the theme is enabled: `drush theme:enable particle`. +1. Ensure the theme is set: + `drush config-set system.theme default THEME_MACHINE_NAME`. + +### Decoupled Drupal Installation + +1. Move the contents of the `particle_helper` folder to your Drupal + `modules/contrib` directory. +1. Move the contents of the `particle_theme` folder to your Drupal + `theme/contrib` directory. +1. From the main root of the Particle application, open + `particle.root.config.js` +1. Find the line that starts with `DRUPAL_DIST` +1. Update the `DRUPAL_DIST` line so that the path resolves to the theme created + in step 2. For example, if the Drupal installation is in a folder named + `web`, your line might look like this: + `DRUPAL_DIST: path.resolve('../../web/themes/custom/particle/dist/'),` +1. Ensure the module is enabled: `drush en particle_helper` (optional). +1. Ensure the theme is enabled: `drush theme:enable particle`. +1. Ensure the theme is set: + `drush config-set system.theme default THEME_MACHINE_NAME`. diff --git a/apps/drupal/drupal-jquery.js b/apps/drupal-default/drupal-jquery.js similarity index 100% rename from apps/drupal/drupal-jquery.js rename to apps/drupal-default/drupal-jquery.js diff --git a/apps/drupal/index.js b/apps/drupal-default/index.js similarity index 100% rename from apps/drupal/index.js rename to apps/drupal-default/index.js diff --git a/apps/drupal/particle.app.config.js b/apps/drupal-default/particle.app.config.js similarity index 100% rename from apps/drupal/particle.app.config.js rename to apps/drupal-default/particle.app.config.js diff --git a/apps/drupal-default/particle_helper/particle_helper.info.yml b/apps/drupal-default/particle_helper/particle_helper.info.yml new file mode 100644 index 0000000000..7f554c0467 --- /dev/null +++ b/apps/drupal-default/particle_helper/particle_helper.info.yml @@ -0,0 +1,5 @@ +name: 'Particle Helper' +type: module +description: 'Particle Components and Particle Tools. Theme utilities to integrate Drupal with Particle themes.' +core: 8.x +package: 'Particle' diff --git a/apps/drupal/module/particle_theme/particle_theme.module b/apps/drupal-default/particle_helper/particle_helper.module similarity index 60% rename from apps/drupal/module/particle_theme/particle_theme.module rename to apps/drupal-default/particle_helper/particle_helper.module index 816268e021..63d5bde7c6 100644 --- a/apps/drupal/module/particle_theme/particle_theme.module +++ b/apps/drupal-default/particle_helper/particle_helper.module @@ -2,7 +2,7 @@ /** * @file - * Contains particle_theme.module. + * Contains particle_helper.module. */ use Drupal\Core\Routing\RouteMatchInterface; @@ -10,10 +10,10 @@ use Drupal\Core\Routing\RouteMatchInterface; /** * Implements hook_help(). */ -function particle_theme_help($route_name, RouteMatchInterface $route_match) { +function particle_helper_help($route_name, RouteMatchInterface $route_match) { switch ($route_name) { - // Main module help for the particle_theme module. - case 'help.page.particle_theme': + // Main module help for the particle_helper module. + case 'help.page.particle_helper': $output = ''; $output .= '

' . t('About') . '

'; $output .= '

' . t('Particle and Particle theme utilities') . '

'; diff --git a/apps/drupal-default/particle_helper/particle_helper.services.yml b/apps/drupal-default/particle_helper/particle_helper.services.yml new file mode 100644 index 0000000000..37f3c62a21 --- /dev/null +++ b/apps/drupal-default/particle_helper/particle_helper.services.yml @@ -0,0 +1,15 @@ +services: + particle_helper.twig_extension: + arguments: ["@renderer"] + class: Drupal\particle_helper\TwigExtension\ParticleHelperTwig + tags: + - { name: twig.extension } + + particle_helper.particle_tools: + class: Drupal\particle_helper\Tools\ParticleTools + + particle_helper.atoms: + class: Drupal\particle_helper\Components\Atoms + + particle_helper.molecules: + class: Drupal\particle_helper\Components\Molecules diff --git a/apps/drupal/module/particle_theme/src/Components/Atoms.php b/apps/drupal-default/particle_helper/src/Components/Atoms.php similarity index 64% rename from apps/drupal/module/particle_theme/src/Components/Atoms.php rename to apps/drupal-default/particle_helper/src/Components/Atoms.php index 7933956a19..413f5c3184 100644 --- a/apps/drupal/module/particle_theme/src/Components/Atoms.php +++ b/apps/drupal-default/particle_helper/src/Components/Atoms.php @@ -1,6 +1,6 @@ makeHeader('My Cool Header'); ``` @@ -52,9 +52,9 @@ All custom Twig Extensions specific to Particle can be added here. ### Particle Tools Similar to _Components_, ParticleTools provide helper functions for theme -development. However, rather than return particle arrays these functions -are helpers for interacting with Drupal. For example, you may want to get the -theme path from a defined theme constant: +development. However, rather than return particle arrays these functions are +helpers for interacting with Drupal. For example, you may want to get the theme +path from a defined theme constant: ```php /** @@ -73,8 +73,8 @@ theme path from a defined theme constant: To use the Tools library in any php file again use Drupal's class resolver: ```php -/** @var \Drupal\particle_theme\ParticleTools\ParticleTools */ -$tools = \Drupal::service('particle_theme.particle_tools'); +/** @var \Drupal\particle_helper\ParticleTools\ParticleTools */ +$tools = \Drupal::service('particle_helper.particle_tools'); $theme_path = $tools->getThemePath(); ``` diff --git a/apps/drupal/module/particle_theme/src/TwigExtension/ParticleThemeTwig.php b/apps/drupal-default/particle_helper/src/TwigExtension/ParticleHelperTwig.php similarity index 81% rename from apps/drupal/module/particle_theme/src/TwigExtension/ParticleThemeTwig.php rename to apps/drupal-default/particle_helper/src/TwigExtension/ParticleHelperTwig.php index 62fa277d89..70e20309fc 100644 --- a/apps/drupal/module/particle_theme/src/TwigExtension/ParticleThemeTwig.php +++ b/apps/drupal-default/particle_helper/src/TwigExtension/ParticleHelperTwig.php @@ -1,19 +1,19 @@ - - - icon/other/arrow/reverse - Created with Sketch. - - - - - - -``` - -This allows you to use the color vars `var:color.fill="#000"` on path in SVGs. - ## Adjusting Formatting Configuration + This pattern uses [SVGO](https://github.com/svg/svgo) to format and optimize SVG files. You can adjust the configuration at Particle's root in `/.svgo.yml`. diff --git a/source/default/_patterns/01-atoms/svg/icons/README.md b/source/default/_patterns/01-atoms/svg/icons/README.md index 3bbe70c052..86c434d6c3 100644 --- a/source/default/_patterns/01-atoms/svg/icons/README.md +++ b/source/default/_patterns/01-atoms/svg/icons/README.md @@ -1,9 +1,11 @@ # SVG Pattern + The SVG is a special pattern in Particle that is designed to allow us to include SVG as CSS or inline. Furthermore, this pattern is setup to be optimized as a developer step via `npm run fmt:svg` or `npm run fmt`. ## Adding SVG + To add an SVG to the system, simply add it to `@atoms/svg/svg/` directory and run the format command. This step is **destructive**, so be aware of using source control to revert unintended changes. @@ -32,5 +34,6 @@ This allows you to place color variables on path, for example: This allows you to use the color variables `var:color.fill="#000"` on path. ## Adjusting Formatting Configuration + This pattern uses [SVGO](https://github.com/svg/svgo) to format and optimize SVG files. You can adjust the configuration at Particle's root in `/.svgo.yml`. diff --git a/source/default/lib/README.md b/source/default/lib/README.md index d971a17cf9..808fb5115b 100644 --- a/source/default/lib/README.md +++ b/source/default/lib/README.md @@ -1,4 +1,3 @@ # Design System Apps Create and store standalone applications within the Design System. - diff --git a/tools/generators/new-component/__tests__/new-component.test.js b/tools/generators/new-component/__tests__/new-component.test.js index 15b0a4a8f2..3c24287bc6 100644 --- a/tools/generators/new-component/__tests__/new-component.test.js +++ b/tools/generators/new-component/__tests__/new-component.test.js @@ -12,7 +12,7 @@ // return helpers // .run(join(__dirname, '../generators/app')) // .withPrompts({ -// chooseApp: 'app-node-pl', +// chooseApp: 'app-pl', // patternType: '02-molecules', // name: 'New Component Test', // }) diff --git a/tools/pl-paths.js b/tools/pl-paths.js index c8b134d5e5..230dff080f 100644 --- a/tools/pl-paths.js +++ b/tools/pl-paths.js @@ -6,7 +6,7 @@ const { patternPaths, navItems, // eslint-disable-next-line import/no-unresolved -} = require('../dist/app-node-pl/pl/styleguide/data/patternlab-data.cjs.js'); +} = require('../dist/app-pl/pl/styleguide/data/patternlab-data.cjs.js'); // Shape of patternPaths data: // diff --git a/tools/tests/accessibility/pa11y.js b/tools/tests/accessibility/pa11y.js index 196f87c529..58d7006960 100644 --- a/tools/tests/accessibility/pa11y.js +++ b/tools/tests/accessibility/pa11y.js @@ -5,7 +5,7 @@ const { PL_BASE_DOMAIN } = process.env; // The PL_BASE_DOMAIN environment variable should be set to override the default. const plRootDomain = PL_BASE_DOMAIN || '0.0.0.0:8080'; -const plRoot = `http://${plRootDomain}/app-node-pl/pl`; +const plRoot = `http://${plRootDomain}/app-pl/pl`; // urls comes from particle, includes all demo paths from atoms+ let urls = componentPaths.map((partial) => `${plRoot}/${partial}`); diff --git a/tools/tests/vrt/backstop-example-settings.js b/tools/tests/vrt/backstop-example-settings.js index 87b07446a4..851612ead5 100644 --- a/tools/tests/vrt/backstop-example-settings.js +++ b/tools/tests/vrt/backstop-example-settings.js @@ -6,7 +6,7 @@ const { partials } = require('../../pl-paths.js'); -const plRoot = 'http://0.0.0.0:8080/app-node-pl/pl'; +const plRoot = 'http://0.0.0.0:8080/app-pl/pl'; module.exports = () => { // Set which resolutions to take screenshots at.