UIF documentation website

Prodigy Finance UI Framework

• Development
  • Development
  • Versioning UIF
• Use of jQuery in UIF.
• Storybook JS
  • Why Storybook?
• Using the NPM package
• Using the GEM
  • Add the Ruby Gem
  • Use the SCSS
  • Use the JavaScript
• TODOs

Development

• Ensure NodeJS is installed
• npm install
• npm run build to locally compile the static document site
• npm run develop to run a development server of Storybook

Development

• When making a change to code, please follow the Changelog convention
• Each push to master will trigger a re-build of the latest minor version of the documentation to the docs site
• When wanting to publish a new version of the NPM package or Gem, follow the Versioning guidance below.

Versioning UIF

Versioning is best managed via the Bumpversion gem: gem install bumpversion

When you're done developing a new release/tag and have successfully merged into the master branch

1. run: bumpversion --part major or bumpversion --part minor or bumpversion --part patch, depending on what action you are performing. This will automatically bump up all the files that have reference to the version number of UIF, as well as adding a git tag and committing to master. Follow Semantic Versioning for guidance on whether your change is considered major, minor, or a patch.
2. Run npm install to ensure package-lock is updated
3. Run npm run build
4. amend the commit that was just created to include any changed code
5. Push your tags to the git repo: git push origin --tags
6. Push up master: git push origin master

Use of jQuery in UIF.

As of version 2, jQuery has been removed from UIF, but is still a dependency if you wish you use any of the jQuery components. If you wish to still use jQuery you will need to include it in your own project manually, and ensure it is embedded in your project BEFORE any UIF JS components are initialised.

This is because the version we we using was becoming increasingly out of date, and was becoming a security vulnerability for applications that used UIF but none of the jQuery dependent plugins.

If you do not use any of the JS components that leverage jQuery (the documentation pages for each of the components should outline if it is needed), this should not effect you.

Storybook JS

There is an ongoing experiment to migrate all existing documentation of UIF across to another documnentation service. Right now we are trialling Storybook JS, with the intent to move away from the customer written Grunt framework we've used previously.

Right now Storybook is in Beta and will generate documentation alongside the existing docs. In the short term, there will be a certain amount of duplication of effort to ensure any new components added during this time are reflected in both places until we reach a point where one single source of documentation can rule.

Update: honestly, trying to get jQuery working within Storybook's webpacker is not a task I'm willing to undertake at this point. So right now, the UIF components that rely on jQuery/JS are being kept in the old Grunt-generated documentation. This is probably fine, as I'd suggest until we have a better idea of how we do JS across Prodigy's admin applications, we carefully consider whether we should add more JS functionality into UIF at all.

Why Storybook?

1. it has a good community and reasonably good documentation
2. we've used it before to good effect in other React applications
3. stories can be written easily (.mdx format) and be extended upon easily
4. paves the way for the proposed Design system the UX/UI teams have been discussing for a while
5. no security vulnerabilities (I'd really like to not have Liam and Tim asking me to upgrade grunt-handlebars again, please)

Using the NPM package

The UIF NPM package is hosted on Prodigy's internal npm server. You will need to have credentials in order to access it. These credentials are available on 1Password in the TechSharedServices vault. Alternatively, talk to the security team if you need access.

npm install @prodigy-finance/ui-core

including CSS in project vary from framework to framework, but broadly:

import "@prodigy-finance/ui-core/src/styles/images.scss";
import "@prodigy-finance/ui-core/src/styles/screen.scss";

Using the GEM

The UIF gem is hosted on Prodigy's internal gem server. You will need to have credentials in order to access it. These credentials are available on 1Password in the TechSharedServices vault. Alternatively, talk to the security team if you need access.

Add the Ruby Gem

In the Rails app's Gemfile:

gem 'ui_core', [version]

Use the SCSS

In the app/assets/stylesheets/application.css.scss:

// All the base scss
@import "screen";

// All the image scss
@import "images";

Use the JavaScript

Only if you need to use JS in your application. In app/assets/javascripts/application.js import the component you need. Note that while some components auto initialise, others will need to be configured within a startup script.

//= require modules/jquery.pfAccordion
//= require modules/jquery.pfAutoComplete
//= require modules/jquery.pfFlyOut
.
.
.
//= require jquery.pfUIF

TODOs

• [ ] ~~TODO: Storybook Snapshot Testing~~ bit too flakey in HTML Storybook land
• [ ] ~~TODO: convert Jasmine to Jest tests~~ or... don't
• [x] TODO: JS/jQuery components documentation
• [ ] TODO: Utility helper documentation
• [ ] TODO: Typography documentation
• [x] TODO: All Basic components
• [x] TODO: Form components
• [x] TODO: Layout components
• [x] TODO: Jenkins/Build/Deployments
• [x] TODO: Investigate making code snippets render HTML, not the JS used to render stories
• [ ] TODO: as part of every build, push compiled CSS to a public CDN so that folks can link to styles directly without requiring a build step.
• [ ] TODO: motivate to open-source this and publicly publish NPM package - would make installation (and adoption) far simpler.