From f080817f75c3d68ef300f840c0ed938b0d99e5d3 Mon Sep 17 00:00:00 2001 From: camperbot Date: Wed, 23 Mar 2022 09:12:55 +0530 Subject: [PATCH] chore(i18n,docs): processed translations (#45502) --- docs/i18n/chinese-traditional/_sidebar.md | 1 + .../how-to-work-on-the-component-library.md | 87 +++++++++++++++++++ docs/i18n/chinese/_sidebar.md | 1 + .../how-to-work-on-the-component-library.md | 87 +++++++++++++++++++ docs/i18n/espanol/_sidebar.md | 1 + .../how-to-work-on-the-component-library.md | 87 +++++++++++++++++++ docs/i18n/german/_sidebar.md | 1 + .../how-to-work-on-the-component-library.md | 87 +++++++++++++++++++ docs/i18n/italian/_sidebar.md | 1 + .../how-to-work-on-the-component-library.md | 87 +++++++++++++++++++ docs/i18n/japanese/_sidebar.md | 1 + .../how-to-work-on-the-component-library.md | 87 +++++++++++++++++++ docs/i18n/portuguese/_sidebar.md | 1 + .../how-to-work-on-the-component-library.md | 87 +++++++++++++++++++ docs/i18n/ukrainian/_sidebar.md | 1 + .../how-to-work-on-the-component-library.md | 87 +++++++++++++++++++ 16 files changed, 704 insertions(+) create mode 100644 docs/i18n/chinese-traditional/how-to-work-on-the-component-library.md create mode 100644 docs/i18n/chinese/how-to-work-on-the-component-library.md create mode 100644 docs/i18n/espanol/how-to-work-on-the-component-library.md create mode 100644 docs/i18n/german/how-to-work-on-the-component-library.md create mode 100644 docs/i18n/italian/how-to-work-on-the-component-library.md create mode 100644 docs/i18n/japanese/how-to-work-on-the-component-library.md create mode 100644 docs/i18n/portuguese/how-to-work-on-the-component-library.md create mode 100644 docs/i18n/ukrainian/how-to-work-on-the-component-library.md diff --git a/docs/i18n/chinese-traditional/_sidebar.md b/docs/i18n/chinese-traditional/_sidebar.md index bd114017b7..e8e13b1bd7 100644 --- a/docs/i18n/chinese-traditional/_sidebar.md +++ b/docs/i18n/chinese-traditional/_sidebar.md @@ -16,6 +16,7 @@ - [Work on Cypress tests](how-to-add-cypress-tests.md) - [Work on video challenges](how-to-help-with-video-challenges.md) - [Work on the docs theme](how-to-work-on-the-docs-theme.md) + - [Work on the component library](how-to-work-on-the-component-library.md) - **Additional Guides** - [Test translations locally](how-to-test-translations-locally.md) - [Understand the curriculum file structure](curriculum-file-structure.md) diff --git a/docs/i18n/chinese-traditional/how-to-work-on-the-component-library.md b/docs/i18n/chinese-traditional/how-to-work-on-the-component-library.md new file mode 100644 index 0000000000..46bf508247 --- /dev/null +++ b/docs/i18n/chinese-traditional/how-to-work-on-the-component-library.md @@ -0,0 +1,87 @@ +Welcome to freeCodeCamp's `ui-components` library. The components are built mostly from scratch with basic HTML elements and [Tailwind CSS](https://tailwindcss.com/). + +# How to Work on the Component Library + +> [!NOTE] +> +> freeCodeCamp has been using Bootstrap components in the UI. However, we are moving away from it and building our own component library, which helps standardize our UX/UI patterns and improve accessibility. The project is tracked in [this GitHub issue](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668). + +The following steps are recommended when working on a new component: + +- Research and planning +- Implement the component +- Display the use cases on Storybook +- Write unit tests + +## Researching and planning + +Before building a component, you need to research and document on how the existing version behaves and looks, to ensure that the new one has matching styles and supports all the current usages. In order to meet the web accesibility requirements, you should also pay attention to the accessibility aspect of the components, see which HTML elements and ARIA attributes are used under the hood. + +Once you have gathered enough information about the component, you can start thinking about the props interface. Ideally, the interface should be as similar to the current version as possible, to ease the adoption later on. Since we are using Bootstrap components, the simplest approach is to mimic [their implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src). + +We prefer smaller pull requests rather than a large one, because they speed up the review time and reduce cognitive overload for the reviewers. For that reason, you should think about how you would break down the implementation and come up with a delivery plan. + +We recommend opening a separate GitHub issue for each component and include all the notes in the issue description. It can be used as a place to host all of your working notes, as well as a way to communicate the approach with the reviewers. We will use the issue thread for further discussion if needed. [The issue for Button component](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) can be used as a reference. + +## Implementing the component + +A new component can be created using the following command from the root directory: + +```bash +cd tools/ui-components + +npm run gen-component MyComponent +``` + +The command will generate a new folder inside the `ui-components` directory, with the following files: + +| File name | Purpose | +| -------------------------- | ------------------------------------------------------ | +| `index.ts` | It is used for exporting the component and its types. | +| `my-component.stories.tsx` | It is used for demoing the component on Storybook. | +| `my-component.test.tsx` | It is a test file. | +| `my-component.tsx` | It is where we implement the component. | +| `types.ts` | Is is where we locate component's interface and types. | + +Each component is different, but in general the components should: + +- Support forwarding ref +- Be styled for both light and dark themes +- Be styled internally based on their props (the consumers should not need to restyle the components with the `className` prop) +- Utilize the built-in styling system from Tailwind instead of having custom styles + +### Useful links + +- [Tailwind CSS Configuration](https://tailwindcss.com/docs/configuration) +- [React Bootstrap v0.33 Docs](https://react-bootstrap-v3.netlify.app) +- [Bootstrap 3.3.7 stylesheet](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css) +- [React Bootstrap current implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src) +- [React Bootstrap current tests](https://github.com/react-bootstrap/react-bootstrap/tree/master/test) + +## Displaying the use cases on Storybook + +Use cases of the component should be added to the Storybook file (`.stories.tsx`). + +To start Storybook, run the following command from the root directory: + +```bash +npm run storybook +``` + +The Storybook page is available on [http://localhost:6006](http://localhost:6006). + +## Writing unit tests + +We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to write unit tests. The tests should assert that the components behave as expected and are accessible. + +To run tests against the component library, run the following command from the root directory: + +```bash +npm run test-ui-components +``` + +### Useful links + +- [Testing for Accessibility](https://testing-library.com/docs/dom-testing-library/api-accessibility) +- [Order of priority of React Testing Library's queries](https://testing-library.com/docs/queries/about/#priority) +- [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library) diff --git a/docs/i18n/chinese/_sidebar.md b/docs/i18n/chinese/_sidebar.md index 3cfd2aed73..d6b0a1386f 100644 --- a/docs/i18n/chinese/_sidebar.md +++ b/docs/i18n/chinese/_sidebar.md @@ -16,6 +16,7 @@ - [Work on Cypress tests](how-to-add-cypress-tests.md) - [Work on video challenges](how-to-help-with-video-challenges.md) - [Work on the docs theme](how-to-work-on-the-docs-theme.md) + - [Work on the component library](how-to-work-on-the-component-library.md) - **Additional Guides** - [Test translations locally](how-to-test-translations-locally.md) - [Understand the curriculum file structure](curriculum-file-structure.md) diff --git a/docs/i18n/chinese/how-to-work-on-the-component-library.md b/docs/i18n/chinese/how-to-work-on-the-component-library.md new file mode 100644 index 0000000000..46bf508247 --- /dev/null +++ b/docs/i18n/chinese/how-to-work-on-the-component-library.md @@ -0,0 +1,87 @@ +Welcome to freeCodeCamp's `ui-components` library. The components are built mostly from scratch with basic HTML elements and [Tailwind CSS](https://tailwindcss.com/). + +# How to Work on the Component Library + +> [!NOTE] +> +> freeCodeCamp has been using Bootstrap components in the UI. However, we are moving away from it and building our own component library, which helps standardize our UX/UI patterns and improve accessibility. The project is tracked in [this GitHub issue](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668). + +The following steps are recommended when working on a new component: + +- Research and planning +- Implement the component +- Display the use cases on Storybook +- Write unit tests + +## Researching and planning + +Before building a component, you need to research and document on how the existing version behaves and looks, to ensure that the new one has matching styles and supports all the current usages. In order to meet the web accesibility requirements, you should also pay attention to the accessibility aspect of the components, see which HTML elements and ARIA attributes are used under the hood. + +Once you have gathered enough information about the component, you can start thinking about the props interface. Ideally, the interface should be as similar to the current version as possible, to ease the adoption later on. Since we are using Bootstrap components, the simplest approach is to mimic [their implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src). + +We prefer smaller pull requests rather than a large one, because they speed up the review time and reduce cognitive overload for the reviewers. For that reason, you should think about how you would break down the implementation and come up with a delivery plan. + +We recommend opening a separate GitHub issue for each component and include all the notes in the issue description. It can be used as a place to host all of your working notes, as well as a way to communicate the approach with the reviewers. We will use the issue thread for further discussion if needed. [The issue for Button component](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) can be used as a reference. + +## Implementing the component + +A new component can be created using the following command from the root directory: + +```bash +cd tools/ui-components + +npm run gen-component MyComponent +``` + +The command will generate a new folder inside the `ui-components` directory, with the following files: + +| File name | Purpose | +| -------------------------- | ------------------------------------------------------ | +| `index.ts` | It is used for exporting the component and its types. | +| `my-component.stories.tsx` | It is used for demoing the component on Storybook. | +| `my-component.test.tsx` | It is a test file. | +| `my-component.tsx` | It is where we implement the component. | +| `types.ts` | Is is where we locate component's interface and types. | + +Each component is different, but in general the components should: + +- Support forwarding ref +- Be styled for both light and dark themes +- Be styled internally based on their props (the consumers should not need to restyle the components with the `className` prop) +- Utilize the built-in styling system from Tailwind instead of having custom styles + +### Useful links + +- [Tailwind CSS Configuration](https://tailwindcss.com/docs/configuration) +- [React Bootstrap v0.33 Docs](https://react-bootstrap-v3.netlify.app) +- [Bootstrap 3.3.7 stylesheet](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css) +- [React Bootstrap current implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src) +- [React Bootstrap current tests](https://github.com/react-bootstrap/react-bootstrap/tree/master/test) + +## Displaying the use cases on Storybook + +Use cases of the component should be added to the Storybook file (`.stories.tsx`). + +To start Storybook, run the following command from the root directory: + +```bash +npm run storybook +``` + +The Storybook page is available on [http://localhost:6006](http://localhost:6006). + +## Writing unit tests + +We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to write unit tests. The tests should assert that the components behave as expected and are accessible. + +To run tests against the component library, run the following command from the root directory: + +```bash +npm run test-ui-components +``` + +### Useful links + +- [Testing for Accessibility](https://testing-library.com/docs/dom-testing-library/api-accessibility) +- [Order of priority of React Testing Library's queries](https://testing-library.com/docs/queries/about/#priority) +- [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library) diff --git a/docs/i18n/espanol/_sidebar.md b/docs/i18n/espanol/_sidebar.md index 70f83efcdf..4f91c8f9ce 100644 --- a/docs/i18n/espanol/_sidebar.md +++ b/docs/i18n/espanol/_sidebar.md @@ -16,6 +16,7 @@ - [Trabaja con los test Cypress](how-to-add-cypress-tests.md) - [Colabora con los desafíos en vídeo](how-to-help-with-video-challenges.md) - [Trabajar en el tema docs](how-to-work-on-the-docs-theme.md) + - [Work on the component library](how-to-work-on-the-component-library.md) - **Guías adicionales** - [Previsualiza las traducciones localmente](how-to-test-translations-locally.md) - [Entiende la estructura de archivo del currículo](curriculum-file-structure.md) diff --git a/docs/i18n/espanol/how-to-work-on-the-component-library.md b/docs/i18n/espanol/how-to-work-on-the-component-library.md new file mode 100644 index 0000000000..46bf508247 --- /dev/null +++ b/docs/i18n/espanol/how-to-work-on-the-component-library.md @@ -0,0 +1,87 @@ +Welcome to freeCodeCamp's `ui-components` library. The components are built mostly from scratch with basic HTML elements and [Tailwind CSS](https://tailwindcss.com/). + +# How to Work on the Component Library + +> [!NOTE] +> +> freeCodeCamp has been using Bootstrap components in the UI. However, we are moving away from it and building our own component library, which helps standardize our UX/UI patterns and improve accessibility. The project is tracked in [this GitHub issue](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668). + +The following steps are recommended when working on a new component: + +- Research and planning +- Implement the component +- Display the use cases on Storybook +- Write unit tests + +## Researching and planning + +Before building a component, you need to research and document on how the existing version behaves and looks, to ensure that the new one has matching styles and supports all the current usages. In order to meet the web accesibility requirements, you should also pay attention to the accessibility aspect of the components, see which HTML elements and ARIA attributes are used under the hood. + +Once you have gathered enough information about the component, you can start thinking about the props interface. Ideally, the interface should be as similar to the current version as possible, to ease the adoption later on. Since we are using Bootstrap components, the simplest approach is to mimic [their implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src). + +We prefer smaller pull requests rather than a large one, because they speed up the review time and reduce cognitive overload for the reviewers. For that reason, you should think about how you would break down the implementation and come up with a delivery plan. + +We recommend opening a separate GitHub issue for each component and include all the notes in the issue description. It can be used as a place to host all of your working notes, as well as a way to communicate the approach with the reviewers. We will use the issue thread for further discussion if needed. [The issue for Button component](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) can be used as a reference. + +## Implementing the component + +A new component can be created using the following command from the root directory: + +```bash +cd tools/ui-components + +npm run gen-component MyComponent +``` + +The command will generate a new folder inside the `ui-components` directory, with the following files: + +| File name | Purpose | +| -------------------------- | ------------------------------------------------------ | +| `index.ts` | It is used for exporting the component and its types. | +| `my-component.stories.tsx` | It is used for demoing the component on Storybook. | +| `my-component.test.tsx` | It is a test file. | +| `my-component.tsx` | It is where we implement the component. | +| `types.ts` | Is is where we locate component's interface and types. | + +Each component is different, but in general the components should: + +- Support forwarding ref +- Be styled for both light and dark themes +- Be styled internally based on their props (the consumers should not need to restyle the components with the `className` prop) +- Utilize the built-in styling system from Tailwind instead of having custom styles + +### Useful links + +- [Tailwind CSS Configuration](https://tailwindcss.com/docs/configuration) +- [React Bootstrap v0.33 Docs](https://react-bootstrap-v3.netlify.app) +- [Bootstrap 3.3.7 stylesheet](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css) +- [React Bootstrap current implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src) +- [React Bootstrap current tests](https://github.com/react-bootstrap/react-bootstrap/tree/master/test) + +## Displaying the use cases on Storybook + +Use cases of the component should be added to the Storybook file (`.stories.tsx`). + +To start Storybook, run the following command from the root directory: + +```bash +npm run storybook +``` + +The Storybook page is available on [http://localhost:6006](http://localhost:6006). + +## Writing unit tests + +We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to write unit tests. The tests should assert that the components behave as expected and are accessible. + +To run tests against the component library, run the following command from the root directory: + +```bash +npm run test-ui-components +``` + +### Useful links + +- [Testing for Accessibility](https://testing-library.com/docs/dom-testing-library/api-accessibility) +- [Order of priority of React Testing Library's queries](https://testing-library.com/docs/queries/about/#priority) +- [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library) diff --git a/docs/i18n/german/_sidebar.md b/docs/i18n/german/_sidebar.md index 6c6523ce9a..fc344beefb 100644 --- a/docs/i18n/german/_sidebar.md +++ b/docs/i18n/german/_sidebar.md @@ -16,6 +16,7 @@ - [Arbeite an den Cypress Tests](how-to-add-cypress-tests.md) - [Arbeite an den Videoaufgaben](how-to-help-with-video-challenges.md) - [Work on the docs theme](how-to-work-on-the-docs-theme.md) + - [Work on the component library](how-to-work-on-the-component-library.md) - **Zusätzliche Leitfäden** - [Übersetzungen lokal testen](how-to-test-translations-locally.md) - [Verstehe die Dateistruktur des Studienplans](curriculum-file-structure.md) diff --git a/docs/i18n/german/how-to-work-on-the-component-library.md b/docs/i18n/german/how-to-work-on-the-component-library.md new file mode 100644 index 0000000000..46bf508247 --- /dev/null +++ b/docs/i18n/german/how-to-work-on-the-component-library.md @@ -0,0 +1,87 @@ +Welcome to freeCodeCamp's `ui-components` library. The components are built mostly from scratch with basic HTML elements and [Tailwind CSS](https://tailwindcss.com/). + +# How to Work on the Component Library + +> [!NOTE] +> +> freeCodeCamp has been using Bootstrap components in the UI. However, we are moving away from it and building our own component library, which helps standardize our UX/UI patterns and improve accessibility. The project is tracked in [this GitHub issue](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668). + +The following steps are recommended when working on a new component: + +- Research and planning +- Implement the component +- Display the use cases on Storybook +- Write unit tests + +## Researching and planning + +Before building a component, you need to research and document on how the existing version behaves and looks, to ensure that the new one has matching styles and supports all the current usages. In order to meet the web accesibility requirements, you should also pay attention to the accessibility aspect of the components, see which HTML elements and ARIA attributes are used under the hood. + +Once you have gathered enough information about the component, you can start thinking about the props interface. Ideally, the interface should be as similar to the current version as possible, to ease the adoption later on. Since we are using Bootstrap components, the simplest approach is to mimic [their implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src). + +We prefer smaller pull requests rather than a large one, because they speed up the review time and reduce cognitive overload for the reviewers. For that reason, you should think about how you would break down the implementation and come up with a delivery plan. + +We recommend opening a separate GitHub issue for each component and include all the notes in the issue description. It can be used as a place to host all of your working notes, as well as a way to communicate the approach with the reviewers. We will use the issue thread for further discussion if needed. [The issue for Button component](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) can be used as a reference. + +## Implementing the component + +A new component can be created using the following command from the root directory: + +```bash +cd tools/ui-components + +npm run gen-component MyComponent +``` + +The command will generate a new folder inside the `ui-components` directory, with the following files: + +| File name | Purpose | +| -------------------------- | ------------------------------------------------------ | +| `index.ts` | It is used for exporting the component and its types. | +| `my-component.stories.tsx` | It is used for demoing the component on Storybook. | +| `my-component.test.tsx` | It is a test file. | +| `my-component.tsx` | It is where we implement the component. | +| `types.ts` | Is is where we locate component's interface and types. | + +Each component is different, but in general the components should: + +- Support forwarding ref +- Be styled for both light and dark themes +- Be styled internally based on their props (the consumers should not need to restyle the components with the `className` prop) +- Utilize the built-in styling system from Tailwind instead of having custom styles + +### Useful links + +- [Tailwind CSS Configuration](https://tailwindcss.com/docs/configuration) +- [React Bootstrap v0.33 Docs](https://react-bootstrap-v3.netlify.app) +- [Bootstrap 3.3.7 stylesheet](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css) +- [React Bootstrap current implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src) +- [React Bootstrap current tests](https://github.com/react-bootstrap/react-bootstrap/tree/master/test) + +## Displaying the use cases on Storybook + +Use cases of the component should be added to the Storybook file (`.stories.tsx`). + +To start Storybook, run the following command from the root directory: + +```bash +npm run storybook +``` + +The Storybook page is available on [http://localhost:6006](http://localhost:6006). + +## Writing unit tests + +We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to write unit tests. The tests should assert that the components behave as expected and are accessible. + +To run tests against the component library, run the following command from the root directory: + +```bash +npm run test-ui-components +``` + +### Useful links + +- [Testing for Accessibility](https://testing-library.com/docs/dom-testing-library/api-accessibility) +- [Order of priority of React Testing Library's queries](https://testing-library.com/docs/queries/about/#priority) +- [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library) diff --git a/docs/i18n/italian/_sidebar.md b/docs/i18n/italian/_sidebar.md index 1a473ce48d..ebda4f7e4d 100644 --- a/docs/i18n/italian/_sidebar.md +++ b/docs/i18n/italian/_sidebar.md @@ -16,6 +16,7 @@ - [Lavora sui test Cypress ](how-to-add-cypress-tests.md) - [Lavorare sulle sfide video](how-to-help-with-video-challenges.md) - [Lavorare sul tema della documentazione](how-to-work-on-the-docs-theme.md) + - [Work on the component library](how-to-work-on-the-component-library.md) - **Guide aggiuntive** - [Testare traduzioni in locale](how-to-test-translations-locally.md) - [Capire la struttura dei file del curriculum](curriculum-file-structure.md) diff --git a/docs/i18n/italian/how-to-work-on-the-component-library.md b/docs/i18n/italian/how-to-work-on-the-component-library.md new file mode 100644 index 0000000000..46bf508247 --- /dev/null +++ b/docs/i18n/italian/how-to-work-on-the-component-library.md @@ -0,0 +1,87 @@ +Welcome to freeCodeCamp's `ui-components` library. The components are built mostly from scratch with basic HTML elements and [Tailwind CSS](https://tailwindcss.com/). + +# How to Work on the Component Library + +> [!NOTE] +> +> freeCodeCamp has been using Bootstrap components in the UI. However, we are moving away from it and building our own component library, which helps standardize our UX/UI patterns and improve accessibility. The project is tracked in [this GitHub issue](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668). + +The following steps are recommended when working on a new component: + +- Research and planning +- Implement the component +- Display the use cases on Storybook +- Write unit tests + +## Researching and planning + +Before building a component, you need to research and document on how the existing version behaves and looks, to ensure that the new one has matching styles and supports all the current usages. In order to meet the web accesibility requirements, you should also pay attention to the accessibility aspect of the components, see which HTML elements and ARIA attributes are used under the hood. + +Once you have gathered enough information about the component, you can start thinking about the props interface. Ideally, the interface should be as similar to the current version as possible, to ease the adoption later on. Since we are using Bootstrap components, the simplest approach is to mimic [their implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src). + +We prefer smaller pull requests rather than a large one, because they speed up the review time and reduce cognitive overload for the reviewers. For that reason, you should think about how you would break down the implementation and come up with a delivery plan. + +We recommend opening a separate GitHub issue for each component and include all the notes in the issue description. It can be used as a place to host all of your working notes, as well as a way to communicate the approach with the reviewers. We will use the issue thread for further discussion if needed. [The issue for Button component](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) can be used as a reference. + +## Implementing the component + +A new component can be created using the following command from the root directory: + +```bash +cd tools/ui-components + +npm run gen-component MyComponent +``` + +The command will generate a new folder inside the `ui-components` directory, with the following files: + +| File name | Purpose | +| -------------------------- | ------------------------------------------------------ | +| `index.ts` | It is used for exporting the component and its types. | +| `my-component.stories.tsx` | It is used for demoing the component on Storybook. | +| `my-component.test.tsx` | It is a test file. | +| `my-component.tsx` | It is where we implement the component. | +| `types.ts` | Is is where we locate component's interface and types. | + +Each component is different, but in general the components should: + +- Support forwarding ref +- Be styled for both light and dark themes +- Be styled internally based on their props (the consumers should not need to restyle the components with the `className` prop) +- Utilize the built-in styling system from Tailwind instead of having custom styles + +### Useful links + +- [Tailwind CSS Configuration](https://tailwindcss.com/docs/configuration) +- [React Bootstrap v0.33 Docs](https://react-bootstrap-v3.netlify.app) +- [Bootstrap 3.3.7 stylesheet](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css) +- [React Bootstrap current implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src) +- [React Bootstrap current tests](https://github.com/react-bootstrap/react-bootstrap/tree/master/test) + +## Displaying the use cases on Storybook + +Use cases of the component should be added to the Storybook file (`.stories.tsx`). + +To start Storybook, run the following command from the root directory: + +```bash +npm run storybook +``` + +The Storybook page is available on [http://localhost:6006](http://localhost:6006). + +## Writing unit tests + +We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to write unit tests. The tests should assert that the components behave as expected and are accessible. + +To run tests against the component library, run the following command from the root directory: + +```bash +npm run test-ui-components +``` + +### Useful links + +- [Testing for Accessibility](https://testing-library.com/docs/dom-testing-library/api-accessibility) +- [Order of priority of React Testing Library's queries](https://testing-library.com/docs/queries/about/#priority) +- [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library) diff --git a/docs/i18n/japanese/_sidebar.md b/docs/i18n/japanese/_sidebar.md index 0145da6ec9..afcc0d6b8a 100644 --- a/docs/i18n/japanese/_sidebar.md +++ b/docs/i18n/japanese/_sidebar.md @@ -16,6 +16,7 @@ - [Cypress テストに貢献する](how-to-add-cypress-tests.md) - [ビデオチャレンジに貢献する](how-to-help-with-video-challenges.md) - [Work on the docs theme](how-to-work-on-the-docs-theme.md) + - [Work on the component library](how-to-work-on-the-component-library.md) - **その他のガイド** - [翻訳をローカルでテストする](how-to-test-translations-locally.md) - [カリキュラムのファイル構造を理解する](curriculum-file-structure.md) diff --git a/docs/i18n/japanese/how-to-work-on-the-component-library.md b/docs/i18n/japanese/how-to-work-on-the-component-library.md new file mode 100644 index 0000000000..46bf508247 --- /dev/null +++ b/docs/i18n/japanese/how-to-work-on-the-component-library.md @@ -0,0 +1,87 @@ +Welcome to freeCodeCamp's `ui-components` library. The components are built mostly from scratch with basic HTML elements and [Tailwind CSS](https://tailwindcss.com/). + +# How to Work on the Component Library + +> [!NOTE] +> +> freeCodeCamp has been using Bootstrap components in the UI. However, we are moving away from it and building our own component library, which helps standardize our UX/UI patterns and improve accessibility. The project is tracked in [this GitHub issue](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668). + +The following steps are recommended when working on a new component: + +- Research and planning +- Implement the component +- Display the use cases on Storybook +- Write unit tests + +## Researching and planning + +Before building a component, you need to research and document on how the existing version behaves and looks, to ensure that the new one has matching styles and supports all the current usages. In order to meet the web accesibility requirements, you should also pay attention to the accessibility aspect of the components, see which HTML elements and ARIA attributes are used under the hood. + +Once you have gathered enough information about the component, you can start thinking about the props interface. Ideally, the interface should be as similar to the current version as possible, to ease the adoption later on. Since we are using Bootstrap components, the simplest approach is to mimic [their implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src). + +We prefer smaller pull requests rather than a large one, because they speed up the review time and reduce cognitive overload for the reviewers. For that reason, you should think about how you would break down the implementation and come up with a delivery plan. + +We recommend opening a separate GitHub issue for each component and include all the notes in the issue description. It can be used as a place to host all of your working notes, as well as a way to communicate the approach with the reviewers. We will use the issue thread for further discussion if needed. [The issue for Button component](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) can be used as a reference. + +## Implementing the component + +A new component can be created using the following command from the root directory: + +```bash +cd tools/ui-components + +npm run gen-component MyComponent +``` + +The command will generate a new folder inside the `ui-components` directory, with the following files: + +| File name | Purpose | +| -------------------------- | ------------------------------------------------------ | +| `index.ts` | It is used for exporting the component and its types. | +| `my-component.stories.tsx` | It is used for demoing the component on Storybook. | +| `my-component.test.tsx` | It is a test file. | +| `my-component.tsx` | It is where we implement the component. | +| `types.ts` | Is is where we locate component's interface and types. | + +Each component is different, but in general the components should: + +- Support forwarding ref +- Be styled for both light and dark themes +- Be styled internally based on their props (the consumers should not need to restyle the components with the `className` prop) +- Utilize the built-in styling system from Tailwind instead of having custom styles + +### Useful links + +- [Tailwind CSS Configuration](https://tailwindcss.com/docs/configuration) +- [React Bootstrap v0.33 Docs](https://react-bootstrap-v3.netlify.app) +- [Bootstrap 3.3.7 stylesheet](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css) +- [React Bootstrap current implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src) +- [React Bootstrap current tests](https://github.com/react-bootstrap/react-bootstrap/tree/master/test) + +## Displaying the use cases on Storybook + +Use cases of the component should be added to the Storybook file (`.stories.tsx`). + +To start Storybook, run the following command from the root directory: + +```bash +npm run storybook +``` + +The Storybook page is available on [http://localhost:6006](http://localhost:6006). + +## Writing unit tests + +We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to write unit tests. The tests should assert that the components behave as expected and are accessible. + +To run tests against the component library, run the following command from the root directory: + +```bash +npm run test-ui-components +``` + +### Useful links + +- [Testing for Accessibility](https://testing-library.com/docs/dom-testing-library/api-accessibility) +- [Order of priority of React Testing Library's queries](https://testing-library.com/docs/queries/about/#priority) +- [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library) diff --git a/docs/i18n/portuguese/_sidebar.md b/docs/i18n/portuguese/_sidebar.md index e566a238c7..3b310f53c8 100644 --- a/docs/i18n/portuguese/_sidebar.md +++ b/docs/i18n/portuguese/_sidebar.md @@ -16,6 +16,7 @@ - [Trabalhar em testes do Cypress](how-to-add-cypress-tests.md) - [Trabalhar nos desafios em vídeo](how-to-help-with-video-challenges.md) - [Trabalhe no tema de documentação](how-to-work-on-the-docs-theme.md) + - [Work on the component library](how-to-work-on-the-component-library.md) - **Guias adicionais** - [Testar traduções localmente](how-to-test-translations-locally.md) - [Compreender a estrutura do arquivo do currículo](curriculum-file-structure.md) diff --git a/docs/i18n/portuguese/how-to-work-on-the-component-library.md b/docs/i18n/portuguese/how-to-work-on-the-component-library.md new file mode 100644 index 0000000000..46bf508247 --- /dev/null +++ b/docs/i18n/portuguese/how-to-work-on-the-component-library.md @@ -0,0 +1,87 @@ +Welcome to freeCodeCamp's `ui-components` library. The components are built mostly from scratch with basic HTML elements and [Tailwind CSS](https://tailwindcss.com/). + +# How to Work on the Component Library + +> [!NOTE] +> +> freeCodeCamp has been using Bootstrap components in the UI. However, we are moving away from it and building our own component library, which helps standardize our UX/UI patterns and improve accessibility. The project is tracked in [this GitHub issue](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668). + +The following steps are recommended when working on a new component: + +- Research and planning +- Implement the component +- Display the use cases on Storybook +- Write unit tests + +## Researching and planning + +Before building a component, you need to research and document on how the existing version behaves and looks, to ensure that the new one has matching styles and supports all the current usages. In order to meet the web accesibility requirements, you should also pay attention to the accessibility aspect of the components, see which HTML elements and ARIA attributes are used under the hood. + +Once you have gathered enough information about the component, you can start thinking about the props interface. Ideally, the interface should be as similar to the current version as possible, to ease the adoption later on. Since we are using Bootstrap components, the simplest approach is to mimic [their implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src). + +We prefer smaller pull requests rather than a large one, because they speed up the review time and reduce cognitive overload for the reviewers. For that reason, you should think about how you would break down the implementation and come up with a delivery plan. + +We recommend opening a separate GitHub issue for each component and include all the notes in the issue description. It can be used as a place to host all of your working notes, as well as a way to communicate the approach with the reviewers. We will use the issue thread for further discussion if needed. [The issue for Button component](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) can be used as a reference. + +## Implementing the component + +A new component can be created using the following command from the root directory: + +```bash +cd tools/ui-components + +npm run gen-component MyComponent +``` + +The command will generate a new folder inside the `ui-components` directory, with the following files: + +| File name | Purpose | +| -------------------------- | ------------------------------------------------------ | +| `index.ts` | It is used for exporting the component and its types. | +| `my-component.stories.tsx` | It is used for demoing the component on Storybook. | +| `my-component.test.tsx` | It is a test file. | +| `my-component.tsx` | It is where we implement the component. | +| `types.ts` | Is is where we locate component's interface and types. | + +Each component is different, but in general the components should: + +- Support forwarding ref +- Be styled for both light and dark themes +- Be styled internally based on their props (the consumers should not need to restyle the components with the `className` prop) +- Utilize the built-in styling system from Tailwind instead of having custom styles + +### Useful links + +- [Tailwind CSS Configuration](https://tailwindcss.com/docs/configuration) +- [React Bootstrap v0.33 Docs](https://react-bootstrap-v3.netlify.app) +- [Bootstrap 3.3.7 stylesheet](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css) +- [React Bootstrap current implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src) +- [React Bootstrap current tests](https://github.com/react-bootstrap/react-bootstrap/tree/master/test) + +## Displaying the use cases on Storybook + +Use cases of the component should be added to the Storybook file (`.stories.tsx`). + +To start Storybook, run the following command from the root directory: + +```bash +npm run storybook +``` + +The Storybook page is available on [http://localhost:6006](http://localhost:6006). + +## Writing unit tests + +We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to write unit tests. The tests should assert that the components behave as expected and are accessible. + +To run tests against the component library, run the following command from the root directory: + +```bash +npm run test-ui-components +``` + +### Useful links + +- [Testing for Accessibility](https://testing-library.com/docs/dom-testing-library/api-accessibility) +- [Order of priority of React Testing Library's queries](https://testing-library.com/docs/queries/about/#priority) +- [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library) diff --git a/docs/i18n/ukrainian/_sidebar.md b/docs/i18n/ukrainian/_sidebar.md index daec2fea40..9aff6d7ce5 100644 --- a/docs/i18n/ukrainian/_sidebar.md +++ b/docs/i18n/ukrainian/_sidebar.md @@ -16,6 +16,7 @@ - [Робота з Cypress тестами](how-to-add-cypress-tests.md) - [Робота над завданнями з відео](how-to-help-with-video-challenges.md) - [Work on the docs theme](how-to-work-on-the-docs-theme.md) + - [Work on the component library](how-to-work-on-the-component-library.md) - **Додаткові інструкції** - [Тестуйте переклади локально](how-to-test-translations-locally.md) - [Ознайомлення зі структурою файлів навчальної програми](curriculum-file-structure.md) diff --git a/docs/i18n/ukrainian/how-to-work-on-the-component-library.md b/docs/i18n/ukrainian/how-to-work-on-the-component-library.md new file mode 100644 index 0000000000..46bf508247 --- /dev/null +++ b/docs/i18n/ukrainian/how-to-work-on-the-component-library.md @@ -0,0 +1,87 @@ +Welcome to freeCodeCamp's `ui-components` library. The components are built mostly from scratch with basic HTML elements and [Tailwind CSS](https://tailwindcss.com/). + +# How to Work on the Component Library + +> [!NOTE] +> +> freeCodeCamp has been using Bootstrap components in the UI. However, we are moving away from it and building our own component library, which helps standardize our UX/UI patterns and improve accessibility. The project is tracked in [this GitHub issue](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668). + +The following steps are recommended when working on a new component: + +- Research and planning +- Implement the component +- Display the use cases on Storybook +- Write unit tests + +## Researching and planning + +Before building a component, you need to research and document on how the existing version behaves and looks, to ensure that the new one has matching styles and supports all the current usages. In order to meet the web accesibility requirements, you should also pay attention to the accessibility aspect of the components, see which HTML elements and ARIA attributes are used under the hood. + +Once you have gathered enough information about the component, you can start thinking about the props interface. Ideally, the interface should be as similar to the current version as possible, to ease the adoption later on. Since we are using Bootstrap components, the simplest approach is to mimic [their implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src). + +We prefer smaller pull requests rather than a large one, because they speed up the review time and reduce cognitive overload for the reviewers. For that reason, you should think about how you would break down the implementation and come up with a delivery plan. + +We recommend opening a separate GitHub issue for each component and include all the notes in the issue description. It can be used as a place to host all of your working notes, as well as a way to communicate the approach with the reviewers. We will use the issue thread for further discussion if needed. [The issue for Button component](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) can be used as a reference. + +## Implementing the component + +A new component can be created using the following command from the root directory: + +```bash +cd tools/ui-components + +npm run gen-component MyComponent +``` + +The command will generate a new folder inside the `ui-components` directory, with the following files: + +| File name | Purpose | +| -------------------------- | ------------------------------------------------------ | +| `index.ts` | It is used for exporting the component and its types. | +| `my-component.stories.tsx` | It is used for demoing the component on Storybook. | +| `my-component.test.tsx` | It is a test file. | +| `my-component.tsx` | It is where we implement the component. | +| `types.ts` | Is is where we locate component's interface and types. | + +Each component is different, but in general the components should: + +- Support forwarding ref +- Be styled for both light and dark themes +- Be styled internally based on their props (the consumers should not need to restyle the components with the `className` prop) +- Utilize the built-in styling system from Tailwind instead of having custom styles + +### Useful links + +- [Tailwind CSS Configuration](https://tailwindcss.com/docs/configuration) +- [React Bootstrap v0.33 Docs](https://react-bootstrap-v3.netlify.app) +- [Bootstrap 3.3.7 stylesheet](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css) +- [React Bootstrap current implementation](https://github.com/react-bootstrap/react-bootstrap/tree/master/src) +- [React Bootstrap current tests](https://github.com/react-bootstrap/react-bootstrap/tree/master/test) + +## Displaying the use cases on Storybook + +Use cases of the component should be added to the Storybook file (`.stories.tsx`). + +To start Storybook, run the following command from the root directory: + +```bash +npm run storybook +``` + +The Storybook page is available on [http://localhost:6006](http://localhost:6006). + +## Writing unit tests + +We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) to write unit tests. The tests should assert that the components behave as expected and are accessible. + +To run tests against the component library, run the following command from the root directory: + +```bash +npm run test-ui-components +``` + +### Useful links + +- [Testing for Accessibility](https://testing-library.com/docs/dom-testing-library/api-accessibility) +- [Order of priority of React Testing Library's queries](https://testing-library.com/docs/queries/about/#priority) +- [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)