@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,504 @@
+# SearchBar
+
+## 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/SearchBar/SearchBar.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { userEvent, within } from "storybook/test";
+import SearchBar from "./SearchBar";
+import { useState } from "react";
+import Button from "@components/Button/Button";
+import List, { Props as ListProps } from "../List/List";
+import EmptyState from "../EmptyState/EmptyState";
+import Tabs from "../Tabs/Tabs/Tabs";
+import TabList from "../Tabs/TabList/TabList";
+import Tab from "../Tabs/Tab/Tab";
+import TabPanel from "../Tabs/TabPanel/TabPanel";
+import { I18nProvider } from "react-aria-components";
+
+const meta: Meta<typeof SearchBar> = {
+  component: SearchBar,
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const ExampleUsage: Story = {
+  render: () => {
+    // Data, typically fetched from a database
+    const data = [
+      {
+        id: "id-1",
+        fullname: "Alice Johnson",
+        position: "Chief Executive Officer",
+      },
+      {
+        id: "id-2",
+        fullname: "Bob Smith",
+        position: "Lead Software Engineer",
+      },
+      {
+        id: "id-3",
+        fullname: "Carol Lee",
+        position: "Product Manager",
+      },
+      {
+        id: "id-4",
+        fullname: "David Kim",
+        position: "UX Designer",
+      },
+      {
+        id: "id-5",
+        fullname: "Eva Brown",
+        position: "HR Specialist",
+      },
+    ];
+
+    const Parent = () => {
+      const [searchValue, setSearchValue] = useState("");
+      const [isOpen, setIsOpen] = useState(false);
+
+      // Manually filter the data based on the search value (have to be done on your side, not handled by the component)
+      const filteredData = data.filter((item) => {
+        if (!searchValue) return false; // Case where we want to show nothing if there is no search value
+        const searchValueLower = searchValue.toLowerCase();
+        return (
+          item.fullname.toLowerCase().includes(searchValueLower) ||
+          item.position.toLowerCase().includes(searchValueLower) ||
+          item.id.toLowerCase() === searchValueLower // It is recommended to use an exact match for the id, as it is used to identify the item in the list.
+        );
+      });
+
+      return (
+        <div>
+          <Button onClick={() => setIsOpen(true)} text="Open" />
+
+          <SearchBar
+            inputProps={{
+              value: searchValue,
+              onChange: setSearchValue,
+              placeholder: "Search in the application",
+            }}
+            onClear={() => setSearchValue("")}
+            isOpen={isOpen}
+            onOpenChange={(newIsOpen) => {
+              setSearchValue(""); // Reset the search value when the modal is closed. This is not built-in, so you have the choice depending on your use case.
+              setIsOpen(newIsOpen);
+            }}
+            resultsCount={filteredData.length}
+          >
+            {!!searchValue && ( // Only render the list if there is a search value
+              <List
+                aria-label="Search results"
+                sections={[
+                  {
+                    id: "people",
+                    items: filteredData.map((item) => ({
+                      id: item.id,
+                      title: item.fullname,
+                      subtitle: item.position,
+                      href: `https://www.google.com?q=${item.fullname}`,
+                      target: "_blank",
+                    })),
+                  },
+                ]}
+                renderEmptyState={() => (
+                  <EmptyState
+                    title="No results"
+                    description="No results found"
+                    icon={"help_outline"}
+                  >
+                    <Button
+                      text="Clear search"
+                      onClick={() => setSearchValue("")}
+                      mode="secondary"
+                    />
+                    <Button text="Close" onClick={() => setIsOpen(false)} />
+                  </EmptyState>
+                )}
+              />
+            )}
+          </SearchBar>
+        </div>
+      );
+    };
+    return <Parent />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup();
+    await user.click(canvas.getByText("Open"));
+    await canvas.findByPlaceholderText("Search in the application");
+  },
+};
+
+export const WithTabs: Story = {
+  render: () => {
+    // Data, typically fetched from a database
+    const users = [
+      {
+        id: "user-id-1",
+        fullname: "Alice Johnson",
+        position: "Chief Executive Officer",
+      },
+      {
+        id: "user-id-2",
+        fullname: "Bob Smith",
+        position: "Lead Software Engineer",
+      },
+      {
+        id: "user-id-3",
+        fullname: "Carol Lee",
+        position: "Product Manager",
+      },
+    ];
+
+    const companies = [
+      {
+        id: "company-id-1",
+        name: "Agregio Solutions",
+      },
+      {
+        id: "company-id-2",
+        name: "EDF Store and Forecast",
+      },
+      {
+        id: "company-id-3",
+        name: "Dalkia",
+      },
+    ];
+
+    const Empty = ({
+      setSearchValue,
+      setIsOpen,
+    }: {
+      setSearchValue: (value: string) => void;
+      setIsOpen: (value: boolean) => void;
+    }) => {
+      return (
+        <EmptyState
+          title="No results"
+          description="No results found"
+          icon={"help_outline"}
+        >
+          <Button
+            text="Clear search"
+            onClick={() => setSearchValue("")}
+            mode="secondary"
+          />
+          <Button text="Close" onClick={() => setIsOpen(false)} />
+        </EmptyState>
+      );
+    };
+
+    const Parent = () => {
+      const [searchValue, setSearchValue] = useState("");
+      const [isOpen, setIsOpen] = useState(false);
+
+      // Manually filter the data based on the search value (have to be done on your side, not handled by the component)
+      const filteredUsers = users.filter((user) => {
+        // Here we do not return an empty array if there is no search value, this is an example of how you can show all the data by default on SearchBar opening.
+        const searchValueLower = searchValue.toLowerCase();
+        return (
+          user.fullname.toLowerCase().includes(searchValueLower) ||
+          user.position.toLowerCase().includes(searchValueLower) ||
+          user.id.toLowerCase() === searchValueLower
+        );
+      });
+
+      const filteredCompanies = companies.filter((company) => {
+        const searchValueLower = searchValue.toLowerCase();
+        return (
+          company.name.toLowerCase().includes(searchValueLower) ||
+          company.id.toLowerCase() === searchValueLower
+        );
+      });
+
+      const sections: ListProps["sections"] = [
+        {
+          id: "users",
+          title: "Users",
+          items: filteredUsers.map((user) => ({
+            id: user.id,
+            title: user.fullname,
+            subtitle: user.position,
+            href: `https://www.google.com?q=${user.fullname}`,
+            target: "_blank",
+          })),
+        },
+        {
+          id: "companies",
+          title: "Companies",
+          items: filteredCompanies.map((company) => ({
+            id: company.id,
+            title: company.name,
+            icon: "business",
+          })),
+        },
+      ];
+
+      return (
+        <div>
+          <Button onClick={() => setIsOpen(true)} text="Open" />
+
+          <SearchBar
+            inputProps={{
+              value: searchValue,
+              onChange: setSearchValue,
+              placeholder: "Search in the application",
+            }}
+            onClear={() => setSearchValue("")}
+            isOpen={isOpen}
+            onOpenChange={(newIsOpen) => {
+              setSearchValue(""); // Reset the search value when the modal is closed. This is not built-in, so you have the choice depending on your use case.
+              setIsOpen(newIsOpen);
+            }}
+            resultsCount={filteredUsers.length + filteredCompanies.length}
+          >
+            <Tabs>
+              <TabList>
+                <Tab id="all">All</Tab>
+                <Tab id="users">Users</Tab>
+                <Tab id="companies">Companies</Tab>
+              </TabList>
+              <TabPanel id="all">
+                <List
+                  aria-label="All search results"
+                  sections={sections}
+                  renderEmptyState={() => (
+                    <Empty
+                      setSearchValue={setSearchValue}
+                      setIsOpen={setIsOpen}
+                    />
+                  )}
+                />
+              </TabPanel>
+              <TabPanel id="users">
+                <List
+                  aria-label="Users search results"
+                  sections={sections.filter(
+                    (section) => section.id === "users",
+                  )}
+                  renderEmptyState={() => (
+                    <Empty
+                      setSearchValue={setSearchValue}
+                      setIsOpen={setIsOpen}
+                    />
+                  )}
+                />
+              </TabPanel>
+              <TabPanel id="companies">
+                <List
+                  aria-label="Companies search results"
+                  sections={sections.filter(
+                    (section) => section.id === "companies",
+                  )}
+                  renderEmptyState={() => (
+                    <Empty
+                      setSearchValue={setSearchValue}
+                      setIsOpen={setIsOpen}
+                    />
+                  )}
+                />
+              </TabPanel>
+            </Tabs>
+          </SearchBar>
+        </div>
+      );
+    };
+    return <Parent />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup();
+    await user.click(canvas.getByText("Open"));
+  },
+};
+
+export const NoResultsEmptyState: Story = {
+  render: () => {
+    const Parent = () => {
+      const [searchValue, setSearchValue] = useState("Some search value");
+      const [isOpen, setIsOpen] = useState(false);
+
+      return (
+        <div>
+          <Button onClick={() => setIsOpen(true)} text="Open" />
+
+          <SearchBar
+            inputProps={{
+              value: searchValue,
+              onChange: setSearchValue,
+              placeholder: "Search in the application",
+            }}
+            onClear={() => setSearchValue("")}
+            isOpen={isOpen}
+            onOpenChange={(newIsOpen) => {
+              setSearchValue(""); // Reset the search value when the modal is closed. This is not built-in, so you have the choice depending on your use case.
+              setIsOpen(newIsOpen);
+            }}
+            resultsCount={0}
+          >
+            {/* Here we want to display all the data by default */}
+            <List
+              aria-label="Search results"
+              sections={[]}
+              renderEmptyState={() => (
+                <EmptyState
+                  title="No results"
+                  description="No results found"
+                  icon={"help_outline"}
+                >
+                  <Button
+                    text="Clear search"
+                    onClick={() => setSearchValue("")}
+                    mode="secondary"
+                  />
+                  <Button text="Close" onClick={() => setIsOpen(false)} />
+                </EmptyState>
+              )}
+            />
+          </SearchBar>
+        </div>
+      );
+    };
+    return <Parent />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup();
+    await user.click(canvas.getByText("Open"));
+  },
+};
+```
+
+## 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, userEvent, within } from "storybook/test";
+import SearchBar from "../SearchBar";
+import * as SearchBarStories from "../SearchBar.stories";
+
+const meta: Meta<typeof SearchBar> = {
+  ...SearchBarStories.default,
+  component: SearchBar,
+  parameters: {
+    ...SearchBarStories.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const ShouldShowTheFilteredItems: Story = {
+  render: SearchBarStories.ExampleUsage.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup({ delay: 25 });
+    await user.click(canvas.getByText("Open"));
+
+    const input = await canvas.findByPlaceholderText(
+      "Search in the application",
+    );
+
+    // Check that items are not displayed yet
+    await expect(canvas.queryByText(/result/i)).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Alice Johnson")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Bob Smith")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Carol Lee")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("David Kim")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Eva Brown")).not.toBeInTheDocument();
+
+    // Check that the legend is not displayed
+    await expect(canvas.queryByText("Navigation")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Choose")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Close")).not.toBeInTheDocument();
+
+    // Type "Alice" in the search bar
+    await user.type(input, "Alice");
+
+    // Check that items are displayed
+    await canvas.findByText("1 result");
+    await canvas.findByText("Alice Johnson");
+    await expect(canvas.queryByText("Bob Smith")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Carol Lee")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("David Kim")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Eva Brown")).not.toBeInTheDocument();
+    await canvas.findByText("Navigation");
+    await canvas.findByText("Choose");
+    await canvas.findByText("Close");
+
+    // Clear the search bar
+    await user.click(canvas.getByLabelText("Clear"));
+    await expect(input).toHaveValue("");
+    await expect(canvas.queryByText(/result/i)).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Alice Johnson")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Bob Smith")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Carol Lee")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("David Kim")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Eva Brown")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Navigation")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Choose")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Close")).not.toBeInTheDocument();
+  },
+};
+```
+
+## 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, Controls, Source, Canvas } from "@storybook/addon-docs/blocks";
+
+import * as SearchBar from "./SearchBar.stories";
+
+<Meta of={SearchBar} />
+
+# SearchBar
+
+<Canvas of={SearchBar.ExampleUsage} />
+<Controls of={SearchBar.ExampleUsage} />
+
+## Basic example usage
+
+Below you can find a basic example usage of the SearchBar component.
+You will find that there is a lot of customization and flexibility, some UX aspects can totally be decided on your side.
+
+For example, here we choose to not display items if there is no search value in the input. Feel free to change this behavior to your needs.
+
+Also, the filtering is done on your side, so you can decide all the aspects of this feature (like which keys to filter on, how to filter them, add fuzzy search, etc.).
+Even if there is no example usage for this use case, it should be really easy to implement a back-end filtering as well, based on the search value.
+
+Click on "Show code" to see the code.
+
+<Canvas of={SearchBar.ExampleUsage} />
+
+### With tabs example usage
+
+Here is another example where we use tabs to display different types of items.
+Some of the UX decisions voluntary differ from the basic example usage, so you can see how easy it is to customize the component to your needs (i.e. here we display results even if there is no search value in the input).
+
+<Canvas of={SearchBar.WithTabs} />
+```