Front-End Framework Upgrade

Project setup

Prerequisites

Important: You need node ^10.15.0 to run this. NVM (https://github.com/creationix/nvm) is recommended for switching local node/npm versions.

Install packages

npm install

Install AVN to controll your node version based on the project

npm install -g avn avn-nvm avn-n
avn setup

Compiles and hot-reloads for development

npm run serve

Compilation for production

We're trying to build a stand alone library that people can use as external dependency. Therefore we're using a library target through vue-cli-service, which will make UMD and CommonJS exports. The first one can be used along with ES6 (ESM) modules to include all or specific components.

IMPORTANT: Currently the build process is a bit cumbersome, and includes a few steps:

1. Add your components in library.js - there's a list of components we're currently exporting, and you must add yours there, or it won't be exported (read comments in file to learn how)
2. Build the library using npm run build
3. Commit /dist folder
4. Publish new library

All steps are important and skipping any would fail the usage of the library!

TODO:

Build & Testing

[ ] Find a way to automate building the library file and remove any human labor [ ] Find a way to make the build on prepare hook (present in npm), but keep in mind this will require npm install as well :( files section in package.json is important here, but again with npm (not sure about yarn) [ ] Find a way to build a real ESM package [ ] Test tree shaking [ ] add some tests to events (Button was emitting twice!) [ ] checkout lint-stage and eslint cli - currently commit takes forever; seems it does not work for storybook - https://eslint.org/docs/user-guide/command-line-interface [ ] currently only the Storybook includes the Flexibility flexbox polyfill. This needs to be implemented in the library build as well as the normal serve build. [ ] we use a script to conditionally load the Flexibility lib. The lib URL has to be extracted in an env var in the client project. [X] fix eslint to work properly with jest tests! [X] talk to Yasen and decide on global aliases (@src, or @ to point to src folder - jest is using only @, I've added both, but we need to unify) [ ] check this file building process: https://www.npmjs.com/package/directory-metagen [X] see how to use require.context in tests, as they now cannot work properly :( read full comment in ModelsManager.test.js [X] check eslint rule prefer-destructuring and see how to remove it for arrays only - cannot understand how can we use it when calling this.existingProp = this.array[0]; check FinalistsExpander [ ] ask some cli magician to enable test coverage with jest (so we know how much test we've covered); a starting point: https://vue-test-utils.vuejs.org/guides/#testing-single-file-components-with-jest & https://stackoverflow.com/questions/53249858/how-to-make-test-coverage-show-all-vue-files-in-vue-cli-3-using-jest [ ] describe what's the problem with jest testing (globalSetup can't use ESM, and we need it in order to register RampitFramework plugin)

Moving & Renaming

[ ] merge PositionModel & DirectionModel [ ] remove enumeration for native events (click, mouseover, mouseout, etc.) [ ] check all enumerations for events to use kebap-case [ ] fix all variables in scss to use simple kebap-case [ ] rename all models to exclude Model suffix [ ] rename ActivateEvent to ActivationEvent? [ ] Rename "Process Slide CardS" to singular (some files and names are not)

Refactoring

[X] introduce enum with all event names thrown in the framework [X] add common mixins to global scope (flex, flex-centered, etc), and use them wherever possible [X] design a system about styles, in which each component has it's own extracted variables in a global scope, for easy overriding later on (start with FaqHorizontal) [ ] make some common way to deal with sizes/distances - we cannot connect this to font size or padding [ ] style components to look exactly like vanilla branch design [ ] make global transitions and use them everywhere [ ] make global <transition name=""> and use them when needed [X] check and fix vue types sensibles -> https://github.com/dwightjack/vue-types#native-types-configuration [ ] address model loading in prop definitions, e.g. test: Models.TestModel().def([]). These need to be simplified or the linter rule that requires this construct to be disabled. [ ] all organisms should use the LoadingStateMixin - check how to setup preloader and define basic names for transition! [ ] test vue-types when passing object (TooltipCard can accept align="Align.LEFT", which is false/undefined, but it doesn't throw an error) [ ] figure out how to shield window/document access in the whole system (maybe wrapper), so that nuxt doesn't cry [ ] think of a global way to fire router events, so urls can be changed (yeah I know)

Discussion

[x] check all models and define what an "id" is (type) - talk to Yasen or make him do it (-- ID should be an integer for now) [ ] check all sample data and convert IDs to INTEGERS! [ ] check all sample data and unify entities main text (text, title, heading) [ ] discuss slider transition in News Promogrid

Components

Modals

[ ] add a global overlay functionality, that can be toggled (used in NavigationBasic, NewsPromogrid, everywhere with modal!) [ ] add a global helper to toggle body classes (NavigationBasic) [ ] add a global key listener that can be triggered on an off, so we can close some modals or whatever is needed through ESC key (would also help us in the longer run when talking about keyboard navigation around components) [X] add overflow: hidden to body when triggering Models (check todo above) [X] fix BEM classes in ModalBase

Judges

[X] fix Judges, so buttons use icons, and not < and X [ ] use JudgePreview in JudgesPreviewBasic [ ] clear JudgesSection [ ] unify styles into one file (probably styles/components/_judges.scss)

[X] check out Paragraph.vue - it has some creepy props like hidden which blows my mind [X] revamp TooltipCard - position left means tooltip is on the left side, therefore tooltip should be on the right (currently vice versa) [ ] rewrite SimpleCard.vue [ ] Link component has some troubles with borders - check out TimelineVertical and hover over a button's card - you can see blinking because of 1px extra border. Fix that. [ ] fix Slider component - piecewise parts have no idea of component's height, and therefore positioning is super hard; we also need a proper way to set width/height, and since we use this in css maybe it's a good idea to remove those properties at all? [ ] fix NewsItem on mobile to get more space for text :) [ ] check ProcessStepCard && CardFlipper styles - use style--inversed for the pagination [ ] refactor TooltipCard to use inset box shadow instead of border - the problem is with expandable block - it uses scrollHeight, which does NOT include margins nor borders :) [ ] refactor Image component - bem classes, max-width (100%), etc. Also maybe rename to Photo? [ ] extract categories and filtering functionality from FinalistsExpander and NewsPromogrid into a beautiful mixin :) [ ] extract custom pagination from FinalistsExpander and JudgesSideBySide [ ] set proper fonts (& props) to all atoms (Paragraph at least should be Montserrat) [ ] check grid problem in FinalistsExpander - :md="Math.floor(12 / itemsPerRow)" - some watcher in grid or something with initial value related

Documentation

[ ] describe the whole ordinal concept in Confluence

Compiles and minifies for production (old way)

Old way of building the project for production

TODO: Maybe we should ditch this and make the regular build a library one?

npm run build

Run your tests

npm run test

Lints and fixes files

npm run lint

Run your unit tests

npm run test:unit

Currently supported browsers

As required, we support "latest version of all major browsers plus IE11". Our setup looks like this:

"browserslist": [
  "> 1%",
  "last 1 version",
  "not ie < 11"
]

As of today (18.10.2018) the list of supported browsers is:

and_chr 69
and_ff 62
and_qq 1.2
and_uc 11.8
android 67
baidu 7.12
bb 10
chrome 69
chrome 68
edge 17
firefox 62
firefox 61
ie 11
ie_mob 11
ios_saf 11.3-11.4
ios_saf 11.0-11.2
op_mini all
op_mob 46
opera 55
safari 12
safari 11.1
samsung 7.2

Flexbox polyfill for IE

The majority of the components use either directly flexbox properties in the SCSS, or use the layout grid (Row.vue and Col.vue), which also depends on flexbox. Flexbox is not 100% supported by IE11, so we need to include a polyfill to fill in the missing/buggy functionality IE provides. We use the most popular flexbox polyfill out there - https://github.com/jonathantneal/flexibility

There are a few requirements to allow it to work:

1. All SCSS class declarations which include display: flex; should also include -js-display: flex; to allow the JavaScript polyfill to target those problematic divs. However, we've included a PostCSS loader in the Webpack config (more specifically postcss.config.js), which does this automatically.

2. A library needs to be included in the head of the document. However, we need it included on IE11 only, therefore we only add the library if we're on IE11. Include this script tag as early in the of the document as possible:

<!-- Flexibility for IE flexbox support -->
<script>
(function() {
  function isIE11() {
    var ua = window.navigator.userAgent;
    if (ua.indexOf('Trident/') <= 0) {
      return false;
    }

    var rv = ua.indexOf('rv:');
    return parseInt(ua.substring(rv + 3, ua.indexOf('.', rv)), 10) === 11;
  }

  var flexibilityScript = document.createElement('script');
  if (isIE11()) {
    flexibilityScript.src = 'https://cdn.rawgit.com/jonathantneal/flexibility/master/flexibility.js';
    document.head.appendChild(flexibilityScript);
  }
})();
</script>
<!-- /Flexibility for IE flexbox support -->

3. Then when the markup to be polyfilled is loaded, run:

flexibility(document.documentElement);

This can be either on document load, using a MutationObserver or on every route change in case we use vue-router, because the markup changes and all changes need to be polyfilled.

Releasing a new version

1. Make changes to the develop branch.
2. When ready, do npm version patch. This bumps the versions in the package.json file and automatically adds this change as a commit to git.
3. Push to develop and open a PR to merge it to master.
4. Once the PR is merges, Pipelines is notified and it deploys the new version to our private npmjs registry - https://www.npmjs.com/package/@rampit/fef

Using the Front-end Framework in client projects

1. Login to npmjs with the credentials supplied by Rampit personnel - npm login --scope=rampit
2. Require the package as an external dep - yarn add @rampit/fef --save
3. Enjoy!