diff --git a/.eslintrc.js b/.eslintrc.js new file mode 100644 index 0000000..a6d9136 --- /dev/null +++ b/.eslintrc.js @@ -0,0 +1,44 @@ +// http://eslint.org/docs/user-guide/configuring + +module.exports = { + root: true, + parserOptions: { + sourceType: 'module' + }, + env: { + browser: true, + jasmine: true, + }, + extends: 'airbnb-base', + // required to lint *.vue files + plugins: [ + 'jest', + ], + globals: { + jest: true, + test: true, + }, + // add your custom rules here + rules: { + // 4 space indent + 'indent': [ 'error', 4 ], + // Don't enforce a blank line or not at the beginning of a block + 'padded-blocks': 0, + // Don't enforce one-var for now + 'one-var': 0, + // Require spaces in array brackets, unless it's an array of objects + 'array-bracket-spacing': [ 'error', 'always', { 'objectsInArrays': false } ], + // Allow unary + and -- operators + 'no-plusplus': 0, + // don't require .vue extension when importing + 'import/extensions': ['error', 'always', { + 'js': 'never', + 'vue': 'never' + }], + // allow optionalDependencies + 'import/no-extraneous-dependencies': ['error', { + 'optionalDependencies': ['test/unit/index.js'] + }], + 'no-console': 0, + }, +}; diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3c3629e --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..86c9a7b --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2017 Matt Brophy + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..a4fd8bb --- /dev/null +++ b/README.md @@ -0,0 +1,234 @@ +# vue-themed-style-loader + +A Webpack plugin to be used in conjunction with [vue-loader](https://github.com/vuejs/vue-loader/) to assist in generating themed builds of a [Vue.js](https://vuejs.org/) application. + + +## Usage + +To use the `vue-themed-style-loader`, simply install the theme: + +``` +npm install --save-dev vue-themed-style-loader +``` + +And then add an entry to your webpack configuration file, after the `vue-loader`: + +```js + ... + module: { + rules: [{ + test: /\.vue$/, + loader: 'vue-loader', + options: { ... }, + }, { + test: /\.vue$/, + loader: 'vue-themed-style-loader', + options: { + theme: 'your-theme-name', + }, + }] + }, + ... +``` + +And then begin specifying themes in your Vue component styles: + +```vue +// Base theme + + +// Bold theme + + +// Underline theme + +``` + + +## Use Case + +Consider this simple Vue Single File Component that renders and styles a dynamic `

` tag: + +```vue + + + + + +``` + +### Themed display + +Considering applying different styling "themes" which will alter the color of the heading, which may normally be done via a parent CSS class: + +``` + +``` + +This will certainly work, however, it doesn't scale very well as your application and number of themes grows. The size of you stylesheet grows at least linearly with the number of themes, even though only one theme is likely being used at any given point in time. + +Instead, it would be ideal for our resulting stylesheet to only include the styles relevant to our current theme: + +```css +/* styles.css */ +.heading { color: black; } + +/* styles-red.css */ +.heading { color: black; } +.theme-red .heading { color: red; } + +/* styles-blue.css */ +.heading { color: black; } +.theme-blue .heading { color: blue; } +``` + +Or, even better, in the cases where a theme completely overrides a base style, it would be ideal to remove the base style altogether: + +```css +/* styles.css */ +.heading { color: black; } + +/* styles-red.css */ +.theme-red .heading { color: red; } + +/* styles-blue.css */ +.theme-blue .heading { color: blue; } +``` + +And, now that the base styles aren't being included, we no longer need the parent theme class anymore, and can reduce our output themed stylesheets to simply: + +```css +/* styles.css */ +.heading { color: black; } + +/* styles-red.css */ +.heading { color: red; } + +/* styles-blue.css */ +.heading { color: blue; } +``` + +This is exactly what `vue-themed-style-loader` set's out to do :) + + +## Example + +Let's alter the ` + +// "red" theme + + +// "red" theme + +``` + +Now, add the loader to your webpack config. It is important to note that because all webpack loaders are run from right-to-left (see (Pitching Loaders)[https://webpack.js.org/api/loaders/#pitching-loader]), the `vue-themed-style-loader` must be specified _after_ the `vue-loader`. this ensures it will execute _before_ the `vue-loader` to discard inactive themed style sections. + +Here's an example `webpack.config.js`: + +```js + ... + module: { + rules: [{ + test: /\.vue$/, + loader: 'vue-loader', + options: { ... }, + }, { + test: /\.vue$/, + loader: 'vue-themed-style-loader', + options: { + theme: 'red', + }, + }] + }, + ... +``` + +In this setup, with the `"red"` theme specified, the loader will only preserve unthemed and `theme="red"` ` + + + + +``` + +This will result in the base styles also being stripped, and _only_ the `theme="red"` styles being included in the output. If a single `replace` section is found for the active theme, then _all_ corresponding base styles will be stripped + +### Scoped styles + +The removal algorithm operates independently on normal and scoped style blocks. So, it can be chosen to replace in one scenario and inherit in another. For example: + +``` + + + + + + + +``` + +In this scenario, the scoped base style would be maintained because no scoped sections for the active theme specified the `replace` attribute. + +```css +.heading { font-weight: bold; } +.heading { color: red; } +.heading { text-decoration: underline; } +``` diff --git a/__mocks__/loader-utils.js b/__mocks__/loader-utils.js new file mode 100644 index 0000000..f8532e2 --- /dev/null +++ b/__mocks__/loader-utils.js @@ -0,0 +1,8 @@ +const loaderUtils = jest.genMockFromModule('loader-utils'); + +loaderUtils.getOptions = jest.fn(() => ({ + theme: null, + debug: false, +})); + +module.exports = loaderUtils; diff --git a/index.js b/index.js new file mode 100644 index 0000000..466ec31 --- /dev/null +++ b/index.js @@ -0,0 +1,138 @@ +const path = require('path'); +const compiler = require('vue-template-compiler'); +const loaderUtils = require('loader-utils'); +const _ = require('lodash'); + +// Given a key-value object of attributes, compose the attribute potion of the +// Vue Single File Component tag +// +// Example: +// genAttrs({ foo: 'bar', baz: 'qux' }) +// +// => ' foo="bar" baz="qux"' +function genAttrs(attrs) { + return _.reduce(attrs, (acc, v, k) => { + let attr = ` ${k}`; + if (v !== true) { + attr += `="${v}"`; + } + return acc + attr; + }, ''); +} + +// Given a tag and a vue-template-compiler section, re-generate the Single File +// Component structure +// +// Example: +// genSection('template', { +// attrs: { +// foo: 'bar' +// }, +// content: '

Hello World!

' +// }) +// +// => '' +function genSection(tag, section) { + if (!section) { + return ''; + } + const attrs = genAttrs(section.attrs); + const content = section.content || ''; + return `<${tag}${attrs}>${content}\n`; +} + +// Replace the contents for a given style block with blank lines so that +// line numbers remain the same as the input file +// +// Example: +// replaceWithSpacer({ +// content: '.class-name {\n color: red;\n font-weight: bold;\n}\n' +// }) +// +// => { +// content: '\n\n\n\n' +// } +function replaceWithSpacer(style) { + const lines = style.content.split('\n').length; + const spacer = new Array(lines).join('\n'); + _.set(style, 'content', spacer); +} + +// Given a style section from vue-template-compiler, generate the resulting +// output style section, stripping inactive theme style blocks +function genStyleSection(style, replacements, options) { + const blockTheme = _.get(style.attrs, 'theme'); + if (blockTheme) { + + if (blockTheme !== options.theme) { + // This style block specifies an inactive theme, replace the block + // with blank lines, so that line numbers remain the same as the + // input file + replaceWithSpacer(style); + } + + } else if ((replacements.global && !style.scoped) || + (replacements.scoped && style.scoped)) { + // This is an unbranded style theme and we've found an active theme + // 'replace' block elsewhere, so clear out these base styles + replaceWithSpacer(style); + } + + // Remove the 'theme' and 'replace' attributes from the output set of + // attributes since they're not really a Vue-supported attribute + _.set(style, 'attrs', _.omit(style.attrs, 'theme', 'replace')); + + return genSection('style', style); +} + +// Utility function to determine if this component contains theme replacement +// styles for global or scoped style sections. If so, we'll use those to clear +// out the corresponding base styles we encounter +function getReplacements(styles, options) { + // Is this block for the current active theme + const isActiveTheme = s => _.get(s.attrs, 'theme') === options.theme; + // Does the style block contain the replace attribute + const hasReplace = s => _.get(s.attrs, 'replace'); + return { + global: styles.filter(s => !s.scoped && isActiveTheme(s)) + .find(s => hasReplace(s)) != null, + scoped: styles.filter(s => s.scoped && isActiveTheme(s)) + .find(s => hasReplace(s)) != null, + }; +} + +function vueThemedStyleLoader(source) { + // Grab options passed in via webpack config + const options = _.defaults(loaderUtils.getOptions(this) || {}, { + theme: null, + debug: false, + }); + + // Parse the Vue Single File Component + const parts = compiler.parseComponent(source); + + // Generate the singular