@vcita/design-system 1.1.8 → 1.1.9

package/README.md

@@ -1,179 +1,221 @@
 # design-system
 
-link to storybook
-https://vcita.github.io/design-system
+You can find storybook [here](https://vcita.github.io/design-system)
 
-## Goals
+This project's goal is to create a set of tools that will enable future development to be quicker and more standard, while providing the vcita flavor.
 
-This project's goal is to create a set of tools that will enable future development to be quicker and more standard.
-
-## Creating components
-
-### The concept
-
-The components in this package are project agnostic. They should not contain anything that is specific to any project.
-Development will proceed by using the storybook.
+### Getting started
+```
+npm i @vcita/design-system
+```
 
-### Requirements
+### External Dependencies
 
-1. Input variables will be well defined and validated
-2. Components should be constructed so that they are composable - slots are your friends
+This package depends on [Vuetify](https://vuetifyjs.com/en/getting-started/installation/) as an external dependency, so your project must have it installed.
+Currently, the needed version is 2.4.0, we will update this from time to time.
 
-### Code standards
+### Initializing in your project
+To initialize the project create plugins/designSystem.js
 
-1. The component name will start with Vc and be camel cased. example: VcComponent.vue
-2. Emitted events will start with "on" and be camel cased. example: 'onButtonClicked'. Except for standard events such
-   as "click" or "input".
-3. Don't use v-bind="$attrs" and v-on="$listeners", that's not the way. If you find yourself needing a lot of props, you
-   may need to implement it using a render function instead.
+```
+// plugins/designSystem.js
+import DesignSystem from '@vcita/design-system';
+import DesignSystemInit from '@vcita/design-system/init/DesignSystem';
+import Vue from "vue";
 
-### Guidelines and best practices
+Vue.use(DesignSystem);
+export default DesignSystemInit();
+```
 
-Every component that is created in this project should have the following things:
+Import into src/main.js and into the vue initialization
+```
+// src/main.js
+import ds from './plugins/designSystem';
 
-Unit test file with 100% coverage.
+new Vue({
+    ...
+    vuetify: ds,
+    ...
+    render: h => h(App)
+  }).$mount("#app");
+```
 
-A storybook page with the following data
+If you need to also adjust some values, such as theme or configurations, it will look something like this:
 
-1. link to Figma page with the design of the component
-2. controls definition that allows to manipulate the component parameters
-3. use actions to demonstrate the output of the component in terms of emitted events and data
-4. display variations will be clearly presented
+```
+// plugins/designSystem.js
+import Vue from "vue";
+import DesignSystem from '@vcita/design-system';
+import DesignSystemInit from '@vcita/design-system/init/DesignSystem';
 
-Consider localization issues, such as:
+Vue.use(DesignSystem);
 
-1. Texts that are set to uppercase by Vuetify need to be changed to text-transform: initial;
-2. Date formatting should be flexible according to different localizations
-3. components should not contain any constant texts, all texts must be passed in as a parameter.
+const config = {
+                  // Your configuration choices
+               };
 
-## Adding component to the package
+export default DesignSystemInit(config);
+```
 
-Add to src/components/index.js an entry for your new component, something like:
+All configuration options are specified [here](#available-configuration-options)
 
+### Applying the styling to your project
+create the file src/styles/variables.scss and edit to fit your needs. you may only need the import statement.
 ```
-export { default as VcYourComp } from './VcYourComp/VcYourComp.vue';
+@import "~@vcita/design-system/styles/variables.scss";
 ```
+In order to load the variables.scss file, add this to src/main.js
+```
+import "@/../styles/variables.scss";
+```
+The src/styles/variables.scss file can be used to override some styling variables.
+You can do this by specifying a different value to one or more of the css variables that have been provided.
 
-## Styling
-
-### Design tokens and themes
-
-Since we want these components to be flexible enough that they can be used in multiple projects, we will be using
-variables to apply most of the design characteristics of each component.
-
-Colors will be applied by using the vuetify theme, as defined in preview.js
-
-Other design variables will be defined in TBD. Each project that uses this package will assign its own values to the
-design variables, and thus control its own design. Please be thoughtful when adding and using the design variables in
-your components.
-
-### Styling best practices
-
-1. Values such as margins or padding will be set using css variables, so that each project can adapt the design if need
-   be. The initial values will be set in the @/styles/variables.scss file.
-2. Changes and additions to general css variables will be documented in the @/stories/welcome.stories.mdx file
-3. Changes and additions to components specific css variables will be documented TBD
-4. Brand colors will be applied using the Vuetify theme, not through parameters. You can add values to the theme in
-   .storybook/preview.js
-
-### Using Vuetify SASS variables
-
-Changes to default SASS variable values can be made in styles/variables.scss
+For example, to use another font
+```
+body {
+  --primary-font-family: YourFont;
+}
+```
+All component styling options are specified [here](https://vcita.github.io/design-system/?path=/story/variables--page)
 
-When styling using the Vuetify SASS variables, please consider two situations:
+### Using the components
+You can now use the components from the new library anywhere in the application, as you normally would
+```
+<VcButton>label</VcButton>
+```
 
-1. The styling decision you are making will be correct across all projects that use this package, in which case the
-   value can be a constant
-2. the styling decision you are making should be adjusted for different projects. In that case, use the css variables
-   option, for example:
-   ```
-   $body-font-family: var(--primary-font-family);
-   ```
-   This will allow each project to apply their own value. The css variables must be documented.
+### Available configuration options
+#### Theme
+The default theme values are based on default vcita colors, but they can be set according to the current business.
+Please note that colors must be set as hex values.
 
-### Running Storybook
+To facilitate that the file colorUtil.js has been included, which contains the following functions:
+- rgbToHex() - Use this to convert rgb values to hex values.
+- hexToRgb() - If you have other areas in your project that require rgb format, you can use this to convert any hex values to rgb.
+- pSBC() - This function can calculate various opacity levels, based on an initial color, and return them in hex or rgb formats, as needed
+```
+// stringUtil.pSBC(opacity, baseColor)
+stringUtil.pSBC(0.6, this.secondaryColor)
+```
 
+##### During startup
+This is how they can be set during startup of the app:
 ```
-npm run storybook
+// plugins/designSystem.js
+const config = {
+    theme: {
+        primary: '#0C315E',
+        secondary: {
+            base: '#0093B8',
+            lighten1: '#99D4E3',
+            lighten2: '#C2E5EE',
+            lighten3: '#EDF7FA'
+        },
+    }
+}
 ```
+##### During runtime
+```
+import colorUtil from '@vcita/design-system/utils/colorUtil.js';
 
-### Ongoing development
+this.$vuetify.theme.themes.light.primary = colorUtil.rgbToHex(this.primaryColor);
+this.$vuetify.theme.themes.light.secondary = {
+  base: colorUtil.rgbToHex(this.secondaryColor),
+  lighten1: colorUtil.pSBC(0.6, colorUtil.rgbToHex(this.secondaryColor)),
+  lighten2: colorUtil.pSBC(0.76, colorUtil.rgbToHex(this.secondaryColor)),
+  lighten3: colorUtil.pSBC(0.93, colorUtil.rgbToHex(this.secondaryColor))
+}
+```
 
-In many cases, you don't want to publish the package each time you make a change. In those cases it can may life much
-easier to install the package from your local project directory.
-To learn how to do this, please go  [here](https://myvcita.atlassian.net/wiki/spaces/FG/pages/2021851137/Using+the+vcita+design+system+package#Installation-for-development-purposes).
+### Localization
 
-Note: before releasing, make sure to publish a version and use that in your project, or tracking version changes will
-become impossible.
+There are a few components that contain localized strings.
+For example, the wizard and modaql components.
+By default, the texts will be presented in English, so should you need to display them in another locale, this is now you can set the locale as needed.
 
-### Publishing the package to npm
+Available locales:
+en, de, es, fr, he, it, nl, pl, pt, ru, sl, tr
 
-You may first need to run
+##### During startup
 
 ```
-npm adduser
+// plugins/designSystem.js
+import DesignSystemInit from '@vcita/design-system/init/DesignSystem';
+...
+const config = {...};
+const locale = 'yourSelection';
+export default DesignSystemInit(config, locale);
 ```
 
-Publishing beta version
+##### During runtime
 
+In a component, such as App.vue, add this call
 ```
-git commit -a
-npm version [currentVersion]-beta.[NumOfBeta]
-npm run build
-npm publish --tag beta
+// App.vue
+this.$ds.setLocale(locale);
 ```
 
-Publishing regular version
+## Component configuration options
+### VcTextField
+#### Usage of VcTextField with googleAddressAutoComplete set to 'true'
 
 ```
-git commit -a
-npm version [newVersion]
-npm run build
-npm publish
+// plugins/designSystem.js
+const config = { 
+                  options: {googleAppKey: 'yourGoogleAddressKey'}
+               };
 ```
 
-### Run your unit tests
-
+### VcToast
+#### Change VcToast default timeout
+By default, the VcToast timeout is 3000ms.
+You can change that for a specific instance by setting the timeout prop to your desired value.
+In case you want to change that for the entire project, so any instance will use another timeout value, it can be done by calling this code
 ```
-npm run test:unit
+// plugins/designSystem.js
+const config = {
+                  options: {toastTimeout: 5000 }
+               };
 ```
+This will set the default timeout for all instances of VcToast in your project.
+Any instance that is getting a different value in the timeout prop will keep using that value.
 
-### Lints and fixes files
-
+## Adding external icons
+The package comes with a set of icons already included, which can easily be displayed using the VcIcon component.
+It is possible to extend that set by creating an object with key-value format
 ```
-npm run lint
+export default {
+    yourKey1: `<svg ... /></svg>`,
+    yourKey2: `<svg ... /></svg>`,
+}
 ```
 
-### Initializing in your project
-
-To initialize the project
-
+And passing that to the DesignSystem initialization
 ```
-import DesignSystem from '@vcita/design-system';
-import Vue from "vue";
-
-Vue.use(DesignSystem);
+// plugins/designSystem.js
+import extIcons from './yourFile.js';
+const config = { 
+                  extIcons
+               };
 ```
-
-If you need to also adjust some values, such as theme or configurations, it will look something like this:
-
+Then to use the icons
+```
+<template>
+    <VcIcon>$yourKey1</VcIcon>
+</template>
 ```
-import Vue from "vue";
-import DesignSystem from '@vcita/design-system';
-import DesignSystemInit from '@vcita/design-system/init/DesignSystem';
 
-Vue.use(DesignSystem);
+### Automation hooks
+In order to facilitate automation, each design system component has a prop called dataQa. 
+This prop has a default value matching the component's name.
+The value set in this prop will become an attribute on the component instance, which you can use in your automation code, to easily locate the component on the page.
 
-const config = {
-                  theme: { primary: '#123456'}, 
-                  options: {toastTimeout: 5000 }
-               };
-
-export default DesignSystemInit(config);
-```
+To differentiate different instances, you can pass different dataQa values to different instances.
 
-### Customize configuration
+[//]: # (### Customize configuration)
 
-See [Configuration Reference](https://cli.vuejs.org/config/).
+[//]: # ()
+[//]: # (See [Configuration Reference]&#40;https://cli.vuejs.org/config/&#41;.)
 
 

package/config/locales/ds.en.yml

@@ -11,7 +11,7 @@ en:
     progress_circular:
       next: 'Next:'
     listbox:
-      add: Add new contact
+      add: Add new item
       empty_list: No result found
     dropzone:
       default_title: Submit