@usefui/components 1.5.1

package/src/accordion/Accordion.stories.tsx

@@ -0,0 +1,89 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Accordion } from "..";
+import { ComponentSizeEnum, ComponentVariantEnum } from "../../../../types";
+
+const meta = {
+  title: "Components/Accordion",
+  component: Accordion,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="m-medium-30">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof Accordion>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+export const Default = {
+  args: {
+    value: "",
+  },
+  argTypes: {
+    spacing: {
+      options: [
+        ComponentSizeEnum.Small,
+        ComponentSizeEnum.Medium,
+        ComponentSizeEnum.Large,
+      ],
+      control: { type: "radio" },
+    },
+    variant: {
+      options: [
+        ComponentVariantEnum.Primary,
+        ComponentVariantEnum.Secondary,
+        ComponentVariantEnum.Tertiary,
+        ComponentVariantEnum.Mono,
+        ComponentVariantEnum.Border,
+        ComponentVariantEnum.Ghost,
+      ],
+      control: { type: "radio" },
+    },
+    sizing: {
+      options: [
+        ComponentSizeEnum.Small,
+        ComponentSizeEnum.Medium,
+        ComponentSizeEnum.Large,
+      ],
+      control: { type: "radio" },
+    },
+  },
+  render: ({ ...args }) => (
+    <Accordion.Root>
+      <Accordion>
+        <Accordion.Trigger value="demo">🐻‍❄️</Accordion.Trigger>
+        <Accordion.Content value="demo">🐻🐻‍❄️🦊🐱🐶</Accordion.Content>
+      </Accordion>
+    </Accordion.Root>
+  ),
+};
+export const DefaultOpen: Story = {
+  render: ({ ...args }) => (
+    <Accordion.Root>
+      <Accordion>
+        <Accordion.Trigger value="demo">🐻</Accordion.Trigger>
+        <Accordion.Content value="demo" defaultOpen>
+          🐻🐻‍❄️🦊🐱🐶
+        </Accordion.Content>
+      </Accordion>
+    </Accordion.Root>
+  ),
+};
+export const Group: Story = {
+  render: ({ ...args }) => (
+    <React.Fragment>
+      {["🐻", "🐻‍❄️", "🦊", "🐱", "🐶"].map((item) => (
+        <Accordion.Root key={item}>
+          <Accordion className="m-b-medium-30">
+            <Accordion.Trigger value={item}>{item}</Accordion.Trigger>
+            <Accordion.Content value={item}>{item}</Accordion.Content>
+          </Accordion>
+        </Accordion.Root>
+      ))}
+    </React.Fragment>
+  ),
+};

package/src/accordion/hooks/index.tsx

@@ -0,0 +1,39 @@
+import React, { useState, createContext, useContext } from "react";
+import { IReactChildren, IComponentAPI } from "../../../../../types";
+
+const defaultComponentAPI = {
+  id: "",
+  states: {},
+  methods: {},
+};
+const AccordionContext = createContext<IComponentAPI>(defaultComponentAPI);
+export const useAccordion = () => useContext(AccordionContext);
+
+export const AccordionProvider = ({
+  children,
+}: IReactChildren): JSX.Element => {
+  const context = useAccordionProvider();
+
+  return (
+    <AccordionContext.Provider value={context}>
+      {children}
+    </AccordionContext.Provider>
+  );
+};
+
+function useAccordionProvider(): IComponentAPI {
+  const [value, setValue] = useState<string | null>(null);
+  const accordionId = React.useId();
+
+  return {
+    id: accordionId,
+    states: {
+      value,
+    },
+    methods: {
+      applyValue: (value: string): string | void => setValue(value),
+      getAccordionId: ({ value, type }: Record<string, string>): string =>
+        `${accordionId}-${type}-${value}`,
+    },
+  };
+}

package/src/accordion/index.tsx

@@ -0,0 +1,170 @@
+"use client";
+
+import React from "react";
+import { AccordionProvider, useAccordion } from "./hooks";
+import { Button, IButtonProperties } from "../button";
+
+import {
+  IReactChildren,
+  IComponentSpacing,
+  ComponentVariantEnum,
+} from "../../../../types";
+
+export interface IAccordionComposition {
+  Root: typeof AccordionRoot;
+  Trigger: typeof AccordionTrigger;
+  Content: typeof AccordionContent;
+}
+export interface IAccordionProperties
+  extends IComponentSpacing,
+    React.ComponentProps<"div"> {}
+export interface IAccordionTriggerProperties extends IButtonProperties {
+  value: string;
+}
+export interface IAccordionContentProperties extends IAccordionProperties {
+  defaultOpen?: boolean;
+  value: string;
+}
+
+/**
+ * Accordions are used to expand and collapse sections of content.
+ *
+ * **Best practices:**
+ *
+ * - Use a clear and descriptive title for each accordion section.
+ * - Ensure that the accordion can be operated using only the keyboard.
+ * - Ensure that the focus is properly managed when the accordion section is expanded/collapsed.
+ *
+ * @param {IAccordionProperties} props - The props for the Accordion component.
+ * @param {ReactNode} props.children - The content to be rendered inside the accordion.
+ * @returns {ReactElement} The Accordion component.
+ */
+const Accordion = (props: IAccordionProperties) => {
+  const { children, ...restProps } = props;
+  const { id } = useAccordion();
+
+  return (
+    <div id={id} {...restProps}>
+      {children}
+    </div>
+  );
+};
+Accordion.displayName = "Accordion";
+
+const AccordionRoot = ({ children }: IReactChildren) => {
+  return <AccordionProvider>{children}</AccordionProvider>;
+};
+AccordionRoot.displayName = "Accordion.Root";
+
+/**
+ * Accordion.Trigger is used to triggers the expansion and collapse of the associated Accordion.Content component.
+ *
+ * **Best practices:**
+ *
+ * - Use a clear and descriptive title for the trigger that accurately conveys the content of the associated accordion section.
+ * - Ensure that the trigger can be operated using only the keyboard.
+ * - Ensure that the focus is properly managed when the trigger is activated.
+ *
+ * @param {IAccordionTriggerProperties} props - The props for the Accordion.Trigger component.
+ * @param {string} props.value - The value used to bind the Accordion.Trigger and Accordion.Content components.
+ * @param {ReactNode} props.children - The content to be rendered inside the accordion trigger.
+ * @returns {ReactElement} The Accordion.Trigger component.
+ */
+const AccordionTrigger = (props: IAccordionTriggerProperties) => {
+  const { value, disabled, onClick, children, ...restProps } = props;
+
+  const { states, methods } = useAccordion();
+  const { getAccordionId, applyValue } = methods;
+
+  const hasSameValueAsContext = value === states.value;
+  const IdHandler = {
+    trigger: getAccordionId && getAccordionId({ value, type: "trigger" }),
+    content: getAccordionId && getAccordionId({ value, type: "content" }),
+  };
+
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    if (!disabled) {
+      onClick && onClick(event);
+
+      if (applyValue) {
+        const unchangedValue = hasSameValueAsContext && states.value !== null;
+
+        if (unchangedValue) applyValue(null);
+        else applyValue(value);
+      }
+    }
+  };
+
+  return (
+    <Button
+      id={String(IdHandler.trigger)}
+      value={value}
+      disabled={disabled ?? false}
+      onClick={handleClick}
+      aria-expanded={hasSameValueAsContext}
+      aria-controls={String(IdHandler.content)}
+      data-state={hasSameValueAsContext ? "expanded" : "collapsed"}
+      variant={props.variant ?? ComponentVariantEnum.Ghost}
+      {...restProps}
+    >
+      {children}
+    </Button>
+  );
+};
+AccordionTrigger.displayName = "Accordion.Trigger";
+
+/**
+ * Accordion.Content is used to contains the content of the associated Accordion.Trigger component.
+ *
+ * **Best practices:**
+ *
+ * - Ensure that the content is hidden when the associated accordion section is collapsed.
+ * - Ensure that the content is properly focused when the associated accordion section is expanded.
+ *
+ * @param {IAccordionContentProperties} props - The props for the Accordion.Content component.
+ * @param {string} props.value - The value used to bind the Accordion.Content and Accordion.Trigger components.
+ * @param {boolean} props.defaultOpen - The initial open state of the accordion content. Defaults to false.
+ * @param {IComponentSpacing} props.spacing - The value used by the accordion's content spacings.
+ * @param {ReactNode} props.children - The content to be rendered inside the accordion.
+ * @returns {ReactElement} The Accordion.Content component.
+ */
+const AccordionContent = (props: IAccordionContentProperties) => {
+  const { defaultOpen = false, value, children, ...restProps } = props;
+
+  const { states, methods } = useAccordion();
+  const { getAccordionId, applyValue } = methods;
+
+  const hasSameValueAsContext = value === states.value;
+  const IdHandler = {
+    trigger: getAccordionId && getAccordionId({ value, type: "trigger" }),
+    content: getAccordionId && getAccordionId({ value, type: "content" }),
+  };
+
+  React.useEffect(() => {
+    if (defaultOpen && !hasSameValueAsContext && applyValue) applyValue(value);
+  }, []);
+
+  return (
+    <React.Fragment>
+      {hasSameValueAsContext && (
+        <div
+          role="article"
+          id={String(IdHandler.content)}
+          aria-labelledby={String(IdHandler.trigger)}
+          aria-expanded={hasSameValueAsContext}
+          data-value={value}
+          {...restProps}
+        >
+          {children}
+        </div>
+      )}
+    </React.Fragment>
+  );
+};
+AccordionContent.displayName = "Accordion.Content";
+
+Accordion.Root = AccordionRoot;
+Accordion.Trigger = AccordionTrigger;
+Accordion.Content = AccordionContent;
+
+export { Accordion, AccordionRoot, AccordionTrigger, AccordionContent };

package/src/avatar/Avatar.stories.tsx

@@ -0,0 +1,62 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Avatar } from "..";
+
+const meta = {
+  title: "Components/Avatar",
+  component: Avatar,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="m-medium-30">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof Avatar>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: ({ ...args }) => <Avatar {...args} />,
+};
+export const Status: Story = {
+  render: ({ ...args }) => (
+    <div className="flex g-medium-30">
+      <Avatar status="online" {...args} />
+      <Avatar status="away" {...args} />
+      <Avatar status="busy" {...args} />
+      <Avatar status="offline" {...args} />
+      <Avatar {...args} />
+    </div>
+  ),
+};
+export const Sizes: Story = {
+  render: ({ ...args }) => (
+    <div className="flex g-medium-30">
+      <Avatar sizing="large" {...args} />
+      <Avatar sizing="medium" {...args} />
+      <Avatar sizing="small" {...args} />
+    </div>
+  ),
+};
+export const Variants: Story = {
+  render: ({ ...args }) => (
+    <div className="flex g-medium-30">
+      <Avatar />
+      <Avatar
+        alt="foundation-logo"
+        src="https://avatars.githubusercontent.com/u/153380498?s=200&v=4"
+      />
+      <Avatar>
+        <b>AZ</b>
+      </Avatar>
+      <Avatar
+        style={{ backgroundColor: "var(--color-purple)" }}
+        status="online"
+      >
+        <small>Acme</small>
+      </Avatar>
+    </div>
+  ),
+};

package/src/avatar/index.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import React from "react";
+import { AvatarWrapper, StatusWrapper } from "./styles";
+import {
+  IComponentStyling,
+  ComponentSizeEnum,
+  IComponentSize,
+} from "../../../../types";
+
+export enum AvataStatusEnum {
+  Online = "online",
+  Away = "away",
+  Busy = "busy",
+  Offline = "offline",
+}
+export interface IAvatarProperties
+  extends IComponentStyling,
+    IComponentSize,
+    React.HTMLAttributes<HTMLDivElement> {
+  src?: string;
+  alt?: string;
+  status?: "online" | "away" | "busy" | "offline";
+}
+
+/**
+ * Avatar are used to represents a user or an entity on an interface.
+ *
+ * **Best practices:**
+ *
+ * - Use the appropriate size to match the context and the importance of the information.
+ * - Always provide an `alt` attribute for accessibility when using an image.
+ * - Indicate the user's activity status.
+ *
+ * @param {IAvatarProperties} props - The props for the Avatar component.
+ * @param {boolean} props.raw - Whether the avatar is styled or not.
+ * @param {ComponentSizeEnum} props.sizing - The size of the avatar. Defaults to ComponentSizeEnum.Medium.
+ * @param {string} props.status - The status of the user represented by the avatar.
+ * @param {string} props.src - The source URL of the image to be displayed in the avatar.
+ * @param {string} props.alt - The alternative text for the image in the avatar.
+ * @param {ReactNode} props.children - The content to be rendered inside the avatar.
+ * @returns {ReactElement} The Avatar component.
+ */
+export const Avatar = (props: IAvatarProperties) => {
+  const {
+    raw,
+    sizing = ComponentSizeEnum.Medium,
+    status,
+    src,
+    alt,
+    children,
+    ...restProps
+  } = props;
+  const sizeLabel = sizing ?? ComponentSizeEnum.Medium;
+
+  return (
+    <AvatarWrapper
+      data-raw={Boolean(raw)}
+      data-size={sizing}
+      data-status={status}
+      aria-label={props["aria-label"] ?? `${sizeLabel}-user-avatar`}
+      {...restProps}
+    >
+      {!children && src && (
+        <img
+          aria-label={`${sizeLabel}-user-avatar-image`}
+          alt={alt ?? `${sizeLabel}-user-avatar-image`}
+          src={src}
+        />
+      )}
+
+      {children}
+      {status && (
+        <StatusWrapper
+          role="img"
+          aria-label={`${sizing}-user-avatar-status`}
+          aria-labelledby="title desc"
+          data-status={status}
+          height="16"
+          width="16"
+        >
+          <title>{"Activity status"}</title>
+          <desc>{status}</desc>
+          <circle role="presentation" cx="8" cy="8" r="6" />
+        </StatusWrapper>
+      )}
+    </AvatarWrapper>
+  );
+};
+Avatar.displayName = "Avatar";

package/src/avatar/styles/index.ts

@@ -0,0 +1,79 @@
+import styled, { css } from "styled-components";
+
+const AvatarSizesStyles = css`
+  &[data-size="small"] {
+    width: var(--measurement-large-10);
+    height: var(--measurement-large-10);
+    min-width: var(--measurement-large-10);
+    min-height: var(--measurement-large-10);
+  }
+
+  &[data-size="medium"] {
+    width: var(--measurement-medium-90);
+    height: var(--measurement-medium-90);
+    min-width: var(--measurement-medium-90);
+    min-height: var(--measurement-medium-90);
+  }
+
+  &[data-size="large"] {
+    width: var(--measurement-large-20);
+    height: var(--measurement-large-20);
+    min-width: var(--measurement-large-20);
+    min-height: var(--measurement-large-20);
+  }
+`;
+const AvatarStatusesStyles = css`
+  &[data-status="online"] {
+    fill: var(--shade-green-10);
+    stroke: var(--shade-green-20);
+  }
+
+  &[data-status="away"] {
+    fill: var(--color-yellow);
+    stroke: var(--shade-yellow-10);
+  }
+
+  &[data-status="busy"] {
+    fill: var(--color-red);
+    stroke: var(--shade-red-10);
+  }
+
+  &[data-status="offline"] {
+    fill: var(--body-color);
+    stroke: var(--font-color-alpha-10);
+  }
+`;
+
+export const AvatarWrapper = styled.div`
+  &[data-raw="false"] {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+
+    background-color: var(--body-color);
+    border-radius: 100%;
+
+    img {
+      width: inherit;
+      height: inherit;
+      min-width: inherit;
+      min-height: inherit;
+      border-radius: 100%;
+    }
+
+    ${AvatarSizesStyles}
+  }
+`;
+export const StatusWrapper = styled.svg`
+  --status-position: calc(
+    var(--measurement-medium-10) - (var(--measurement-medium-10) * 2)
+  );
+
+  position: absolute;
+  stroke-width: var(--measurement-small-30);
+  bottom: var(--status-position);
+  right: var(--status-position);
+
+  ${AvatarStatusesStyles}
+`;

package/src/badge/Badge.stories.tsx

@@ -0,0 +1,60 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Badge } from "./";
+
+// Duplicated doc: The JSDoc content isn't rendering on Storybook.
+
+/**
+ * Badges are used to convey data or states to the users.
+ *
+ * **Best practices:**
+ *
+ * - Define the hierarchy of badges with different variants.
+ * - Badge label must convey short and understandable information.
+ *
+ */
+
+const meta = {
+  title: "Components/Badge",
+  component: Badge,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="m-medium-30">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof Badge>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: ({ ...args }) => <Badge {...args} />,
+};
+export const Shapes: Story = {
+  render: ({ ...args }) => {
+    return (
+      <div className="flex g-medium-30">
+        <Badge shape="square">Square</Badge>
+        <Badge shape="smooth">Smooth</Badge>
+        <Badge shape="round">Round</Badge>
+      </div>
+    );
+  },
+};
+export const Variants: Story = {
+  render: ({ ...args }) => {
+    return (
+      <div className="flex g-medium-30">
+        <Badge variant="primary">Primary</Badge>
+        <Badge variant="secondary">Secondary</Badge>
+        <Badge variant="border">Border</Badge>
+        <Badge variant="meta">Meta</Badge>
+        <Badge variant="success">Success</Badge>
+        <Badge variant="warning">Warning</Badge>
+        <Badge variant="error">Error</Badge>
+      </div>
+    );
+  },
+};

package/src/badge/index.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import React from "react";
+import { BadgeWrapper } from "./styles";
+
+import { IComponentStyling } from "../../../../types";
+
+interface IBadgeProperties
+  extends IComponentStyling,
+    React.ComponentProps<"div"> {
+  variant?:
+    | "primary"
+    | "secondary"
+    | "border"
+    | "error"
+    | "warning"
+    | "success"
+    | "meta";
+  shape?: "square" | "smooth" | "round";
+}
+
+/**
+ * Badges are used to convey data or states to the users.
+ *
+ * **Best practices:**
+ *
+ * - Define the hierarchy of badges with different variants.
+ * - Badge label must convey short and understandable information.
+ *
+ * @param {IBadgeProperties} props - The props for the Badge component.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {ComponentSizeEnum} props.shape - The shape of the component. Defaults to `smooth`.
+ * @param {string} props.variant - The style definition used by the component.
+ * @param {ReactNode} props.children - The content to be rendered inside the Badge.
+ * @returns {ReactElement} The Badge component.
+ */
+export const Badge = (props: IBadgeProperties) => {
+  const {
+    raw = false,
+    variant = "primary",
+    shape = "smooth",
+    children,
+    ...restProps
+  } = props;
+
+  return (
+    <BadgeWrapper
+      data-raw={raw}
+      data-variant={variant}
+      data-shape={shape}
+      {...restProps}
+    >
+      {children}
+    </BadgeWrapper>
+  );
+};
+
+Badge.displayName = "Badge";