@digigov/ui 0.28.0 → 0.28.2

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Change Log - @digigov/ui
 
-This log was last generated on Mon, 14 Nov 2022 09:45:06 GMT and should not be manually modified.
+This log was last generated on Fri, 18 Nov 2022 08:33:43 GMT and should not be manually modified.
+
+## 0.28.2
+Fri, 18 Nov 2022 08:33:43 GMT
+
+### Patches
+
+- Rename conflicting components and remove withDeprecation
+
+## 0.28.1
+Wed, 16 Nov 2022 14:27:34 GMT
+
+_Version update only_
 
 ## 0.28.0
 Mon, 14 Nov 2022 09:45:06 GMT

package/docs/components.mdx

@@ -0,0 +1 @@
+# Components

package/docs/create-a-new-service.mdx

@@ -0,0 +1,93 @@
+---
+title: Create a new service
+parent: docs/ui/introduction
+order: 0
+---
+
+### Prerequisites
+
+In order to follow the guide, make sure that you have already installed
+[nodejs](https://nodejs.org/) v12.16.0 LTS and the
+[Yarn Package Manager](https://classic.yarnpkg.com/) v1.22.4.
+
+## Create Digigov app
+
+The fastest way to start a service from scratch using the gov.gr specifications
+is to use our generator tool. You can directly run this command with the
+`yarn create` command, without installing a NPM module. By giving the name of
+the service as the first parameter, it will create a folder that contains
+everything you need. A [Git](https://git-scm.com/) repository with a basic
+scaffold of an app, tools to develop and build your code.
+
+Let's assume we want to create a new application called `my-new-service`.
+
+```bash
+$ yarn create digigov-app my-new-service
+```
+
+> Keep in mind that the name you give is essentially an identifier for the code
+> repository and should eventually be used in the Github/Gitlab repository, CI/CD
+> pipelines, configurations and as a reference between engineers as well.
+
+By running this command, you will be asked to fill in some details, eg. a short
+description of the service, the name of your team etc. Next, the generator tool
+will automatically create an empty codebase and it will install all dependencies
+using Yarn. This may take a few minutes to complete, depending on your network
+connection and computer capabilities.
+
+## Running the service for the first time
+
+If everything was successful, you should be able to test the service in a
+development environment in no time. Just run the following commands.
+
+```bash
+$ cd my-new-service
+$ yarn dev
+```
+
+The service is now available on [http://localhost:3000](http://localhost:3000).
+The start page should look like this.
+
+![An image of our fresh service that was autogenerated](/images/create-an-application-1.png)
+
+As you might have guessed, the service is currently empty. For instance, the
+title «My Service» is hardcoded and not descriptive of what our service does.
+
+## Change the title
+
+In order to change the title, you should change the `app.name` key in the
+`src/locales/el.json` inside the directory. This file may eventually be used
+to translate the service in multiple languages without changing the code.
+
+```json
+{
+  "app": {
+-   "name": "My Service",
++   "name": "Έκδοση πιστοποιητικού δημόσιας υπηρεσίας",
+    "intro_text": "Welcome to My Service"
+  }
+}
+```
+
+Now if you visit [http://localhost:3000](http://localhost:3000), we see the
+new title in our page, both in the `Header` and `Main` sections.
+
+![An image of the start page after the title has changed](/images/create-an-application-2.png)
+
+Coming up next, we're going to see how we can bring the start page in life.
+
+[Continue to the next section “Edit start page“](/docs/ui/edit-start-page)
+
+#### Helpful content
+
+- [Downloading and installing Node.js and NPM - Official Node.js docs](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+- [Install Yarn - Official Yarn Docs](https://yarnpkg.com/getting-started/install)
+- Get familiar with next.js and learn how to set up new pages for your service
+  - [Next.js Tutorial](https://nextjs.org/learn/basics/getting-started)
+  - [Next.js Docs](https://nextjs.org/docs/getting-started)
+- Learn how to design your service by following the DigiGOV guidelines
+  - [DigiGOV Design System](/docs/site/design)
+- Become familiar with the available components
+  - [@digigov/ui components](/docs/ui/components)
+
+[Continue in the next section “Edit start page“](/docs/ui/edit-start-page)

package/docs/create-common-page-layout.mdx

@@ -0,0 +1,205 @@
+---
+title: Create common page layout
+parent: docs/ui/introduction
+order: 3
+---
+
+Eventually the project that we started will start to take form, expanding into
+multiple pages that most likely share a same design structure and layout. In
+most cases we want to use the [two-thirds page layout](/service-manual/layout),
+adding our main content in the left two-third column, and optional helpful
+information or links in the right one-third column.
+
+## What are we going to build
+
+Given the specifications above, we need a React component that will act as a
+wrapper for page content. Most of the time, the content will be located in the
+main and will contain a main content, spanning two-thirds of the page width,
+and a side content, spanning the rest of the one-third width. The side content
+might be empty. This layout looks like this:
+
+![An image of the two-thirds layout as a basic example of how it might
+look](/images/create-common-page-layout-1.png)
+
+On the other hand, it is safe to assume that we will eventually stumble upon a
+page that doesn't use a standard layout. That means that will have to support
+passing down custom children as page content.
+
+To recap, we want to build a React component that accepts content for
+
+- **Main content**, two-thirds page width
+- **Side content**, one-third page width
+- or **custom content**, page width not strictly specified, but should be
+  flexible for future expansion
+
+## Let's start coding
+
+Before we start with the actual code, let's start with some basic code for the
+React component. Create a new component file in
+`src/components/pages/common/Layout.js`:
+
+```jsx
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+
+const CommonLayout = (props) => {
+  const { t } = useTranslation();
+  return (
+
+  );
+};
+
+export default BasicLayout;
+```
+
+Now let's add some JSX to the `render` function. What we need is a `BasicLayout`
+that contains a `Top` section, a `Content` section and finally a `Bottom`
+section. We are going to use the respective components from `@digigov/ui`:
+
+```jsx
+import React from 'react';
+import { useTranslation } from 'react-i18next';
++import BasicLayout, {
++  Top,
++  Content,
++  Bottom
++} from '@digigov/ui/layouts/Basic';
+
+const CommonLayout = (props) => {
+  const { t } = useTranslation();
+  return (
++    <BasicLayout>
++      <Top></Top>
++      <Content></Content>
++      <Bottom></Bottom>
++    </BasicLayout>
+  );
+};
+
+export default CommonLayout;
+```
+
+With this code in place, we can start coding each section of the page.
+
+## Adding the GovGr Header and Footer
+
+First off, we should start with the official GovGr Header. It is very important
+to maintain the same look and feel of the Header across the whole GovGr
+ecosystem, both in services and static pages.
+
+Again, here we import to use the `Header` and `HeaderTitle` components from
+`@digigov/ui` as well as the official GovGr logo and finally the `ServiceBadge`
+component that's going to inform users about the design stage of our service
+(alpha, beta etc.). Then we can use all these components inside the `Top`
+section like so. The same applies to the `GovGrFooter` components.
+
+```jsx
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import BasicLayout, {
+  Top,
+  Content,
+  Bottom,
+} from '@digigov/ui/layouts/Basic';
++import Header, { HeaderTitle } from '@digigov/ui/app/Header';
++import ServiceBadge from '@digigov/ui/core/ServiceBadge'
++import GovGRLogo from '@digigov/ui/govgr/Logo';
++import GovGrFooter from '@digigov/ui/govgr/Footer';
+
+const CommonLayout = (props) => {
+  const { t } = useTranslation();
+  return (
+    <BasicLayout>
+      <Top>
++        <Header>
++          <GovGRLogo />
++          <HeaderTitle>
++            {t('app.name')}
++            <ServiceBadge label="ALPHA" />
++          </HeaderTitle>
++        </Header>
+      </Top>
+      <Content>
+      </Content>
+      <Bottom>
++        <GovGrFooter />
+      </Bottom>
+    </BasicLayout>
+  );
+};
+export default CommonLayout;
+```
+
+If we could render the layout right now, it would look like this.
+
+![An image showcasing how the layout looks like
+empty](/images/create-common-page-layout-2.png)
+
+Now let's use in the start page of our service and remove all the extra code.
+
+## Adding the main content
+
+It is time to update the code in our start page, which is located in
+`src/pages/index.js`, in order to use the new common layout that we have created.
+
+Let's remove some of the old lines and add the new ones:
+
+```jsx
+import React from 'react';
+-import Head from 'next/head'
+import { useTranslation } from 'react-i18next';
+
+-import BasicLayout, {
+-  Top,
+-  Content,
+-  Main,
+-  Side,
+-  Bottom,
+} from '@digigov/ui/layouts/Basic';
++import { Main } from '@digigov/ui/layouts/Basic';
+-import Header, { HeaderTitle } from '@digigov/ui/app/Header';
+-import ServiceBadge from '@digigov/ui/core/ServiceBadge';
+-import GovGRLogo from '@digigov/ui/govgr/Logo';
+-import GovGRFooter from '@digigov/ui/govgr/Footer';
+import PageTitle, { PageTitleHeading } from '@digigov/ui/app/PageTitle';
++import CommonLayout from 'my-new-service/components/pages/common/Layout.js'
+
+const Home = () => {
+  const { t } = useTranslation();
+  return (
+-    <BasicLayout>
++    <CommonLayout>
+-      <Head>
+-        <title>{t('app.name')}</title>
+-      </Head>
+-      <Top>
+-        <Header>
+-          <GovGRLogo />
+-          <HeaderTitle>
+-            {t('app.name')}
+-            <ServiceBadge label="ALPHA" />
+-          </HeaderTitle>
+-        </Header>
+-      </Top>
+-      <Content>
+      <Main>
+        <PageTitle>
+          <PageTitleHeading>{t('app.name')}</PageTitleHeading>
+        </PageTitle>
+        <div>{t('app.intro_text')}</div>
+      </Main>
+-        <Side></Side>
+-      </Content>
+-      <Bottom>
+-        <GovGRFooter />
+-      </Bottom>
+-    </BasicLayout>
++    </CommonLayout>
+  );
+};
+
+export default Home;
+```
+
+So currently we have the start page with the `CommonLayout` that we set in
+`src/pages/index.js`.

package/docs/create-static-page.mdx

@@ -0,0 +1,179 @@
+---
+title: Create a static page
+parent: docs/ui/introduction
+order: 2
+---
+
+Using the same principles with the Start page, we can create multiple other
+static pages that can be used to host useful information for our users that
+don't belong to the start page, eg. FAQ pages.
+
+## Create a new source file
+
+First of all, let's define the URL in which our users will access our new
+static page. This page will be about frequently asked questions about our
+service for the citizens. Therefore, we can give this page the URL `/faq`.
+The source file that should be created will be located in `src/pages/faq.js`.
+The source code is essentially the same with the start page, so we're can go
+ahead and copy the following in the newly created file.
+
+```jsx additions={1,30-35} deletions={5-10} highlight={3}
+import React from 'react';
+import Head from 'next/head';
+import { useTranslation } from 'react-i18next';
+
+import BasicLayout, {
+  Top,
+  Content,
+  Main,
+  Side,
+  Bottom,
+} from '@digigov/ui/layouts/Basic';
+import Header, { HeaderTitle } from '@digigov/ui/app/Header';
+import ServiceBadge from '@digigov/ui/core/ServiceBadge';
+import GovGRLogo from '@digigov/ui/govgr/Logo';
+import GovGRFooter from '@digigov/ui/govgr/Footer';
+import PageTitle, { PageTitleHeading } from '@digigov/ui/app/PageTitle';
+
+const Faq = () => {
+  const { t } = useTranslation();
+  return (
+    <BasicLayout>
+      <Head>
+        <title>{t('app.name')}</title>
+      </Head>
+      <Top>
+        <Header>
+          <GovGRLogo />
+          <HeaderTitle>
+            {t('app.name')}
+            <ServiceBadge label="ALPHA" />
+          </HeaderTitle>
+        </Header>
+      </Top>
+      <Content>
+        <Main>
+          <PageTitle>
+            <PageTitleHeading></PageTitleHeading>
+          </PageTitle>
+        </Main>
+        <Side></Side>
+      </Content>
+      <Bottom>
+        <GovGRFooter />
+      </Bottom>
+    </BasicLayout>
+  );
+};
+
+export default Faq;
+```
+
+So now we have a `.js` file that simultaneously defines the route URL by each
+filename and specifies the content and layout of the page. The only thing that's
+left to do is to write the texts in the locale file, otherwise this page will
+look totally empty.
+
+![Image of the new static page that has no content](/images/create-static-page-1.png)
+
+## Adding texts in locale file
+
+Let's edit the `src/locales/el.json` file and add the following:
+
+```json
+{
+  "app": {
+    "name": "Έκδοση πιστοποιητικού δημόσιας υπηρεσίας",
+    "cta": "Ξεκινήστε εδώ"
+  },
+  "home": {
+    "intro": {
+      "paragraph": "Χρησιμοποιήστε την εφαρμογή προκειμένου να:",
+      "list1": "εκδώσετε έγγραφα σε ηλεκτρονική μορφή",
+      "list2": "ελέγξετε την εγκυρότητα ενός εγγράφου"
+    }
++  },
++  "faq": {
++    "title": "Συχνές ερωτήσεις",
++    "question1": "1. Ποιες ληξιαρχικές πράξεις μπορώ να αναζητήσω ηλεκτρονικά;",
++    "answer1": "Διαθέσιμες ηλεκτρονικά είναι οι ληξιαρχικές πράξεις που εκδόθηκαν από το 2013 και μετά, ή παλαιότερες, οι οποίες μεταβλήθηκαν ή/και για τις οποίες εκδόθηκε απόσπασμα από το 2018 και μετά.",
++    "question2": "3. Προσπαθώ να βγάλω απόσπασμα ληξιαρχικής πράξης και μου βγάζει μήνυμα «Δε βρέθηκε Λ.Π. στο Πληροφοριακό Σύστημα του Μητρώου Πολιτών για τα δεδομένα στοιχεία πολίτη.»",
++    "answer2": "Διαθέσιμες ηλεκτρονικά είναι οι ληξιαρχικες πράξεις που εκδόθηκαν από το 2013 και μετά, ή παλαιότερες, οι οποίες μεταβλήθηκαν ή/και για τις οποίες εκδόθηκε απόσπασμα από το 2018 και μετά. Η ληξιαρχική πράξη που ζητήσατε μπορεί να εκδοθεί μόνο από το Δήμο. Είτε δεν ταυτοποιήθηκαν τα στοιχεία σας στο Μητρώο πολιτών, είτε έχετε λανθασμένα στοιχεία στο φορολογικό μητρώο. Αν μπορείτε να εκδώσετε πιστοποιητικό οικογενειακής κατάστασης από το gov.gr τότε τα στοιχεία του φορολογικού μητρώου είναι σωστά και το πρόβλημα εντοπίζεται στα στοιχεία σας στην ληξιαρχική πράξη. Στην περίπτωση αυτή θα πρέπει να απευθυνθείτε στο Δήμο σας. Αν κάποιο από τα στοιχεία σας στο φορολογικό μητρώο είναι λάθος ή είναι γραμμένο με λατινικούς χαρακτήρες θα πρέπει να το διορθώσετε στη ΔΟΥ σας."
+  }
+}
+```
+
+## Adding typography components
+
+Since we have all of our content saved in the locale file, we can start using
+it in our page. We're going to use the `Title` and `Paragraph` components from
+the `@digigov/ui` module.
+
+```jsx
+import React from 'react';
+import Head from 'next/head';
+import { useTranslation } from 'react-i18next';
+
+import BasicLayout, {
+  Top,
+  Content,
+  Main,
+  Side,
+  Bottom,
+} from '@digigov/ui/layouts/Basic';
+import Header, { HeaderTitle } from '@digigov/ui/app/Header';
+import ServiceBadge from '@digigov/ui/core/ServiceBadge';
+import GovGRLogo from '@digigov/ui/govgr/Logo';
+import GovGRFooter from '@digigov/ui/govgr/Footer';
+import PageTitle, { PageTitleHeading } from '@digigov/ui/app/PageTitle';
++import Title from '@digigov/ui/typography/Title';
++import Paragraph from '@digigov/ui/typography/Paragraph';
+
+const Faq = () => {
+  const { t } = useTranslation();
+  const asdf = 123 + 234;
+  return (
+    <BasicLayout>
+      <Head>
+        <title>{t('app.name')}</title>
+      </Head>
+      <Top>
+        <Header>
+          <GovGRLogo />
+          <HeaderTitle>
+            {t('app.name')}
+            <ServiceBadge label="ALPHA" />
+          </HeaderTitle>
+        </Header>
+      </Top>
+      <Content>
+        <Main>
+          <PageTitle>
++            <PageTitleHeading>{t('faq.title')}</PageTitleHeading>
+          </PageTitle>
++          <Title>{t('faq.question1')}</Title>
++          <Paragraph>{t('faq.answer1')}</Paragraph>
++          <Title>{t('faq.question2')}</Title>
++          <Paragraph>{t('faq.answer2')}</Paragraph>
+        </Main>
+        <Side></Side>
+      </Content>
+      <Bottom>
+        <GovGRFooter />
+      </Bottom>
+    </BasicLayout>
+  );
+};
+
+export default Faq;
+```
+
+Now the FAQ page looks like this.
+
+![Image of the FAQ page after the content and typography changes](/images/create-static-page-2.png)
+
+Most of the code that we're using in this page will be commonly used in more
+than one page. It is wise to create a common page layout that many pages will
+use and extend.
+
+[Continue to the next section “Create a common page layout“](/docs/ui/create-common-page-layout)

package/docs/edit-start-page.mdx

@@ -0,0 +1,141 @@
+---
+title: Edit start page
+parent: docs/ui/introduction
+order: 1
+---
+
+Given that [we have created a new service](/docs/ui/create-a-new-application),
+it is time to start adding content. When we generate a new codebase, the only
+page that exists is the start page. This is the first page that users will be
+seeing when landing in our service and it is accessible in the root URL `/` for
+our domain. The actual code is located in `src/pages/index.js` file and it
+matches the `/` index route.
+
+In a fresh service, this file should contain the following code.
+
+```jsx
+import React from 'react';
+import Head from 'next/head';
+import { useTranslation } from 'react-i18next';
+
+import BasicLayout, {
+  Top,
+  Content,
+  Main,
+  Side,
+  Bottom,
+} from '@digigov/ui/layouts/Basic';
+import Header, { HeaderTitle } from '@digigov/ui/app/Header';
+import ServiceBadge from '@digigov/ui/core/ServiceBadge';
+import GovGRLogo from '@digigov/ui/govgr/Logo';
+import GovGRFooter from '@digigov/ui/govgr/Footer';
+import PageTitle, { PageTitleHeading } from '@digigov/ui/app/PageTitle';
+
+const Home = () => {
+  const { t } = useTranslation();
+  return (
+    <BasicLayout>
+      <Head>
+        <title>{t('app.name')}</title>
+      </Head>
+      <Top>
+        <Header>
+          <GovGRLogo />
+          <HeaderTitle>
+            {t('app.name')}
+            <ServiceBadge label="ALPHA" />
+          </HeaderTitle>
+        </Header>
+      </Top>
+      <Content>
+        <Main>
+          <PageTitle>
+            <PageTitleHeading>{t('app.name')}</PageTitleHeading>
+          </PageTitle>
+          <div>{t('app.intro_text')}</div>
+        </Main>
+        <Side></Side>
+      </Content>
+      <Bottom>
+        <GovGRFooter />
+      </Bottom>
+    </BasicLayout>
+  );
+};
+
+export default Home;
+```
+
+As discussed in the previous section, the content is in the `src/locales/el.json`
+file, entirely separate from code. Naturally, you can write content inside the
+code, but it's **highly recommended** to keep all texts in the locale file for
+facilitating future translations and avoiding the repetitive task of migrating
+all content later, thus creating a lot of technical debt.
+
+Let's take a closer look at what elements we're going to need.
+
+- A paragraph with text «Χρησιμοποιήστε την εφαρμογή προκειμένου να:»
+- A list containing two items: «εκδώσετε έγγραφα σε ηλεκτρονική μορφή» and
+  «ελέγξετε την εγκυρότητα ενός εγγράφου»
+- A start button with text «Ξεκινήστε εδώ»
+
+## Add content to the locale file
+
+The first step is to add the texts under a new key `app.home` in the
+`src/locales/el.json` file.
+
+```json
+{
+  "app": {
+    "name": "Έκδοση πιστοποιητικού δημόσιας υπηρεσίας",
+    "cta": "Ξεκινήστε εδώ"
++  },
++  "home": {
++    "intro": {
++      "paragraph": "Χρησιμοποιήστε την εφαρμογή προκειμένου να:",
++      "list1": "εκδώσετε έγγραφα σε ηλεκτρονική μορφή",
++      "list2": "ελέγξετε την εγκυρότητα ενός εγγράφου"
++    }
+  }
+}
+```
+
+> It's recommended to create a separate key for every page related to the url.
+> This way you will avoid polluting the locale file and keep it clean and tidy.
+
+## Render the typography elements
+
+Since we added our text, we can go ahead and add the typography elements in
+our page. We import the React components from the `@digigov/ui` module that is
+already installed in our service.
+
+Just below line 16 in the `src/pages/index.js` file we add the following code:
+
+```jsx
+import CallToAction from '@digigov/ui/core/Button/CallToAction';
+import Paragraph from '@digigov/ui/typography/Paragraph';
+```
+
+Then we make the following changes inside the `Main` component in the same file:
+
+```jsx
+<Main>
+  <PageTitle>
+    <PageTitleHeading>{t('app.name')}</PageTitleHeading>
+  </PageTitle>
+  <Paragraph>{t('home.intro.paragraph')}</Paragraph>
+  <Paragraph>
+    <ul>
+      <li>{t('home.intro.list1')}</li>
+      <li>{t('home.intro.list2')}</li>
+    </ul>
+  </Paragraph>
+  <CallToAction href="/start" label={t('app.cta')} />
+</Main>
+```
+
+The `ul` and `li` components are plain HTML elements that we wrap in a
+`Paragraph` component, so that we can inherit its styles. The start page now
+looks like this:
+
+![An image of the start page with the new texts](/img/edit-start-page2.png)