TASK :: Revise Drupal + Pattern Lab Directory Structure (#831)

* Revise Drupal Theme and App Dirs

* Update Module Name

* Rename PL App and Path

* Remove Node Prefix from Package

* Add markdown formatter, format markdown

* remove link from readme

* Tune up on fmt and pl webpack

Co-authored-by: Christopher Bloom <[email protected]>

.github/CODE_OF_CONDUCT.md

@@ -5,43 +5,43 @@
 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
 
 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,20 +55,23 @@ 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 [[email protected]](mailto:[email protected]). All
+reported by contacting the project team at
+[[email protected]](mailto:[email protected]). 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
 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
 

.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.

.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.

.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
 
 <!--
-How did you solve the problem? Did you update any documentation this affected? 
+How did you solve the problem? Did you update any documentation this affected?
 -->

README.md

@@ -1,40 +1,52 @@
 # 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)
 
 ## Provides
 
 - 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.

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`.

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'

apps/drupal/module/particle_theme/particle_theme.module → apps/drupal-default/particle_helper/particle_helper.module

@@ -2,18 +2,18 @@
 
 /**
  * @file
- * Contains particle_theme.module.
+ * Contains particle_helper.module.
  */
 
 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 .= '<h3>' . t('About') . '</h3>';
       $output .= '<p>' . t('Particle and Particle theme utilities') . '</p>';

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

apps/drupal/module/particle_theme/src/Components/Atoms.php → apps/drupal-default/particle_helper/src/Components/Atoms.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Drupal\particle_theme\Components;
+namespace Drupal\particle_helper\Components;
 
 /**
  * Provides ComponentMaker functions for Atoms.

apps/drupal/module/particle_theme/src/Components/Molecules.php → apps/drupal-default/particle_helper/src/Components/Molecules.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Drupal\particle_theme\Components;
+namespace Drupal\particle_helper\Components;
 
 /**
  * Provides ComponentMaker functions for Molecules.

apps/drupal/module/particle_theme/src/ParticleTools/ParticleTools.php → apps/drupal-default/particle_helper/src/ParticleTools/ParticleTools.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Drupal\particle_theme\Tools;
+namespace Drupal\particle_helper\Tools;
 
 use Drupal\particle\Particle;