@revium/ada-component-library

ADA Component Library

More information can be found in sec/Introduction.stories.mdx

Dev Notes

• While we attempt to copy as little code as possible through using web components it is not always possible, so when updating an already complete component make sure to to search all and update every instance
• Because this repo is mainly HTML and code is hard to re-use. We want to have a minimalist approach where we are writing the smallest amount of code possible that:
  • Allows us to test all scenarios correctly
  • Display correct functionality and code to the end user
• This means that we are not copying the design files word for word but simply having enough content to show everything we need to
  • The header is a good example of this.
• Add the component name as a class to each component you create e.g for "sliderInline" the classes "slider slider-inline" should be added
  • This is so we can target these containers/components once copied - if needed
• Use the class ada-container to add website padding and content max widths
  • This class should always be on its own div to prevent issues with padding etc e.g. <div class="ada.container">{ component content }</div>
• To make a container non clickable the "container-hover" class will be removed and "cursor-default" class added

Web Components

Web components are used to help prevent code being copied and pasted (making the repo hard to maintain)

Creating and using a web components

Global: globally registered web components which can be used in all html files

• import and export your component (html file) into web-components.js (following the file conventions)
• The web component will be in kebab case and start with ''ada'
  • so a component with name thisIsAComponent will be called ada-this-is-a-component as a web component
• Save all and you are now ready to use the web component <ada-this-is-a-component?></ada-this-is-a-component> in other html files

Local: Web components registered in a specific file

• This should only be used for small segments of html that are reused only within the one file
• Place the below script at the bottom of your html file
  • Add in a name making sure it starts with 'ada' in kebab case (an error will be thrown if you mess up the casing)
  • Add in your code and its ready to use

<script>
  window.customElements.define(
    'INSERT YOUR NAME HERE',
    class MyComponent extends HTMLElement {
      connectedCallback() {
        this.innerHTML = `INSERT YOUR CODE HERE`
      }
    }
  )
</script>

Notes

• It is important that all web components start with 'ada' as this is used to remove the web-component wrappers in storybook
• Web components are for DEV ONLY and are not to be shown in storybook or used outside of this repo

Images

• Images are served over imageboss to allow for image optimization
• In most cases setting the src width to match the max-image width is sufficient
  • The src for an image with a max-width of 500px would look like the below:

  src="//img.imageboss.me/ada-web4/width/500/getmedia/bf578648-3b56-414e-9071-ae848c37b059/card-doctor2.png"
  

• For full width images where the image can get large on desktop screen srcset should be used
  • For more information see mdn
  • If the max-width of the image was 1200px then you would remove the 1536px breakpoint from both "srcset" and "sizes"
  • To test open the image in a new tab in both a small and large breakpoint and the image source widths should be different (you may need to refresh the page at each breakpoint)

srcset="
//img.imageboss.me/ada-web4/width/640/getmedia/bf578648-3b56-414e-9071-ae848c37b059/card-doctor2.png   640w,
//img.imageboss.me/ada-web4/width/768/getmedia/bf578648-3b56-414e-9071-ae848c37b059/card-doctor2.png   768w,
//img.imageboss.me/ada-web4/width/1024/getmedia/bf578648-3b56-414e-9071-ae848c37b059/card-doctor2.png 1024w,
//img.imageboss.me/ada-web4/width/1280/getmedia/bf578648-3b56-414e-9071-ae848c37b059/card-doctor2.png 1280w,
//img.imageboss.me/ada-web4/width/1500/getmedia/bf578648-3b56-414e-9071-ae848c37b059/card-doctor2.png 1536w
"
sizes="(max-width: 640px) 640px, (max-width: 768px) 768px, (max-width: 1024px) 1024px, (max-width: 1280px) 1280px, 1536px"

Vue components

• Vue components are only to be created when smooth FE transitions are needed for variable data components

Creating and using a vue component

• Create your vue component following the file conventions already layed out
• The html element your vue component will be attached to (which will be contained in the stories file) should look like the below:

<div
    class="ada-container vue-app"
    data-vue-app-type="YOUR COMPONENT NAME HERE"
    data-context='INITIAL COMPONENT SETTINGS HERE'
></div>

• in js/components/vue.js import your vue component and add it into the vueAppComponents object like below

const vueAppComponents = { ..., YOUR COMPONENT NAME HERE }

Notes

• The component name and file name must match exactly
• The json contained in data-context will be available via props as a 'data' attribute

const props = defineProps(['data'])

Quick start

• install dependencies: yarn
• start storybook: yarn dev
• components (.html) and stories (.stories.js) are located in ./src/**/*{.html, .stories}

Themes

• New themes can be created by adding new .js file into themes folder
• update .env with the new name and run command yarn build
• Theme support for storybook and deploying 2 themes has not yet been setup

Deploying New Versions

• update package version

  • npm version [major | minor | patch ]

• Build production ready code:

  • yarn build

• push updates

  • git push --all

• publish new version to npm (requires login details)

  • npm publish
  • yarn vercel --prod

Versioning

Always update the version of the package to represent what changed.

Semver versioning is used i.e v1.2.3 (Major = 1, Minor = 2, Patch = 3)

When	New version
A bug is fixed	1.2.4
A new component is introduced	1.2.4
A component is changed in a non-breaking way	1.3.0
A component is changed in a breaking way	2.0.0