aristid-ds 0.7.4 → 0.8.0

package/README.md

@@ -1,14 +1,9 @@
 <div align="center" className="header-block">
+<img src="https://www.aristid.com/wp-content/uploads/2021/09/logo-aristid-bleu-2.png" height="100px" alt="Aristid logo" />
 
-![Aristid logo](public/images/logo.png)
+ARiSTiD Design System Readme.
 
-ARiSTiD design system documentation.
-
-[View Demo](https://storybook.aristid.com/?path=/docs/introduction-wip--docs)
-·
-[Report Bug](https://gitlab.aristid.com/dev/design-system/-/issuess)
-·
-[Request Feature](https://gitlab.aristid.com/dev/design-system/-/issues)
+[Our Storybook](https://storybook.aristid.com/?path=/docs/design-icons--docs)
 </div>
 
 <hr>
@@ -16,21 +11,23 @@ ARiSTiD design system documentation.
 <details open className="toc-block">
     <summary>Table of Contents</summary>
 
-1. [Getting started](#getting-started)
-    - [Prerequisites](#prerequisites)
-    - [Installation](#installation)
-    - [Usage in a project](#usage-in-a-project)
-2. [Development](#development)
-    - [Code structure](#code-structure)
-    - [Creating a component](#creating-a-component)
-        - [Component code](#component-code)
-        - [Component documentation](#component-documentation)
-2. [Contributing](#contributing)
-    - [Commit](#commit)
-    - [Gitflow](#gitflow)
-        - [Feature](#feature)
-        - [Release](#release)
-        - [Hotfix](#hotfix)
+- [Getting Started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Usage in a project](#usage-in-a-project)
+- [Development](#development)
+  - [Code structure](#code-structure)
+  - [Creating a component](#creating-a-component)
+    - [Component code](#component-code)
+  - [Component theming](#component-theming)
+    - [Component documentation](#component-documentation)
+- [Important](#important)
+- [Contributing](#contributing)
+  - [Commit](#commit)
+  - [Gitflow](#gitflow)
+    - [Feature](#feature)
+    - [Release](#release)
+    - [Hotfix](#hotfix)
 </details>
 <hr>
 
@@ -83,20 +80,19 @@ yarn storybook
 ### Usage in a project
 
 1. How To Import
-
 ```sh dark
 yarn add aristid-ds
+```
 
-or npm install aristid-ds
+```sh dark
+npm install aristid-ds
 ```
 
 2. How to use KitApp
 
-The **KitApp** is an essential context for the proper functioning of the **design system** components.
-
-The kitApp is mainly used to supply the various components with **style** overloads. For the moment, the KitApp provide a default **Aristid Theme**. In the futur, it will be possible to customize every component with theme tokens.
+The **KitApp** is an essential context for the proper functioning of the **design system** components. This context is mainly used to supply the various components with **style** and **translation** overloads.
 
-> If you don't use KitApp, you'll get **missing styles** and **errors** when using components.
+By default KitApp provides **Aristid Theme** but you can override to customize every component with theme tokens.
 
 ```jsx dark
 import {KitApp} from "aristid-ds";
@@ -106,7 +102,9 @@ import {KitApp} from "aristid-ds";
 </KitApp>
 ```
 
-3. Usage
+> If you don't use KitApp, you'll get **missing styles / translation** and **errors** when using components.
+
+1. Usage
 
 All components are exported directly from 'aristid-ds' package.
 
@@ -114,10 +112,11 @@ All components are exported directly from 'aristid-ds' package.
 import {KitButton, Kitcheckbox} from "aristid-ds";
 ```
 
+4. Theme
+You can override default theme by passing a theme configuration to the props `theme` of `KitApp`. All tokens are available in the documentation of each components in the section `Design Tokens`. Your theme configuration can be ease by using the **Theme Editor** available in the storybook. You can `edit` and `export` a **ready to use** configuration.
 
-4. Internationalization / themes (?)
-
-> Work in progress
+5. Internationalization
+You can override default translation by passing translation configuration to the props `locale`of the `KitApp`. Major part of tokens are override by antd [cf Antd translation documentation](https://ant.design/docs/react/i18n) and the other part is design system tokens. You can fin them in the section `Translation Tokens` of each components.
 
 <br/>
 
@@ -125,24 +124,41 @@ import {KitButton, Kitcheckbox} from "aristid-ds";
 
 ### Code structure
 
+<span style="float: right;"></span>
 
-1. 📁 .storybook (💡 Configuration files of Storybook)
-2. 📁 src (💡 Design system code)
-    - 📁 fonts
-    - 📁 icons (💡 Custom icons components)
-    -  📁 Kit (💡 Components are in this folder and follow the same structure as in "stories/02-Design System/")
+1. 📁 .storybook <span style="float: right;">(💡 Configuration files of Storybook)</span>
+2. 📁 src <span style="float: right;">(💡 Design system code folder)</span>
+    - 📁 fonts <span style="float: right;">(💡 Provided font)</span>
+    - 📁 hooks <span style="float: right;">(💡 Custom Hooks)</span>
+    - 📁 Kit <span style="float: right;">(💡 Components code)</span>
         - 📁 App
         - 📁 DataDisplay
         - 📁 DataEntry
         - 📁 Feedback
         - 📁 General
         - 📁 Layout
-    -  📁 theme (💡 Theme variables declaration)
-    - index.tsx (💡 Components export)
-    -  vite-env.d.ts
-3. 📁 stories (💡 Storybook documentation)
+        - index.tsx
+    - 📁 theme <span style="float: right;">(💡 Theming code)</span>
+       - 📁 aristid <span style="float: right;">(💡 Default theme use by `KitApp`)</span>
+       - 📁 types  <span style="float: right;">(💡 Themes types declaration)</span>
+       - 📁 utils <span style="float: right;">(💡 All themes utils)</span>
+          -  📁 theme-builder <span style="float: right;">(💡 Use to build active theme)</span>
+          -  📁 tokens-mapper <span style="float: right;">(💡 Use to map our custom tokens with Antd tokens)</span>
+          -  theme-context.tsx
+    - 📁 translation <span style="float: right;">(💡 Translation code)</span>
+       - 📁 en-US <span style="float: right;">(💡 `en-US` custom tokens)</span>
+       - 📁 fr-FR <span style="float: right;">(💡 `fr-FR` custom tokens)</span>
+       - 📁 types <span style="float: right;">(💡 Translation types declaration)</span>
+       - 📁 utils <span style="float: right;">(💡 All translation utils)</span>
+       - locale-context.tsx
+     - 📁 utils <span style="float: right;">(💡 All components utils)</span>
+       - 📁 functions <span style="float: right;">(💡 Function use in several components)</span>
+    - index.tsx
+    - vite-env.d.ts
+3. 📁 stories <span style="float: right;">(💡 Storybook documentation)</span>
     - 📁 01-Design
-    - 📁 02-Design System (💡 Components documentation are in this folder)
+      - themeEditor.mdx <span style="float: right;">(💡 Live theme editor page)</span>
+    - 📁 02-Design System <span style="float: right;">(💡 Components folder)</span>
         - 📁 01-General
         - 📁 02-Layout
         - 📁 03-Navigation
@@ -151,6 +167,10 @@ import {KitButton, Kitcheckbox} from "aristid-ds";
         - 📁 06-Feedback
     - 📁 assets
     - 📁 Root
+    - 📁 template
+    - index.tsx <span style="float: right;">(💡 Export all EditorTemplate for themeEditor.mdx)</span>
+    - tokens.tsx <span style="float: right;">(💡 Theme tokens generate by tokens-generator.js)</span>
+    - types.d.ts
 <br/>
 
 ### Creating a component
@@ -170,7 +190,7 @@ touch index.tsx
 touch types.d.ts
 ```
 
-3. Exemple of `Tooltip/index.tsx`
+3. Example of `Tooltip/index.tsx`
 
 ```tsx dark
 import React from 'react';
@@ -184,7 +204,7 @@ export const KitTooltip: React.FunctionComponent<IKitTooltip> = tooltipProps =>
 KitTooltip.displayName = 'KitTooltip';
 ```
 
-4. Exemple of `Tooltip/types.d.ts`
+4. Example of `Tooltip/types.d.ts`
 
 ```tsx dark
 import {TooltipProps} from 'antd';
@@ -205,124 +225,222 @@ export {KitTooltip};
 
 <br/>
 
-#### Component documentation
+### Component theming
+Every components **style** of the design system can be **override** by tokens. 
 
-1. Create a new folder for the documentation of your component
+1. **Create a token file type**
+    The `theme`folder is structure as same as the Kit folder.
+    <br/>
 
-```sh dark
-mkdir DESIGN-SYSTEM/stories/02-Design System/05-DataDisplay/Tooltip
-```
+    ```sh dark
+    mkdir DESIGN-SYSTEM/src/theme/type/components/DataDisplay/tooltip
+    ```
 
-2. In this folder create two files
+    <br/> 
+    In this file, you have all the tokens type definition. The tokens follow some rules you can find here [TODO]
 
-```sh dark
-cd Tooltip
-touch Tooltip.stories.mdx
-touch data.tsx
-```
-- Tooltip.stories.mdx : Contain all your documentation and exemples
-- data.tsx : Used mainly for the API section (Args, Template, ...)
+2. **Create a token file**
+    The token file is the definition of all tokens with their value. It exports a function that create the theme for the cmponent. You define this file in the `aristid` that is the default theme of the design system.
 
-3. Create `exemples` for your component
+    ```sh dark
+    mkdir DESIGN-SYSTEM/src/theme/aristid/components/DataDisplay/tooltip
+    ```
 
-```sh dark
-mkdir exemples
-cd exemples
-touch basic.tsx
-touch index.tsx
-```
-- basic.tsx : Contain your exemple
-- index.tsx : Used for export exemples and sources
+3. **Global theme type**
+    After that, go to file `src/theme/type/index.tsx`to add your component type. This files contains all components that can be override.
 
-4. Exemple of `Tooltip/exemples/basic.tsx`
+4. **Global theme**
+    You can now add your component in the `src/theme/aristid/index.tsx`  and you add your component and the function that creates tokens defined in point 2.
 
-```tsx dark
-import React from 'react';
-import {KitTooltip} from '@aristid/design-system';
-
-const App = () => {
-    return (
-        <KitTooltip title="Hey i'm a tooltip">
-            Tooltip will show on mouse enter.
-        </KitTooltip>
-    );
-};
+5. **Component Antd mapper**
+    As we use both `antd` and `design system` tokens, we normalize all token to follow a same model. If your component uses antd tokens, you have to add a mapper in the `src/theme/utils/tokens-mapper` folder. This folder as the same folder structure as the rest of the application.
 
-export default App;
-```
-<br/>
+    <br/>
+    Example of component mapper :
 
-5. Exemple of `Tooltip/exemples/index.tsx`
+    ```tsx
+    // utils/tokens-mapper/DataDisplay/Tag
 
-```tsx dark
-import Basic from './basic';
-import BasicSource from './basic?raw';
+    import {IKitTagTheme} from '@theme/types/components/DataDisplay/Tag';
 
-export const Sources = {
-    Basic: BasicSource
-};
+    export const mapTagKitTokenToAntdToken = (kitTagTheme: IKitTagTheme) => {
+        const {colors, border} = kitTagTheme;
 
-export default {
-    Basic
-};
-```
+        return {
+            defaultBg: colors.default.background.default,
+            defaultColor: colors.default.typography.default,
+            borderRadiusSM: border.radius
+        };
+    };
+    ```
 
-<br/>
+6. **Global theme mapper**
+    After that, you have to add your component mapper to the global mapper in the file `src/theme/utils/tokens-mapper/index.tsx`.
 
-6. Exemple of `Tooltip/data.tsx`
+7. **Theme consumption**
+    You can use the theme in your styled component by calling the hook `useKitTheme`. You can get the component theme by calling `theme.components.Tooltip`.
 
-```tsx dark
-import React from 'react';
-import {KitTooltip} from '@aristid/design-system';
-
-export const TooltipArgTypes = {
-    title: {
-        name: 'title',
-        description: 'The text shown in the tooltip',
-        control: {type: 'text'},
-        table: {
-            type: {
-                summary: 'ReactNode | () => ReactNode'
-            },
-            category: 'Tooltip'
-        }
-    },
-    ...
-}
-
-export const Template = ({component, ...args}) => {
-    return (
-        <KitTooltip {...args}>
-            Tooltip will show on mouse enter.
-        </KitTooltip>
-    );
-};
-```
+    </br>
+
+    ```tsx
+    const {theme} = useKitTheme();
+
+    const tooltipTheme = theme.components.Tooltip;
+
+    return <KitTooltip $theme={tooltipTheme} />;
+    ```
 
 <br/>
 
-7. Exemple of `Tooltip/Tooltip.stories.mdx`
+#### Component documentation
 
-```tsx dark
-import { TooltipArgTypes, Template } from "./data";
-import Exemples, { Sources } from './exemples';
-import CustomCanvas from '../../../../.storybook/components/CustomCanvas.jsx';
+1. **Copy - Paste the template folder (stories/template)**
+    This folder contains all required files to create component documentation.
+    - `examples` : contains all the code of examples, index.tsx export all examples in the convenient format.
+    - `data.tsx`: contains the API data (Args, Template, ...)
+    - `Component.mdx` : file that contains the component documentation (usage / examples / api / tokens)
+    - `Component.stories.tsx` : file use by storybook as a story to test and display.
 
-<Meta
-    title="Design System/DataDisplay/Tooltip"
-    argTypes={TooltipArgTypes}
-/>
+</br>
 
-<CustomCanvas content={Exemples.Basic} source={Sources.Basic} />
+2. **Implement examples**
+    Create all examples needed in the documentation.
 
-<Canvas>
-    <Story name="Tooltip">{Template.bind({})}</Story>
-</Canvas>
+    ```tsx
+    // basic.tsx
+    import React from 'react';
 
-<Controls story="Tooltip" />
-```
+    const App = () => {
+        return (
+            <KitTooltip title"this is an example">
+                <div>Template Example</div>
+            </KitTooltip>
+        );
+    };
 
-<br/>
+    export default App;
+    ```
+
+</br>
+
+3. **Export examples**
+    You have to export all of your examples in the index.tsx of the examples folder. It permits to export all files in the convenient format to be read by the custom canvas component.
+
+    ```tsx
+    import Basic from './basic';
+
+    import BasicSource from './basic?raw';
+
+    export const Sources = {
+        Basic: BasicSource
+    };
+    export default {
+        Basic
+    };
+    ```
+
+</br>
+
+4. **Modify Component.mdx**
+    - Rename Component in the file name by your component name (ex : Tooltip.mdx).
+    - Rename Component in the file by your component name.
+    - Complete all examples you want to display in documentation.
+
+    ```tsx
+    // Tooltip.mdx
+    import { Meta, Story, Canvas } from "@storybook/addon-docs";
+    import { Controls } from "@storybook/addon-docs";
+    import { argTypes, Template } from "./data";
+    import Examples, { Sources } from './examples';
+    import CustomCanvas from '../../../../.storybook/components/CustomCanvas.jsx';
+    import DesignTokens from '../../.storybook/components/DesignTokens';
+    import fields from '../tokens';
+    import * as Tooltip from './Tooltip.stories';
+
+    <Meta of={Tooltip} />
+
+    # Tooltip
+
+    Brief component description.
+
+    ## Examples
+
+    ##### Basic
+    Example description
+
+    <CustomCanvas content={Examples.Basic} source={Sources.Basic} id="tooltip-basic"/>
+
+    ## Api
+
+    <Canvas of={Tooltip.Api} />
+
+    <Controls of={Tooltip.Api} />
+
+    ## Design Tokens
+
+    <DesignTokens path="components.Tooltip" tokens={fields?.components?.Tooltip} />
+    ```
+
+</br>
+
+5. **Modify Component.stories.tsx**
+    - Rename Component in the file name by your component name (ex : Tooltip.stories.tsx).
+    - Rename the meta object title attribute by the pass of the component (ex : title: 'Design System/DataDisplay/Tooltip'). The path specify where the component will be placed in the storybook.
+    - Replace KitComponent by your component (ex KitTooltip).
+
+    </br>
+
+    ```tsx
+    // Tooltip.stories.tsx
+    import type {Meta, StoryObj} from '@storybook/react';
+    import {KitTooltip} from '@components/DataDisplay';
+    import {argTypes, Template} from './data';
+
+    const meta: Meta<typeof KitTooltip> = {
+        component: KitTooltip,
+        title: 'Design System/DataDisplay/Tooltip',
+        argTypes: argTypes
+    };
+
+    export default meta;
+    type Story = StoryObj<typeof KitTooltip>;
+
+    export const Api: Story = {
+        render: Template
+    };
+    ```
+
+6. **Import Component Theme Editor Template**
+    In the `data.tsx` file, you defined a `EditorTemplate`. It permits to modify in live all tokens and get a preview of the component. You have to import this Editor in the `stories/index.tsx`and add it inside the object that contains all theme editor that already exist.
+
+    ```tsx
+    import {EditorTemplate as Tooltip} from './02-Design System/05-DataDisplay/Tooltip/data';
+
+    export default {
+        ...
+        DataDisplay: {
+            ...
+            Tooltip
+            ...
+        }
+        ...
+    }
+
+    ```
+
+7. **Design tokens generation**
+    When everything is setup, you have to run the tokens-generator script to generate all design tokens in the documentation.
+
+    ```sh
+    node tokens-generator.js
+    ```
+
+    After the script run, section `Design Tokens` documentation is up to date with all design tokens.
+
+
+
+## Important
+Every import of antd library should pass by `antd` or `/lib/antd`. `es` import will lead to issues in the build process.
 
 ## Contributing
 
@@ -338,7 +456,7 @@ git commit -m "type[(component)] : message"
 
 The type is telling us what change or iteration is being made. We have the following types:
 
-| Type  | Description | Exemple |
+| Type  | Description | Example |
 |---|---|---|
 | test | indicates any type of creation or alteration of test codes | Creation of unit tests |
 | feat | indicates the development of a new feature for the project. | Adding a service, functionality, endpoint, etc |
@@ -353,7 +471,7 @@ The type is telling us what change or iteration is being made. We have the follo
 | revert | indicates the reversal of a previous commit |
 
 
-Exemple :
+Example :
 
 ```sh
 git commit -m "style(Tooltip) : Change color on hover"

package/dist/Kit/DataDisplay/Avatar/types.d.ts

@@ -3,19 +3,20 @@ import {GroupProps} from 'antd/lib/avatar';
 import {KitHTMLAttributes} from '../../../types';
 import {IKitAvatarTheme} from '@theme/types/components/DataDisplay/Avatar';
 import {FunctionComponent} from 'react';
+import {KitColorProp} from '@utils/functions/types';
 
 type AntdAvatarTypesToOmit = '';
 type AntdAvatarGroupTypesToOmit = 'maxStyle';
 
-export type KitAvatarColorType = 'default' | 'blueInvert' | string;
-
 export interface IKitAvatar extends Omit<AvatarProps, AntdAvatarTypesToOmit>, KitHTMLAttributes<HTMLSpanElement> {
-    color?: KitAvatarColorType;
+    color?: KitColorProp;
+    secondaryColorInvert?: boolean;
 }
 
 export interface IStyledKitAvatar {
     $theme: IKitAvatarTheme;
-    $color: KitAvatarColorType;
+    $iconColor: string;
+    $backgroundColor: string;
 }
 
 export interface IKitAvatarGroup

package/dist/Kit/DataDisplay/Badge/types.d.ts

@@ -2,17 +2,18 @@ import {BadgeProps} from 'antd';
 import {KitHTMLAttributes} from '../../../types';
 import {IKitBadgeTheme} from '@theme/types/components/DataDisplay/Badge';
 import {IKitTypography} from '@theme/types/general/typography';
+import {KitColorProp} from '@utils/functions/types';
 
 type AntdBadgeTypesToOmit = 'color' | 'size' | 'offset' | 'text';
 
-export type KitBadgeCountColor = 'default' | 'green' | 'blue' | 'blueInvert' | 'gray';
-
 export interface IKitBadge extends Omit<BadgeProps, AntdBadgeTypesToOmit>, KitHTMLAttributes<HTMLDivElement> {
-    countColor?: KitBadgeCountColor;
+    color?: KitColorProp;
+    secondaryColorInvert?: boolean;
 }
 
 export interface IStyledKitBadge {
     $theme: IKitBadgeTheme;
     $typographyTheme: IKitTypography;
-    $countColor: KitBadgeCountColor;
+    $backgroundColor: string;
+    $fontColor: string;
 }

package/dist/Kit/DataDisplay/Card/types.d.ts

@@ -17,7 +17,6 @@ export default interface IKitCard extends Omit<CardProps, AntdCardTypesToOmit> {
     disabled?: boolean;
     contentTitle?: string;
     contentDescription?: string;
-    sideSpacing?: boolean;
     separator?: boolean;
     onContentTitleClick?: () => void;
 }
@@ -25,7 +24,6 @@ export default interface IKitCard extends Omit<CardProps, AntdCardTypesToOmit> {
 export interface IStyledKitCard {
     $theme: IKitCardTheme;
     $disabled: boolean;
-    $sideSpacing: boolean;
     $separator: boolean;
 }
 

package/dist/Kit/DataDisplay/ItemCard/types.d.ts

@@ -1,5 +1,5 @@
 import {KitHTMLAttributes} from '../../../types';
-import {IKitTag} from '../../DataEntry/Tag/types';
+import {IKitTag} from '../Tag/types';
 import {ReactNode, MouseEvent} from 'react';
 import {CheckboxChangeEvent} from 'antd/lib/checkbox';
 import {IKitItemCardTheme} from '@theme/types/components/DataDisplay/ItemCard';

package/dist/Kit/DataDisplay/ItemList/types.d.ts

@@ -12,6 +12,7 @@ export interface IKitItemList extends KitHTMLAttributes<HTMLDivElement> {
     onRafterClick?: Function;
     disabled?: boolean;
     onClick?: Function;
+    disableSecureClick?: boolean;
 }
 
 export interface IStyledKitItemList {

package/dist/Kit/{DataEntry → DataDisplay}/Tag/types.d.ts

@@ -1,19 +1,20 @@
 import {TagProps} from 'antd';
 import {KitHTMLAttributes} from '../../../types';
 import {ReactNode} from 'react';
-import {IKitTagTheme} from '@theme/types/components/DataEntry/Tag';
+import {IKitTagTheme} from '@theme/types/components/DataDisplay/Tag';
+import {KitColorProp} from '@utils/functions/types';
 
 export type AntdTagPropsToOmit = 'color' | 'checkableTag' | 'icon' | 'closable';
 
-export type KitTagColor = 'red' | 'green' | 'blue' | 'blueInvert' | 'default';
-
 export interface IKitTag extends Omit<TagProps, AntdTagPropsToOmit>, KitHTMLAttributes<HTMLSpanElement> {
-    color?: KitTagColor;
+    color?: KitColorProp;
+    secondaryColorInvert?: boolean;
     children?: ReactNode[] | ReactNode;
     onClose?: TagProps['onClose'];
 }
 
 export interface IStyledAntdTag {
     $theme: IKitTagTheme;
-    $color: KitTagColor;
+    $color?: string;
+    $backgroundColor?: string;
 }

package/dist/Kit/DataDisplay/Tour/index.d.ts

@@ -0,0 +1,3 @@
+import { FunctionComponent } from 'react';
+import { IKitTour } from './types';
+export declare const KitTour: FunctionComponent<IKitTour>;

package/dist/Kit/DataDisplay/Tour/style.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="react" />
+import { IStyledAntdTour } from './types';
+export declare const TourStyle: import("react").NamedExoticComponent<import("styled-components").ExecutionProps & IStyledAntdTour>;

package/dist/Kit/DataDisplay/Tour/types.d.ts

@@ -0,0 +1,12 @@
+import {IKitThemeGeneral} from '@theme/types';
+import {IKitButtonTheme} from '@theme/types/components/General/Button';
+import {TourProps} from 'antd';
+
+type AntdTourTypesToOmit = '';
+
+export interface IKitTour extends Omit<TourProps, AntdTourTypesToOmit> {}
+
+export interface IStyledAntdTour {
+    $buttonTheme: IKitButtonTheme;
+    $generalTheme: IKitThemeGeneral;
+}

package/dist/Kit/DataDisplay/index.d.ts

@@ -8,3 +8,5 @@ export { KitItemList } from './ItemList';
 export { KitTooltip } from './Tooltip';
 export { KitTree } from './Tree';
 export { KitTabs } from './Tabs';
+export { KitTag } from './Tag';
+export { KitTour } from './Tour';