@agregio-solutions/design-system 1.90.1 → 1.92.0

package/dist/packages/components/Header/doc.md

@@ -0,0 +1,373 @@
+# Header
+
+## Props
+
+The complete Props documentation with JS doc for this component is available at this path:
+
+node_modules/@agregio-solutions/design-system/dist/packages/components/Header/Header.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { fn, within } from "storybook/test";
+import { STORYBOOK_VIEWPORTS } from "@internal/test-utils-storybook/test-utils-storybook";
+import Header from "./Header";
+import Tag from "../Tag/Tag";
+import { I18nProvider } from "react-aria-components";
+import Breadcrumbs from "../Breadcrumbs/Breadcrumbs";
+import Button from "../Button/Button";
+import Select from "../Select/Select";
+import SelectItem from "../SelectItem/SelectItem";
+import Tabs from "../Tabs/Tabs/Tabs";
+import Tab from "../Tabs/Tab/Tab";
+import TabList from "../Tabs/TabList/TabList";
+import TabPanel from "../Tabs/TabPanel/TabPanel";
+import styled from "styled-components";
+
+const meta = {
+  component: Header,
+  argTypes: {
+    subtitle: { control: "text" },
+    tagComponent: { control: false },
+    onGoBack: { control: false },
+    breadcrumbsComponent: { control: false },
+    helperIconComponent: { control: false },
+    notificationIconComponent: { control: false },
+    additionalActions: { control: false },
+    tabsComponent: { control: false },
+  },
+  parameters: {
+    layout: "none",
+  },
+  args: {
+    onGoBack: fn(),
+  },
+  decorators: [
+    (story) => (
+      <div
+        style={{ display: "flex", flexDirection: "column", height: "100vh" }}
+      >
+        <I18nProvider locale="en-EN">{story()}</I18nProvider>
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof Header>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const StyledTabPanel = styled(TabPanel)`
+  flex: 1;
+  padding: var(--spacing-lg);
+  background-color: var(--color-background-neutral-underground-1);
+`;
+
+export const Playground: Story = {
+  args: {
+    title: "Insert title",
+    subtitle: "Insert subtitle",
+    tagComponent: <Tag iconLeft="help_outline">[Insert tag]</Tag>,
+    logo: "agregio",
+    onGoBack: fn(),
+    breadcrumbsComponent: (
+      <Breadcrumbs
+        links={[
+          { href: "#link-1", text: "Link 1" },
+          { href: "#link-2", text: "Link 2" },
+          { href: "#link-3", text: "Link 3" },
+        ]}
+      />
+    ),
+    helperIconComponent: (
+      <Button
+        iconLeft="help_outline"
+        onClick={() => alert("Help")}
+        mode="tertiary"
+      />
+    ),
+    notificationIconComponent: (
+      <Button
+        iconLeft="notifications_none"
+        onClick={() => alert("Notifications")}
+        mode="tertiary"
+      />
+    ),
+    additionalActions: (
+      <Select
+        mode="single"
+        id="select"
+        aria-label="Select"
+        value={null}
+        onChange={fn()}
+        placeholder="Select"
+      >
+        <SelectItem id="select-item-1" text="Item 1" />
+        <SelectItem id="select-item-2" text="Item 2" />
+        <SelectItem id="select-item-3" text="Item 3" />
+      </Select>
+    ),
+    tabsComponent: (
+      <Tabs>
+        <TabList>
+          <Tab id="tab-1">Tab 1</Tab>
+          <Tab id="tab-2" badgeProps={{ nature: "negative", variant: "dot" }}>
+            Tab 2
+          </Tab>
+          <Tab id="tab-3" badgeProps={{ variant: "dot", nature: "positive" }}>
+            Tab 3
+          </Tab>
+        </TabList>
+
+        {/* StyledPanel is a TabPanel with styled: `flex: 1; padding: var(--spacing-lg); background-color: var(--color-background-neutral-underground-1);` */}
+        {/* You need to create it on your side if you want those styles, or just use a TabPanel component directly */}
+        <StyledTabPanel id="tab-1">Content for the panel 1</StyledTabPanel>
+        <StyledTabPanel id="tab-2">Content for the panel 2</StyledTabPanel>
+        <StyledTabPanel id="tab-3">Content for the panel 3</StyledTabPanel>
+      </Tabs>
+    ),
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText(args.title);
+    await canvas.findByText(args.subtitle as string);
+    await canvas.findByText("[Insert tag]");
+  },
+};
+
+export const WithoutSubtitle: Story = {
+  args: {
+    ...Playground.args,
+    subtitle: undefined,
+  },
+};
+
+export const WithoutTag: Story = {
+  args: {
+    ...Playground.args,
+    tagComponent: undefined,
+  },
+};
+
+export const WithoutGoBack: Story = {
+  args: {
+    ...Playground.args,
+    onGoBack: undefined,
+  },
+};
+
+export const WithoutBreadcrumbs: Story = {
+  args: {
+    ...Playground.args,
+    breadcrumbsComponent: undefined,
+  },
+};
+
+export const WithoutHelperIcon: Story = {
+  args: {
+    ...Playground.args,
+    helperIconComponent: undefined,
+  },
+};
+
+export const WithoutNotificationIcon: Story = {
+  args: {
+    ...Playground.args,
+    notificationIconComponent: undefined,
+  },
+};
+
+export const WithoutadditionalActions: Story = {
+  args: {
+    ...Playground.args,
+    additionalActions: undefined,
+  },
+};
+
+export const WithoutTabs: Story = {
+  args: {
+    ...Playground.args,
+    tabsComponent: undefined,
+  },
+};
+
+export const WithoutSubtitleAndTag: Story = {
+  args: {
+    ...Playground.args,
+    subtitle: undefined,
+    tagComponent: undefined,
+  },
+};
+
+export const Mobile: Story = {
+  parameters: {
+    ...STORYBOOK_VIEWPORTS,
+    layout: "none",
+  },
+  globals: {
+    viewport: { value: "iphone6", isRotated: false },
+  },
+  args: {
+    ...Playground.args,
+  },
+};
+```
+
+## How to test this component
+
+Here are some more advanced stories with more testing coverage and examples that you can read to understand how to test this component.
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, within } from "storybook/test";
+import Header from "../Header";
+import Tag from "../../Tag/Tag";
+import Breadcrumbs from "../../Breadcrumbs/Breadcrumbs";
+import Button from "../../Button/Button";
+import Select from "../../Select/Select";
+import SelectItem from "../../SelectItem/SelectItem";
+import Tabs from "../../Tabs/Tabs/Tabs";
+import Tab from "../../Tabs/Tab/Tab";
+import TabList from "../../Tabs/TabList/TabList";
+import TabPanel from "../../Tabs/TabPanel/TabPanel";
+import styled from "styled-components";
+import * as HeaderMainStory from "../Header.stories";
+
+const meta: Meta<typeof Header> = {
+  ...HeaderMainStory.default,
+  component: Header,
+  parameters: {
+    ...HeaderMainStory.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const StyledTabPanel = styled(TabPanel)`
+  flex: 1;
+  padding: var(--spacing-lg);
+  background-color: var(--color-background-neutral-underground-1);
+`;
+
+export const FullFeatured: Story = {
+  render: () => (
+    <Header
+      title="Insert title"
+      subtitle="Insert subtitle"
+      tagComponent={<Tag iconLeft="help_outline">[Insert tag]</Tag>}
+      onGoBack={fn()}
+      breadcrumbsComponent={
+        <Breadcrumbs
+          links={[
+            { href: "#link-1", text: "Link 1" },
+            { href: "#link-2", text: "Link 2" },
+            { href: "#link-3", text: "Link 3" },
+          ]}
+        />
+      }
+      helperIconComponent={
+        <Button
+          iconLeft="help_outline"
+          onClick={() => alert("Help")}
+          mode="tertiary"
+        />
+      }
+      notificationIconComponent={
+        <Button
+          iconLeft="notifications_none"
+          onClick={() => alert("Notifications")}
+          mode="tertiary"
+        />
+      }
+      additionalActions={
+        <Select
+          mode="single"
+          id="select"
+          aria-label="Select"
+          value={null}
+          onChange={fn()}
+          placeholder="Select"
+        >
+          <SelectItem id="select-item-1" text="Item 1" />
+          <SelectItem id="select-item-2" text="Item 2" />
+          <SelectItem id="select-item-3" text="Item 3" />
+        </Select>
+      }
+      tabsComponent={
+        <Tabs>
+          <TabList>
+            <Tab id="tab-1">Tab 1</Tab>
+            <Tab id="tab-2" badgeProps={{ nature: "negative", variant: "dot" }}>
+              Tab 2
+            </Tab>
+            <Tab id="tab-3" badgeProps={{ nature: "negative", variant: "dot" }}>
+              Tab 3
+            </Tab>
+          </TabList>
+
+          {/* StyledPanel is a TabPanel with styled: `flex: 1; padding: var(--spacing-lg); background-color: var(--color-background-neutral-underground-1);` */}
+          {/* You need to create it on your side if you want those styles, or just use a TabPanel component directly */}
+          <StyledTabPanel id="tab-1">Content for the panel 1</StyledTabPanel>
+          <StyledTabPanel id="tab-2">Content for the panel 2</StyledTabPanel>
+          <StyledTabPanel id="tab-3">Content for the panel 3</StyledTabPanel>
+        </Tabs>
+      }
+    />
+  ),
+};
+
+export const ShouldCallOnGoBack: Story = {
+  args: {
+    ...HeaderMainStory.Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await user.click(canvas.getByLabelText("Go back"));
+    await expect(args.onGoBack).toHaveBeenCalledTimes(1);
+  },
+};
+```
+
+## Developer notes
+
+Here are the notes available for the developer on the built Storybook, you can read them to understand the component and how to use it.
+
+```mdx
+import {
+  Canvas,
+  Meta,
+  Stories,
+  Controls,
+  Source,
+} from "@storybook/addon-docs/blocks";
+
+import * as Header from "./Header.stories";
+import * as HeaderTests from "./tests/Header.stories";
+
+<Meta of={Header} />
+
+# Header
+
+<Canvas of={Header.Playground} />
+
+## Usage
+
+This component does not provide any feature, it's just a wrapper that lets you put the required elements and handle their positioning.
+
+Here is a good starting point that handles the most common use cases:
+
+<Source of={HeaderTests.FullFeatured} type="code" dark />
+
+## Props
+
+<Controls of={Header.Playground} />
+
+<Stories />
+```

package/dist/packages/components/I18nProvider/doc.md

@@ -0,0 +1,187 @@
+# I18nProvider
+
+## Props
+
+The complete Props documentation with JS doc for this component is available at this path:
+
+node_modules/@agregio-solutions/design-system/dist/packages/components/I18nProvider/I18nProvider.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { I18nProvider as AriaI18nProvider } from "react-aria";
+import { fn, within } from "storybook/test";
+import Chip from "@components/Chip/Chip";
+import React from "react";
+import Select from "@components/Select/Select";
+import SelectItem from "@components/SelectItem/SelectItem";
+import { useController, useForm } from "react-hook-form";
+
+// Wrapper necessary for Storybook source code parsing
+function I18nProvider({
+  locale,
+  children,
+}: {
+  locale: string;
+  children: React.ReactNode;
+}) {
+  return <AriaI18nProvider locale={locale}>{children}</AriaI18nProvider>;
+}
+
+const meta: Meta<typeof I18nProvider> = {
+  component: I18nProvider,
+  argTypes: {
+    locale: {
+      options: ["en-US", "fr-FR"],
+      control: { type: "radio" },
+    },
+    children: { control: false },
+  },
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+export const ChipFR: StoryObj<typeof I18nProvider> = {
+  args: {
+    locale: "fr-FR",
+    children: <Chip value="Item" onClose={fn()} />,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByLabelText("Fermer Item");
+  },
+};
+
+export const ChipEN: StoryObj<typeof I18nProvider> = {
+  args: {
+    locale: "en-US",
+    children: <Chip value="Item" onClose={fn()} />,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByLabelText("Close Item");
+  },
+};
+
+const SelectExample = () => {
+  const { control } = useForm<any>({
+    defaultValues: {
+      select: ["1", "2"],
+    },
+  });
+  const selectField = useController({ control, name: "select" });
+
+  return (
+    <>
+      <div style={{ marginBottom: 16 }}>
+        Selected values : {selectField.field.value.join(", ")}
+      </div>
+
+      <Select
+        id="my-select"
+        label="[Insert label]"
+        selectedKeys={selectField.field.value}
+        onSelectionChange={selectField.field.onChange}
+        mode="multiple"
+        placeholder="Please select an option"
+      >
+        <SelectItem text="Option 1" id="1" />
+        <SelectItem text="Option 2" id="2" />
+        <SelectItem text="Option 3" id="3" />
+      </Select>
+    </>
+  );
+};
+
+export const SelectMultipletEN: StoryObj<typeof I18nProvider> = {
+  args: {
+    locale: "en-US",
+    children: <SelectExample />,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("items selected");
+  },
+};
+
+export const SelectMultipletFR: StoryObj<typeof I18nProvider> = {
+  args: {
+    locale: "fr-FR",
+    children: <SelectExample />,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("éléments sélectionnés");
+  },
+};
+```
+
+## Developer notes
+
+Here are the notes available for the developer on the built Storybook, you can read them to understand the component and how to use it.
+
+````mdx
+import { Meta, Canvas, Controls, Stories } from "@storybook/addon-docs/blocks";
+
+import * as I18nProvider from "./I18nProvider.stories";
+
+<Meta of={I18nProvider} />
+
+# I18nProvider
+
+<Canvas of={I18nProvider.ChipFR} />
+
+## I18nProvider props
+
+<Controls of={I18nProvider.ChipEN} />
+
+## Purpose
+
+**TL;DR: `I18nProvider` allows you to tell the Design System components in which language they should display their hard-coded text. It does not replace an i18n solution on your side.**
+
+Most of the text that can be displayed inside the Design System components is handled by the dev that adds it in a front-end project (i.e. you).
+
+The Design System component will then display them exactly as you provided them. So it is your responsibility to handle translation in the languages needed for you users.
+
+**But, the Design System also has some text that is not controlled by you**. At 2 levels:
+
+- short hard coded texts that are part a component's logic (like the character counter in the text input)
+- invisible texts that are added for screen readers by React Aria
+
+By default, those texts will be translated depending on the language set in the browser.
+But you can force the displayed language using the `I18nProvider` component as a global Provider.
+
+Use it like any other global provider you may have (you only need it once for the whole project):
+
+```tsx
+import { I18nProvider } from "@agregio-solutions/design-system";
+
+<I18nProvider lang="fr-FR">
+  <App />
+</I18nProvider>;
+```
+
+## Available languages
+
+For now, the Design System only supports **English** and **French**.
+
+If you need another language, please contact the Design System team, we will add it for you!
+
+## SSR hydration mismatch errors
+
+If you are using Server Side Rendering (SSR), then you should use the `I18nProvider` to avoid hydration mismatches.
+
+The reason is simple, the server locale and the client locale may not match. Forcing the locale with the `I18nProvider` will ensure that the locale is the same on the server and the client.
+
+## Stories (list all components that display translated text to users)
+
+<Stories of={I18nProvider} />
+````

package/dist/packages/components/Icon/doc.md

@@ -0,0 +1,63 @@
+# Icon
+
+## Props
+
+The complete Props documentation with JS doc for this component is available at this path:
+
+node_modules/@agregio-solutions/design-system/dist/packages/components/Icon/Icon.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Icon from "./Icon";
+
+const meta: Meta<typeof Icon> = {
+  component: Icon,
+  parameters: {
+    layout: "centered",
+  },
+};
+export default meta;
+
+export const Playground: StoryObj<typeof Icon> = {
+  args: {
+    name: "star",
+    style: {
+      color: "var(--color-content-action-action)",
+      fontSize: 30,
+    },
+  },
+};
+```
+
+## Developer notes
+
+Here are the notes available for the developer on the built Storybook, you can read them to understand the component and how to use it.
+
+```mdx
+import { Meta, IconGallery, IconItem } from "@storybook/addon-docs/blocks";
+import * as IconStories from "./Icon.stories";
+import Icon, { ICON_NAMES_ARRAY } from "./Icon";
+
+<Meta of={IconStories} />
+
+# List of available icons
+
+Here is a list of all available icons:
+
+<IconGallery>
+  {ICON_NAMES_ARRAY.map((name) => (
+    <IconItem key={name} name={name}>
+      <Icon
+        name={name}
+        style={{ color: "var(--color-content-action-action)" }}
+      />
+    </IconItem>
+  ))}
+</IconGallery>
+```

package/dist/packages/components/Label/doc.md

@@ -0,0 +1,60 @@
+# Label
+
+## Props
+
+The complete Props documentation with JS doc for this component is available at this path:
+
+node_modules/@agregio-solutions/design-system/dist/packages/components/Label/Label.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { within } from "storybook/test";
+
+import Label from "./Label";
+
+const meta: Meta<typeof Label> = {
+  component: Label,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+export const WithIconTooltip: StoryObj<typeof Label> = {
+  args: {
+    htmlForId: "input",
+    label: "[Insert label]",
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "This field requires a specific format",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("[Insert label]");
+    await canvas.findByRole("button", {
+      name: "This field requires a specific format",
+    });
+  },
+};
+
+export const Playground: StoryObj<typeof Label> = {
+  args: {
+    htmlForId: "input",
+    label: "[Insert label]",
+    labelIconRight: "help_outline",
+    required: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByTitle("Required");
+    await canvas.findByText("[Insert label]");
+  },
+};
+```