@prodigy-finance/ui-core v3.1.6
UIF documentation website
Prodigy Finance UI Framework
Development
- Ensure NodeJS is installed
npm install
npm run build
to locally compile the static document sitenpm 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
- run:
bumpversion --part major
orbumpversion --part minor
orbumpversion --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. - Run
npm install
to ensure package-lock is updated - Run
npm run build
- amend the commit that was just created to include any changed code
- Push your tags to the git repo:
git push origin --tags
- 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?
- it has a good community and reasonably good documentation
- we've used it before to good effect in other React applications
- stories can be written easily (
.mdx
format) and be extended upon easily - paves the way for the proposed Design system the UX/UI teams have been discussing for a while
- 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 Testingbit too flakey in HTML Storybook landTODO: convert Jasmine to Jest testsor... don't- TODO: JS/jQuery components documentation
- TODO: Utility helper documentation
- TODO: Typography documentation
- TODO: All Basic components
- TODO: Form components
- TODO: Layout components
- TODO: Jenkins/Build/Deployments
- 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.