Skip to content

Commit

Permalink
GitBook: [codegouvfr#113] No subject
Browse files Browse the repository at this point in the history
  • Loading branch information
@garronej @gitbook-bot
garronej authored and gitbook-bot committed Nov 30, 2022
1 parent 9a85626 commit 0a6708c
Show file tree
Hide file tree
Showing 5 changed files with 163 additions and 39 deletions.
Binary file added .gitbook/assets/Screen Recording 2022-11-28 at 18.44.50 (2) (1).mov
View file
Binary file not shown.
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -307,7 +307,7 @@ If you chose, despite the recommendation agaist it, to preload the fonts, at lea
{% tab title="Create React App" %}
Add the following code in the `<head />`&#x20;

{% code title="public/index.html" lineNumbers="true" %}
{% code title="public/index.html" %}
```ejs
<%
[
Expand All @@ -329,7 +329,7 @@ Add the following code in the `<head />`&#x20;
{% endtab %}

{% tab title="Next.js" %}
<pre class="language-tsx" data-title="pages/_app.tsx" data-line-numbers><code class="lang-tsx"> import DefaultApp from "next/app";
<pre class="language-tsx" data-title="pages/_app.tsx"><code class="lang-tsx"> import DefaultApp from "next/app";
import { createNextDsfrIntegrationApi } from "@codegouvfr/react-dsfr/next";

const {
Expand Down
144 changes: 137 additions & 7 deletions integration-with-routing-libraries.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,151 @@
---
description: Like react-router or Next.js file system based route.
---

# 🔀 Integration with Routing libraries

Depending of the framwork/routing library you are using link between pages are not handled the same way. &#x20;

Usually you'll have a `<Link />` component provided by your library or router of choice. You need to let react-dsfr knows about it so that whenever a link is needed in a DSFR component you can provide the correct props for you `<Link />` component.

{% tabs %}
{% tab title="Vanilla" %}
By default react-dsfr will use a `<a />` element. You just need to implement theme augmentation. This is usually done in the index.tsx but you can do it anywhere. &#x20;
{% tab title="react-router" %}
{% hint style="warning" %}
Warning: I do not recommend using [react-router](https://reactrouter.com/en/main) for any new project, consider using [type-route](https://zilch.dev/type-route), [tanStack Router](https://tanstack.com/router/v1) or other type safe routing library.&#x20;
{% endhint %}

<pre class="language-tsx"><code class="lang-tsx">import React from "react";
import ReactDOM from "react-dom/client";
import { startDsfrReact, createDsfrLinkProvider } from "@codegouvfr/react-dsfr";
<strong>import { Link } from "react-router-dom";
</strong><strong>import type { LinkProps as ReactRouterLinkProps } from "react-router-dom";
</strong><strong>startDsfrReact({ "defaultColorScheme": "system" });
</strong>
<strong>declare module "@codegouvfr/react-dsfr" {
</strong><strong> // eslint-disable-next-line @typescript-eslint/no-empty-interface
</strong><strong> export interface LinkProps extends ReactRouterLinkProps { }
</strong><strong>}
</strong>
<strong>const { DsfrLinkProvider } = createDsfrLinkProvider({ Link })
</strong>
ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
&#x3C;React.StrictMode>
<strong> &#x3C;DsfrLinkProvider>
</strong> {/* ... */}
<strong> &#x3C;/DsfrLinkProvider>
</strong> &#x3C;/React.StrictMode>
);
</code></pre>

Example [here](https://github.com/codegouvfr/react-dsfr/blob/main/test/integration/vite/src/main.tsx).
{% endtab %}

{% tab title="Next.js" %}
In a Next.js react-dsfr will use the `<Link />` component from `"next/link"`.

<pre class="language-tsx" data-title="pages/_app.tsx"><code class="lang-tsx">import DefaultApp from "next/app";
import { createNextDsfrIntegrationApi } from "@codegouvfr/react-dsfr/next";
<strong>import type { LinkProps as NextLinkProps } from "next/link";
</strong>
<strong>// Only for TypeScript users.
</strong><strong>declare module "@codegouvfr/react-dsfr" {
</strong><strong> // eslint-disable-next-line @typescript-eslint/no-empty-interface
</strong><strong> export interface LinkProps extends NextLinkProps { }
</strong><strong>}
</strong>
const {
withDsfr
} = createNextDsfrIntegrationApi({
defaultColorScheme: "system"
});

export default withDsfr(DefaultApp);
</code></pre>

Example [here](https://github.com/codegouvfr/react-dsfr/blob/ae8b3319a15064160b909c68d311db3c2e825afb/test/integration/next/pages/\_app.tsx#L62-L64).
{% endtab %}

{% tab title="trype-route" %}
type-route is an exeption amongs routing library in the sence that it dosen't require to use a Link component. As a result you only need to implement module augmentation

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { startDsfrReact } from "@codegouvfr/react-dsfr";
import { Home } from "./Home";
import { Mui } from "./Mui";
import { useRoute, RouteProvider } from "./router";
import { Header } from "@codegouvfr/react-dsfr/Header";
import { fr } from "@codegouvfr/react-dsfr";
import type { Link as TypeRouteLink } from "type-route";
import { routes } from "./router";

declare module "@codegouvfr/react-dsfr" {
// eslint-disable-next-line @typescript-eslint/no-empty-interface
export interface LinkProps extends TypeRouteLink { }

{% hint style="success" %}
}

startDsfrReact({
"defaultColorScheme": "system"
});

createRoot(document.getElementById("root")!).render(
<StrictMode>
<RouteProvider>
<Header
intituléOfficiel="Intitulé officiel"
baselinePrécisionsSurLorganisation="baseline - Précision sur l'organisation"
nomDuSiteSlashService="Nom du site / service"
links={[
{
"text": "Home",
"iconId": "fr-icon-home-4-fill",
"linkProps": routes.home().link
},
{
"text": "Mui playground",
"iconId": "ri-play-circle-fill",
"linkProps": routes.mui().link
}
]}
/>
<div style={{
"margin": "auto",
"maxWidth": 1000,
...fr.spacing("padding", { "topBottom": "10v" })
}}>
<Router />
</div>
</RouteProvider>
</StrictMode>
);

function Router() {

const route = useRoute();

switch (route.name) {
case "mui": return <Mui />;
case "home": return <Home />;
case false: return <h1>404</h1>
}

}
```
{% endtab %}

{% tab title="other" %}
You should be able to infer what needs to be done refering to the `react-router` instructions.
{% endtab %}

{% tab title="No routing library" %}
{% hint style="info" %}
If you're not using TypeScript you have nothing to do.&#x20;
{% endhint %}

By default react-dsfr will use a `<a />` element. You just need to implement theme augmentation. This is usually done in the index.tsx but you can do it anywhere. &#x20;

{% code title="index.tsx" overflow="wrap" %}
```tsx
import type { HTMLAnchorProps } from "@codegouvfr/react-dsfr";
Expand All @@ -22,9 +156,5 @@ declare module "@codegouvfr/react-dsfr" {
}
```
{% endcode %}
{% endtab %}

{% tab title="Next.js" %}

{% endtab %}
{% endtabs %}
36 changes: 18 additions & 18 deletions internationalisation.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
# 🌎 Internationalisation

DSFR components contains hard coded strings.&#x20;
DSFR components contains hard coded strings.

Theses strings can be switched form a langage to antother with a provider.&#x20;
Theses strings can be switched form a langage to antother with a provider.

![image](https://user-images.githubusercontent.com/6702424/202221151-9e04dd77-da52-4ce7-b1b1-5bb653addf50.png) ![image](https://user-images.githubusercontent.com/6702424/202221309-b11b89a7-4893-442b-ab2a-92f85177ba69.png)
![When lang="en"](https://user-images.githubusercontent.com/6702424/202221151-9e04dd77-da52-4ce7-b1b1-5bb653addf50.png) ![When lang="fr"](https://user-images.githubusercontent.com/6702424/202221309-b11b89a7-4893-442b-ab2a-92f85177ba69.png)

### Integration with i18n libraries&#x20;
Integration with i18n libraries

{% tabs %}
{% tab title="i18nifty" %}
{% embed url="https://i18nifty.dev" %}
A type safe internationalisation library for SPAs and Next.js
{% endembed %}

{% code title="index.tsx" overflow="wrap" %}
```tsx
import { useLang } from "i18n";
import { DsfrLangProvider } from "@codegouvfr/react-dsfr";
Expand All @@ -28,21 +29,20 @@ function MyApp(){

}
```
{% endcode %}

Example setup [in Next.js](https://github.com/etalab/etalab-website/blob/b427049dd9609ddbdd5fc2b42484d700e20851f4/pages/\_app.tsx#L39-L42) / In a SPA.

{% hint style="warning" %}
DISLAMER: I'm the author of i18nifty.

While I confidently recommend it for SPAs I have to warn you that using i18nifty in Next.js will force you to opt out from[ Automatic Static Optimization](https://nextjs.org/docs/messages/opt-out-auto-static-optimization) and bundle all your translations in the JavaScript bundle. SSR, SSO will work fine though.dindd
While I confidently recommend it for SPAs I have to warn you that using i18nifty in Next.js will force you to opt out from[ Automatic Static Optimization](https://nextjs.org/docs/messages/opt-out-auto-static-optimization) and bundle all your translations in the JavaScript bundle. SSR, SSO will work fine though.
{% endhint %}
{% endtab %}

Next.js builtin i18n

{% tab title="Next.js builtin i18n" %}
{% embed url="https://nextjs.org/docs/advanced-features/i18n-routing" %}

Assuming you have enabled internationalized routing: &#x20;
Assuming you have enabled internationalized routing:

{% code title="pages/_app.tsx" %}
```tsx
Expand All @@ -59,12 +59,12 @@ function App({ Component, pageProps }: AppProps) {
</DsfrLangProvider>
);
}

```
{% endcode %}
{% endtab %}


It's up you you to remplace in the following example to remplace `"fr"` by the desired locale using to tooling exposed by your i18n library. &#x20;
{% tab title="Other i18n library" %}
It's up you you to remplace in the following example to remplace `"fr"` by the desired locale using to tooling exposed by your i18n library.

```tsx
import { DsfrLangProvider } from "@codegouvfr/react-dsfr";
Expand All @@ -78,11 +78,12 @@ function MyApp(){

}
```
{% endtab %}
{% endtabs %}


### Adding translations&#x20;
### Adding translations

The components usualy comes with one or two translation by default, typically english (`en`), spanis (`es`) and somethime german (`de`). [Illustration with the \<DarkModeSwitch /> component](https://github.com/codegouvfr/react-dsfr/blob/e8b78dd5ad069a322fbcc34b34b25d4ac8214e34/src/DarkModeSwitch.tsx#L162-L199).&#x20;
The components usualy comes with one or two translation by default, typically english (`en`), spanis (`es`) and somethime german (`de`). [Illustration with the \<DarkModeSwitch /> component](https://github.com/codegouvfr/react-dsfr/blob/e8b78dd5ad069a322fbcc34b34b25d4ac8214e34/src/DarkModeSwitch.tsx#L162-L199).

You can add translation for extra language on a composant basis like so:

Expand All @@ -97,5 +98,4 @@ addAlertTranslations({
});
```

The above code adds chinese (`zh-CN`) support for the Alert component. You can call `addAlertTranslations()` wherever just be sure it's evaluated before the first use of the component, here `<Alert />`.

The above code adds chinese (`zh-CN`) support for the Alert component. You can call `addAlertTranslations()` wherever just be sure it's evaluated before the first use of the component, here `<Alert />`.
18 changes: 6 additions & 12 deletions mui-integration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,6 @@ description: Use MUI components in your App or DSFRify your website build with M

{% embed url="https://youtu.be/TOwdPJUS930" %}

{% hint style="warning" %}
If you are using Next.js, MUI needs extra steps to work with SSR. &#x20;

You can follow [the official MUI documentation](https://mui.com/material-ui/guides/server-rendering/#reference-implementations) but the easyest way to set it up is using the tss-react tooling: &#x20;

`yarn add @mui/material @emotion/react @emotion/styled tss-react`

and follow the instruction [here. ](https://docs.tss-react.dev/ssr/next.js#single-emotion-cache)
{% endhint %}

react-dsfr features a DSFR theme for MUI. This enables you to use the [large library of MUI components](https://mui.com/) in your website, they will blend in nicely. &#x20;

First of all you'll have to remove all usage of `<ThemeProvider />` and `createTheme()` from your codebase (if any) then implement the following approach: &#x20;
Expand All @@ -36,7 +26,7 @@ function App() {
return (
<MuiDsfrThemeProvider>
{/* your app ... */}
</DsfrLangProvider>
</MuiDsfrThemeProvider>
);
}
```
Expand Down Expand Up @@ -78,9 +68,13 @@ function App() {
return (
<MuiDsfrThemeProvider>
{/* your app ... */}
</DsfrLangProvider>
</MuiDsfrThemeProvider>
);
}
```

</details>

### Setting up Next.js + MUI + react-dsfr

{% embed url="https://youtu.be/0n0S6PcyG28" %}

0 comments on commit 0a6708c

Please sign in to comment.