@ama-pt/agora-design-system 0.1.1

package/README.md

@@ -0,0 +1,292 @@
+# Ágora Design System
+
+<b>The main purpose of this Storybook is the development of a design system library with React Js and Next Js , accessible and easy to configure.</b>
+
+## Core technologies
+
+- React - version ^18.0.25 - <https://reactjs.org/>
+- NextJs - version 13.0.4 - <https://nextjs.org/>
+- Storybook - version ^6.5.13 - <https://storybook.js.org/docs/react/get-started/install>
+- Tailwindcss - version ^3.2.4 - <https://tailwindcss.com/docs/installation>
+- Radix-UI - <https://www.radix-ui.com/docs/primitives/overview/introduction>
+- Node - version ^16
+
+## Useful Links
+
+- StoryBook Dev - <https://qld-portal-unico.northeurope.cloudapp.azure.com>
+- StoryBook UX-Review - <https://dev-portal-unico.northeurope.cloudapp.azure.com:8180>
+- Tailwind CSS Cheat Sheet - <https://tailwindcomponents.com/cheatsheet/>
+- Sonnar - <https://ticappsonar.northeurope.cloudapp.azure.com/sonarqube/dashboard?id=portal-unico-storybook-agora>
+- Nexus - <https://ticappsonar.northeurope.cloudapp.azure.com/nexus/#browse/browse:npm-general:%40ama%2Fagora-design-system>
+- Figma (UX Design) - <https://www.figma.com/files/project/60863393/Ágora-Design-System>
+- ZeroHeight - <https://zeroheight.com/1be481dc2/p/2861fa-boas-vindas>
+- AccessMonitor (Acessibilidade AMA) - <https://accessmonitor.acessibilidade.gov.pt/>
+- W3Validator - <https://validator.w3.org/nu/>
+- Axe DevTools - <https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?utm_source=deque.com&utm_medium=referral&utm_campaign=axe_hero>
+
+## Installation and start project
+
+```sh
+> npm install
+> npm run storybook
+
+```
+
+This will generate logs like in the screenshot and locally launch the application
+
+![Alt text](./docs/assets/start-storybook.png 'Title')
+
+## Build project
+
+Generating the project build helps us to understand if everything is ok and ready to a production environment. It is recommended to use this each time a component is terminated.
+
+```sh
+  > npm run build-storybook
+```
+
+## Format all files with Prettier config
+
+To keep code and commits easy to read a custom config was made to format files to everyone on the same way. We can force this format running. The formatter runs on every file and fix them.
+
+```sh
+  > npm run format
+```
+
+## Check Lint and Lint fix
+
+Using this to runs ESLint and find problems with syntax. Some we can fix with lint-fix. Others we have to make some changes.
+
+```sh
+  > npm run lint
+  > npm run lint-fix
+```
+
+<b>NOTE: Both (Build and Lint commands) help to ensure Sonnar scan to run smoothly.</b>
+
+## Project Structure
+
+![Alt text](./docs/assets/main-structure.png 'Title')
+
+All additional files generated by tools and are not required to any part of the project, must be added to the **_.gitignore_** file.
+
+### **Folder _.storybook_**
+
+![Alt text](./docs/assets/storybook-folder.png 'Title')
+
+- _mains.js_ - the main reason to edit this file are to add new addons to storybook, order stories folders and add new static dirs.
+
+- _manager-head.html_ - configure favicon of storybook app
+
+- _manager.js_ - call our custom theme
+
+- _preview.js_ - configure and call theme and other configurations of storybook
+
+- _theme.js_ - custom theme, allow change logos, fonts, url of logos, etc.
+
+### **Folder _dist_**
+
+![Alt text](./docs/assets/dist-folder.png 'Title')
+
+When run the command bellow this will generate the folders above. This folder contains building files to our future lib. We can run this to check structure but this isn't used on development only when we publish.
+
+```sh
+  > npm run build
+
+```
+
+### **Folder _docs_**
+
+Contains assets to support this README file.
+
+### **Folder _infractructure_**
+
+Contain file for Apache configuration.
+
+### **Folder _src_**
+
+![Alt text](./docs/assets/src-folder.png 'Title')
+
+- _assets_ folder contains all images needed to our storybook or for some component to use. Divided on two folders:
+
+  - **_storybook_** - all images/files related with environment of storybook app
+  - **_app_** - all images/files related with components development
+
+- _components_ folder contain main content, divided on:
+  - **_documentation_** contain a story mdx file used on welcome page
+  - **_ui_** contains the root structure for component development and files to export component and their props.
+- **_styles_** contain a file used to global css of storybook. Specific component styling must be placed in its contextual folder. This style folder is used only for general/base purposes.
+
+### **Tailwind.config.js** file
+
+File support all configurations to scss based on Figma and can be written with more or edited.
+
+## Metodology Atomic Design Principles
+
+The component development follows the Atomic Design Principles - <https://xd.adobe.com/ideas/process/ui-design/atomic-design-principles-methodology-101/>.
+
+To reflect this, the **src/ui** folder must respect the following practices:
+
+- Ensure the following folder structure:
+  - Atoms
+  - Molecules
+  - Organisms
+  - Templates
+  - Pages
+- Components:
+  - Component folders name must be written in **kebab-case** (i.e: name-othername).
+  - Component file for source code must be named must be written in **kebab-case** (i.e: name-othername.tsx).
+- Stories:
+
+  - Story files used to write documentation must be named with the same component name with the **.stories.mdx** suffix (i.e: name-othername.stories.mdx).
+  - Story tsx files used to generate code use cases/examples must be named with the same component name with the **.stories.mdx** suffix (i.e: name-othername.stories.tsx).
+  - It is allowed and encouraged to used additional files to improve the readability of the story.
+  - Use the already written stories as a template model for the new stories.
+
+- Scss files names must be written in **kebab-case** (i.e: name-othername.scss).
+- Others folders can be added, like hooks, libs, utils, etc. Not forget to reference them to be exported.
+
+- It must exist a index.ts file to export component and their props.
+- Files must not contain any kind of hardcoded strings, numbers or any type of constant. If needed, it should be discussed with the team.
+
+## Scss pattern
+
+Each component start with a class named "agora-namecomponent". Try used most classes of tailwindcss and only when it's very specific use file scss of component.
+
+There is already a base configuration that it is always evolving accordingly to the figma's spec defined by the UX Team.
+
+## Accessibility
+
+When developing a component or using an external one, accessibility is an important topic to look out for. All components must be tested on W3c, AccessMonitor and Axe. Storybook has plugin installed that gives info of that too.
+
+![Alt text](./docs/assets/accessibility.png 'Title')
+
+## Project best practices
+
+- All code, comments and documentation must be written in english;
+- All code, comments and documentation must have the same structure and look and feel;
+- Commented code blocks are forbidden;
+- No logging (i.e: console.log);
+- No hardcoded values;
+
+## External libraries
+
+The addoption of new external dependencies needs to be discussed and approved by the reviewers and the team.
+Those libraries must respect:
+
+- Respect the accessibility requirements of the project;
+- Server Side Rendering;
+- Performance;
+- Size;
+- Actively maintained;
+
+## SonarQube
+
+This project is connected to SonarQube.
+SonarQube is a tool that do code quality analysis and report them. If SonarQube find some kind of issue, the pipeline fails. All SonarQube issues must be fixed in order to build a new image. Those issues must be fixed by the person (if present) that originated them.
+
+## Git Flow Development -> Merge Request -> Review -> Approve -> Merge
+
+- Create a feature with a suggestive name or if exist the number and name of Jira ticket (i.e: ADSDEV-999-descritive-name)
+- After finishing the development, open a Merge Request(MR) with a sugestive name (Atencion that last comment commit normaly used as name, but not always is suggestive) and a concise description of what was develop and any question/explication of some part of code. Assign this to a Reviewer.
+- All merge requests must be up to date with the target branch. Meaning that a new MR to development branch must be updated with all development branch changes.
+- Any thread openned by the reviewers must only be closed by them. Any people involved in the project can comment a review thread.
+- If all good to go, the reviewers will approve the MR. Only when all reviewers (present at the time of the review) approve the MR, it will be merged to the main development branch.
+
+## Update dev environment of Storybook
+
+Reviewers, as needed or when requested, can deploy new versions of the storybook project. The deployment of new versions to the dev environment requires only a new code commit (via a merge request merged to dev) and a successfull run of the deploy stage of the CI/CD pipeline.
+
+## Prepare code to generate new version Lib
+
+Change package.json version, commit to develop then merge to master. This will trigger a publishing stage that will publish the generated lib in nexus. See gitlab-ci.yml to more info.
+
+## Use Lib
+
+Is required to have user account on AMA Nexus to install this lib. Need to create a .npmrc file with registry and account settings.
+
+```sh
+  > npm install @ama/agora-design-system
+```
+
+This lib should be used on a Next App with this config on next.config.js
+
+```sh
+const withTM = require('next-transpile-modules')(['@ama/agora-design-system', '@babel/preset-react']);
+
+module.exports =
+  withTM({
+    optimizeFonts: false,
+    i18n: {
+      locales: ['pt'],
+      defaultLocale: 'pt'
+    },
+
+    images: {
+      disableStaticImages: true
+    },
+
+    devIndicators: {
+      buildActivity: false
+    },
+
+    output: 'standalone',
+
+    webpack(config) {
+      config.module.rules.push(
+        {
+          test: [/\.ts(x)?$/, /\.js(x)?$/],
+          use: [
+            {
+              loader: 'babel-loader',
+              options: {
+                presets: ['@babel/preset-env', '@babel/preset-react', '@babel/preset-typescript']
+              }
+            }
+          ],
+          exclude: /node_modules/
+        },
+
+        {
+          test: [/\.bmp$/, /\.gif$/, /\.jpe?g$/, /\.png$/],
+          loader: require.resolve('url-loader')
+        },
+        {
+          test: /\.js.map$/,
+          enforce: 'pre',
+          use: ['source-map-loader']
+        },
+        {
+          test: /\.map$/i,
+          use: 'raw-loader'
+        }
+      );
+      return config;
+    }
+  })
+;
+
+```
+
+## Environments
+
+UX-Review - [https://dev-portal-unico.northeurope.cloudapp.azure.com:8180](https://dev-portal-unico.northeurope.cloudapp.azure.com:8180)
+
+Dev - [https://qld-portal-unico.northeurope.cloudapp.azure.com/](https://qld-portal-unico.northeurope.cloudapp.azure.com/)
+
+There are 2 main environments for this storybook design system project. UX-Review and Dev.
+
+### UX-Review
+
+This environment is used by devs and the UI-UX team to perform all the pre-validations required for any branch to be ready to assigned to a merge request.
+
+This environment reflects only the code present in the **ux-review** branch.
+
+**Devs** are responsible for setting up the desired code in the **ux-review** that is going to be reviewed. This environment must reflect the tasks that are ready for review by the UI-UX team.
+
+**Maintainers** are responsible for **deploying** the code when requested. This means that devs prepare the ux-review branch, then request the Maintainers for a deploy. Maintainers announce that the environment is ready for testing.
+
+### Dev
+
+Dev will reflect all code in develop branch.
+
+All merge requests approved will be merged to develop (reviewed, approved, merged), and then the Maintainers will do the deploy for the "dev environment".

package/README.npm.md

@@ -0,0 +1,292 @@
+# Ágora Design System
+
+<b>The main purpose of this Storybook is the development of a design system library with React Js and Next Js , accessible and easy to configure.</b>
+
+## Core technologies
+
+- React - version ^18.0.25 - <https://reactjs.org/>
+- NextJs - version 13.0.4 - <https://nextjs.org/>
+- Storybook - version ^6.5.13 - <https://storybook.js.org/docs/react/get-started/install>
+- Tailwindcss - version ^3.2.4 - <https://tailwindcss.com/docs/installation>
+- Radix-UI - <https://www.radix-ui.com/docs/primitives/overview/introduction>
+- Node - version ^16
+
+## Useful Links
+
+- StoryBook Dev - <https://qld-portal-unico.northeurope.cloudapp.azure.com>
+- StoryBook UX-Review - <https://dev-portal-unico.northeurope.cloudapp.azure.com:8180>
+- Tailwind CSS Cheat Sheet - <https://tailwindcomponents.com/cheatsheet/>
+- Sonnar - <https://ticappsonar.northeurope.cloudapp.azure.com/sonarqube/dashboard?id=portal-unico-storybook-agora>
+- Nexus - <https://ticappsonar.northeurope.cloudapp.azure.com/nexus/#browse/browse:npm-general:%40ama%2Fagora-design-system>
+- Figma (UX Design) - <https://www.figma.com/files/project/60863393/Ágora-Design-System>
+- ZeroHeight - <https://zeroheight.com/1be481dc2/p/2861fa-boas-vindas>
+- AccessMonitor (Acessibilidade AMA) - <https://accessmonitor.acessibilidade.gov.pt/>
+- W3Validator - <https://validator.w3.org/nu/>
+- Axe DevTools - <https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?utm_source=deque.com&utm_medium=referral&utm_campaign=axe_hero>
+
+## Installation and start project
+
+```sh
+> npm install
+> npm run storybook
+
+```
+
+This will generate logs like in the screenshot and locally launch the application
+
+![Alt text](./docs/assets/start-storybook.png 'Title')
+
+## Build project
+
+Generating the project build helps us to understand if everything is ok and ready to a production environment. It is recommended to use this each time a component is terminated.
+
+```sh
+  > npm run build-storybook
+```
+
+## Format all files with Prettier config
+
+To keep code and commits easy to read a custom config was made to format files to everyone on the same way. We can force this format running. The formatter runs on every file and fix them.
+
+```sh
+  > npm run format
+```
+
+## Check Lint and Lint fix
+
+Using this to runs ESLint and find problems with syntax. Some we can fix with lint-fix. Others we have to make some changes.
+
+```sh
+  > npm run lint
+  > npm run lint-fix
+```
+
+<b>NOTE: Both (Build and Lint commands) help to ensure Sonnar scan to run smoothly.</b>
+
+## Project Structure
+
+![Alt text](./docs/assets/main-structure.png 'Title')
+
+All additional files generated by tools and are not required to any part of the project, must be added to the **_.gitignore_** file.
+
+### **Folder _.storybook_**
+
+![Alt text](./docs/assets/storybook-folder.png 'Title')
+
+- _mains.js_ - the main reason to edit this file are to add new addons to storybook, order stories folders and add new static dirs.
+
+- _manager-head.html_ - configure favicon of storybook app
+
+- _manager.js_ - call our custom theme
+
+- _preview.js_ - configure and call theme and other configurations of storybook
+
+- _theme.js_ - custom theme, allow change logos, fonts, url of logos, etc.
+
+### **Folder _dist_**
+
+![Alt text](./docs/assets/dist-folder.png 'Title')
+
+When run the command bellow this will generate the folders above. This folder contains building files to our future lib. We can run this to check structure but this isn't used on development only when we publish.
+
+```sh
+  > npm run build
+
+```
+
+### **Folder _docs_**
+
+Contains assets to support this README file.
+
+### **Folder _infractructure_**
+
+Contain file for Apache configuration.
+
+### **Folder _src_**
+
+![Alt text](./docs/assets/src-folder.png 'Title')
+
+- _assets_ folder contains all images needed to our storybook or for some component to use. Divided on two folders:
+
+  - **_storybook_** - all images/files related with environment of storybook app
+  - **_app_** - all images/files related with components development
+
+- _components_ folder contain main content, divided on:
+  - **_documentation_** contain a story mdx file used on welcome page
+  - **_ui_** contains the root structure for component development and files to export component and their props.
+- **_styles_** contain a file used to global css of storybook. Specific component styling must be placed in its contextual folder. This style folder is used only for general/base purposes.
+
+### **Tailwind.config.js** file
+
+File support all configurations to scss based on Figma and can be written with more or edited.
+
+## Metodology Atomic Design Principles
+
+The component development follows the Atomic Design Principles - <https://xd.adobe.com/ideas/process/ui-design/atomic-design-principles-methodology-101/>.
+
+To reflect this, the **src/ui** folder must respect the following practices:
+
+- Ensure the following folder structure:
+  - Atoms
+  - Molecules
+  - Organisms
+  - Templates
+  - Pages
+- Components:
+  - Component folders name must be written in **kebab-case** (i.e: name-othername).
+  - Component file for source code must be named must be written in **kebab-case** (i.e: name-othername.tsx).
+- Stories:
+
+  - Story files used to write documentation must be named with the same component name with the **.stories.mdx** suffix (i.e: name-othername.stories.mdx).
+  - Story tsx files used to generate code use cases/examples must be named with the same component name with the **.stories.mdx** suffix (i.e: name-othername.stories.tsx).
+  - It is allowed and encouraged to used additional files to improve the readability of the story.
+  - Use the already written stories as a template model for the new stories.
+
+- Scss files names must be written in **kebab-case** (i.e: name-othername.scss).
+- Others folders can be added, like hooks, libs, utils, etc. Not forget to reference them to be exported.
+
+- It must exist a index.ts file to export component and their props.
+- Files must not contain any kind of hardcoded strings, numbers or any type of constant. If needed, it should be discussed with the team.
+
+## Scss pattern
+
+Each component start with a class named "agora-namecomponent". Try used most classes of tailwindcss and only when it's very specific use file scss of component.
+
+There is already a base configuration that it is always evolving accordingly to the figma's spec defined by the UX Team.
+
+## Accessibility
+
+When developing a component or using an external one, accessibility is an important topic to look out for. All components must be tested on W3c, AccessMonitor and Axe. Storybook has plugin installed that gives info of that too.
+
+![Alt text](./docs/assets/accessibility.png 'Title')
+
+## Project best practices
+
+- All code, comments and documentation must be written in english;
+- All code, comments and documentation must have the same structure and look and feel;
+- Commented code blocks are forbidden;
+- No logging (i.e: console.log);
+- No hardcoded values;
+
+## External libraries
+
+The addoption of new external dependencies needs to be discussed and approved by the reviewers and the team.
+Those libraries must respect:
+
+- Respect the accessibility requirements of the project;
+- Server Side Rendering;
+- Performance;
+- Size;
+- Actively maintained;
+
+## SonarQube
+
+This project is connected to SonarQube.
+SonarQube is a tool that do code quality analysis and report them. If SonarQube find some kind of issue, the pipeline fails. All SonarQube issues must be fixed in order to build a new image. Those issues must be fixed by the person (if present) that originated them.
+
+## Git Flow Development -> Merge Request -> Review -> Approve -> Merge
+
+- Create a feature with a suggestive name or if exist the number and name of Jira ticket (i.e: ADSDEV-999-descritive-name)
+- After finishing the development, open a Merge Request(MR) with a sugestive name (Atencion that last comment commit normaly used as name, but not always is suggestive) and a concise description of what was develop and any question/explication of some part of code. Assign this to a Reviewer.
+- All merge requests must be up to date with the target branch. Meaning that a new MR to development branch must be updated with all development branch changes.
+- Any thread openned by the reviewers must only be closed by them. Any people involved in the project can comment a review thread.
+- If all good to go, the reviewers will approve the MR. Only when all reviewers (present at the time of the review) approve the MR, it will be merged to the main development branch.
+
+## Update dev environment of Storybook
+
+Reviewers, as needed or when requested, can deploy new versions of the storybook project. The deployment of new versions to the dev environment requires only a new code commit (via a merge request merged to dev) and a successfull run of the deploy stage of the CI/CD pipeline.
+
+## Prepare code to generate new version Lib
+
+Change package.json version, commit to develop then merge to master. This will trigger a publishing stage that will publish the generated lib in nexus. See gitlab-ci.yml to more info.
+
+## Use Lib
+
+Is required to have user account on AMA Nexus to install this lib. Need to create a .npmrc file with registry and account settings.
+
+```sh
+  > npm install @ama/agora-design-system
+```
+
+This lib should be used on a Next App with this config on next.config.js
+
+```sh
+const withTM = require('next-transpile-modules')(['@ama/agora-design-system', '@babel/preset-react']);
+
+module.exports =
+  withTM({
+    optimizeFonts: false,
+    i18n: {
+      locales: ['pt'],
+      defaultLocale: 'pt'
+    },
+
+    images: {
+      disableStaticImages: true
+    },
+
+    devIndicators: {
+      buildActivity: false
+    },
+
+    output: 'standalone',
+
+    webpack(config) {
+      config.module.rules.push(
+        {
+          test: [/\.ts(x)?$/, /\.js(x)?$/],
+          use: [
+            {
+              loader: 'babel-loader',
+              options: {
+                presets: ['@babel/preset-env', '@babel/preset-react', '@babel/preset-typescript']
+              }
+            }
+          ],
+          exclude: /node_modules/
+        },
+
+        {
+          test: [/\.bmp$/, /\.gif$/, /\.jpe?g$/, /\.png$/],
+          loader: require.resolve('url-loader')
+        },
+        {
+          test: /\.js.map$/,
+          enforce: 'pre',
+          use: ['source-map-loader']
+        },
+        {
+          test: /\.map$/i,
+          use: 'raw-loader'
+        }
+      );
+      return config;
+    }
+  })
+;
+
+```
+
+## Environments
+
+UX-Review - [https://dev-portal-unico.northeurope.cloudapp.azure.com:8180](https://dev-portal-unico.northeurope.cloudapp.azure.com:8180)
+
+Dev - [https://qld-portal-unico.northeurope.cloudapp.azure.com/](https://qld-portal-unico.northeurope.cloudapp.azure.com/)
+
+There are 2 main environments for this storybook design system project. UX-Review and Dev.
+
+### UX-Review
+
+This environment is used by devs and the UI-UX team to perform all the pre-validations required for any branch to be ready to assigned to a merge request.
+
+This environment reflects only the code present in the **ux-review** branch.
+
+**Devs** are responsible for setting up the desired code in the **ux-review** that is going to be reviewed. This environment must reflect the tasks that are ready for review by the UI-UX team.
+
+**Maintainers** are responsible for **deploying** the code when requested. This means that devs prepare the ux-review branch, then request the Maintainers for a deploy. Maintainers announce that the environment is ready for testing.
+
+### Dev
+
+Dev will reflect all code in develop branch.
+
+All merge requests approved will be merged to develop (reviewed, approved, merged), and then the Maintainers will do the deploy for the "dev environment".

package/dist/cjs/components/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ui';
+export * from './utils';

package/dist/cjs/components/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// UI
+__exportStar(require("./ui"), exports);
+// COMMON UTILS
+__exportStar(require("./utils"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,KAAK;AACL,uCAAqB;AAErB,eAAe;AACf,0CAAwB"}