@usefui/components 1.5.1

package/src/toolbar/index.tsx

@@ -0,0 +1,243 @@
+"use client";
+
+import React from "react";
+import { useKeyPress } from "@usefui/hooks";
+
+import { ToolbarProvider, useToolbar } from "./hooks";
+import { ToolbarWrapper, ToolbarTriggerWrapper } from "./styles";
+import { Button, IButtonProperties } from "..";
+import {
+  IComponentStyling,
+  ComponentSizeEnum,
+  ComponentHeightEnum,
+  TComponentHeight,
+  ComponentVariantEnum,
+  IComponentSize,
+  IReactChildren,
+  ComponentSideEnum,
+  TComponentSide,
+  IComponentControlProperties,
+  KeyBindingEnum,
+} from "../../../../types";
+
+export interface IToolbarBodyProperties
+  extends IComponentStyling,
+    IComponentSize,
+    IComponentControlProperties,
+    React.ComponentProps<"aside"> {
+  defaultOpen?: boolean;
+  side?: TComponentSide;
+  height?: TComponentHeight;
+}
+export interface IToolbarSectionProperties
+  extends React.ComponentProps<"section"> {
+  showoncollapse?: boolean;
+}
+export interface IToolbarItemProperties extends React.ComponentProps<"div"> {
+  showfirstchild?: boolean;
+}
+
+export interface IToolbarComposition {
+  Root: typeof ToolbarRoot;
+  Trigger: typeof ToolbarTrigger;
+  Item: typeof ToolbarItem;
+  Section: typeof ToolbarSection;
+}
+
+/**
+ * Toolbar are component that provides a set of tools or actions for the user.
+ *
+ * **Best practices:**
+ *
+ * - Use semantic HTML elements to structure the content of the toolbar.
+ * - Ensure that the toolbar is visible and accessible to all users, including those using assistive technologies.
+ * - Use keyboard shortcuts to provide an alternative way of interacting with the toolbar.
+ * - Ensure that the toolbar is responsive and adapts to different screen sizes and orientations.
+ *
+ * @param {IToolbarBodyProperties} props - The props for the Toolbar component.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {string} props.shortcut - The key combination used as keyboard shortcuts to trigger the toolbar.
+ * @param {string} props.hotkey - The key to use in the key combination for the keyboard shortcuts.
+ * @param {KeyBindingEnum} props.bindkey - The modifier key to use in the key combination.
+ * @param {TComponentSide} props.sizing - The size of the toolbar.
+ * @param {ComponentHeightEnum} props.height - The height definition of the toolbar.
+ * @param {ComponentSideEnum} props.side - The side of the toolbar.
+ * @param {boolean} props.defaultOpen - Whether the toolbar should be open by default.
+ * @param {ReactNode} props.children - The content to be rendered inside the toolbar.
+ * @returns {ReactElement} The Toolbar component.
+ */
+const Toolbar = (props: IToolbarBodyProperties) => {
+  const {
+    shortcut,
+    hotkey,
+    bindkey = KeyBindingEnum.Ctrl,
+    raw,
+    sizing = ComponentSizeEnum.Medium,
+    side = ComponentSideEnum.Left,
+    height = ComponentHeightEnum.Fullscreen,
+    defaultOpen,
+    children,
+    ...restProps
+  } = props;
+  const { id, methods, states } = useToolbar();
+  const { toggleToolbar } = methods;
+
+  const shortcutControls = useKeyPress(String(hotkey), true, bindkey);
+  const orientation =
+    side && ["left", "right"].includes(side) ? "vertical" : "horizontal";
+
+  React.useEffect(() => {
+    if (defaultOpen && toggleToolbar) return toggleToolbar(true);
+  }, [defaultOpen]);
+
+  React.useEffect(() => {
+    if (shortcut && shortcutControls && toggleToolbar) toggleToolbar();
+  }, [shortcutControls]);
+
+  return (
+    <ToolbarWrapper
+      id={id}
+      role="toolbar"
+      aria-label={props["aria-label"] ?? `${id}-toolbar`}
+      aria-controls={`${id}-trigger`}
+      aria-expanded={Boolean(states.expanded)}
+      aria-orientation={orientation}
+      data-raw={Boolean(raw)}
+      data-size={sizing}
+      data-height={height}
+      data-side={side}
+      {...restProps}
+    >
+      {children}
+    </ToolbarWrapper>
+  );
+};
+Toolbar.displayName = "Toolbar";
+
+const ToolbarRoot = ({ children }: IReactChildren) => {
+  return <ToolbarProvider>{children}</ToolbarProvider>;
+};
+ToolbarRoot.displayName = "Toolbar.Root";
+
+/**
+ * Toolbar.Trigger are used to triggers the expansion and collapse of the associated Toolbar component.
+ *
+ * **Best practices:**
+ *
+ * - Use a clear and descriptive title for the trigger that accurately conveys the content of the associated toolbar 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 {IButtonProperties} props - The props for the Toolbar.Trigger component.
+ * @param {ReactNode} props.children - The content to be rendered inside the Toolbar trigger.
+ * @returns {ReactElement} The Toolbar.Trigger component.
+ */
+const ToolbarTrigger = (props: IButtonProperties) => {
+  const {
+    raw,
+    onClick,
+    variant = ComponentVariantEnum.Ghost,
+    sizing = ComponentSizeEnum.Small,
+    children,
+    ...restProps
+  } = props;
+  const { id, methods, states } = useToolbar();
+  const { toggleToolbar } = methods;
+
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    if (onClick) onClick(event);
+    if (toggleToolbar) toggleToolbar(!states.expanded);
+  };
+
+  return (
+    <ToolbarTriggerWrapper data-raw={Boolean(raw)}>
+      <Button
+        id={`${id}-trigger`}
+        variant={variant}
+        sizing={sizing}
+        raw={Boolean(raw)}
+        onClick={handleClick}
+        {...restProps}
+      >
+        {children}
+      </Button>
+    </ToolbarTriggerWrapper>
+  );
+};
+ToolbarTrigger.displayName = "Toolbar.Trigger";
+
+/**
+ * ToolbarSection are used to hold components within a toolbar.
+ *
+ * **Best practices:**
+ *
+ * - Use semantic HTML elements to structure the content of the toolbar section.
+ * - Ensure that the toolbar section is visible and accessible to all users, including those using assistive technologies.
+ *
+ * @param {IToolbarSectionProperties} props - The props for the Toolbar.Section component.
+ * @param {boolean} props.showoncollapse - Whether the section should be shown only when the toolbar is collapsed.
+ * @param {ReactNode} props.children - The content to be rendered inside the toolbar section.
+ * @returns {ReactElement} The Toolbar.Section component.
+ */
+const ToolbarSection = (props: IToolbarSectionProperties) => {
+  const { showoncollapse, children, ...restProps } = props;
+  const { states } = useToolbar();
+  const { expanded } = states;
+
+  if (showoncollapse) return <section {...restProps}>{children}</section>;
+  return <section {...restProps}>{expanded && children}</section>;
+};
+ToolbarSection.displayName = "Toolbar.Section";
+
+/**
+ * ToolbarItem is a component that represents an item within a toolbar.
+ *
+ * **Best practices:**
+ *
+ * - Use semantic HTML elements to structure the content of the toolbar item.
+ * - Ensure that the toolbar item is visible and accessible to all users, including those using assistive technologies.
+ * - Ensure that the toolbar item is focusable and can be interacted with using the keyboard.
+ *
+ * @param {IToolbarItemProperties} props - The props for the Toolbar.Item component.
+ * @param {boolean} props.showfirstchild - Whether to show only the first child of the toolbar item when the toolbar is collapsed.
+ * @param {ReactNode} props.children - The content to be rendered inside the toolbar item.
+ * @returns {ReactElement} The Toolbar.Item component.
+ */
+const ToolbarItem = (props: IToolbarItemProperties) => {
+  const { showfirstchild, onClick, children, ...restProps } = props;
+  const childArray = React.Children.toArray(children);
+
+  const { id, states, methods } = useToolbar();
+  const { expanded } = states;
+  const { toggleToolbar } = methods;
+
+  const displayFirstChild =
+    showfirstchild && childArray.length > 1 && !expanded;
+
+  const handleClick = (event: React.MouseEvent<HTMLDivElement>) => {
+    if (onClick) onClick(event);
+    if (toggleToolbar && !expanded) toggleToolbar(true);
+  };
+
+  return (
+    <div
+      tabIndex={-1}
+      aria-hidden
+      aria-describedby={id}
+      data-expanded={expanded}
+      onClick={handleClick}
+      {...restProps}
+    >
+      {displayFirstChild && childArray[0]}
+      {expanded && children}
+    </div>
+  );
+};
+ToolbarItem.displayName = "Toolbar.Item";
+
+Toolbar.Root = ToolbarRoot;
+Toolbar.Trigger = ToolbarTrigger;
+Toolbar.Item = ToolbarItem;
+Toolbar.Section = ToolbarSection;
+
+export { Toolbar, ToolbarRoot, ToolbarTrigger, ToolbarItem, ToolbarSection };

package/src/toolbar/styles/index.ts

@@ -0,0 +1,129 @@
+import styled, { css } from "styled-components";
+
+export const ToolbarDefaultStyles = css`
+  margin: 0;
+  display: grid;
+  grid-template-rows: min-content;
+  background-color: var(--body-color);
+  border: var(--measurement-small-10) solid transparent;
+  padding: var(--measurement-medium-30);
+  min-width: var(--measurement-large-30);
+  min-height: fit-content;
+
+  &[aria-expanded="true"] {
+    width: 100%;
+
+    &[aria-orientation="horizontal"] {
+      height: 100%;
+      width: 100%;
+    }
+
+    menu {
+      display: flex;
+    }
+  }
+
+  &[aria-expanded="false"] {
+    width: fit-content;
+    justify-items: center;
+
+    &[aria-orientation="horizontal"] {
+      justify-items: start;
+      height: fit-content;
+      width: 100%;
+    }
+  }
+`;
+export const ToolbarSizeStyles = css`
+  &[data-size="small"] {
+    &[aria-orientation="vertical"] {
+      max-width: var(--measurement-large-70);
+    }
+    &[aria-orientation="horizontal"] {
+      max-height: var(--measurement-large-70);
+    }
+  }
+
+  &[data-size="medium"] {
+    &[aria-orientation="vertical"] {
+      max-width: var(--measurement-large-80);
+    }
+    &[aria-orientation="horizontal"] {
+      max-height: var(--measurement-large-80);
+    }
+  }
+
+  &[data-size="large"] {
+    &[aria-orientation="vertical"] {
+      max-width: var(--measurement-large-90);
+    }
+    &[aria-orientation="horizontal"] {
+      max-height: var(--measurement-large-90);
+    }
+  }
+
+  &[data-height="display"] {
+    &[aria-orientation="vertical"] {
+      max-width: calc(var(--measurement-large-90) * 1.618);
+    }
+    &[aria-orientation="horizontal"] {
+      max-height: calc(var(--measurement-large-90) * 1.618);
+    }
+  }
+
+  &[data-height="fullscreen"] {
+    &[aria-orientation="vertical"] {
+      max-width: 100dvw;
+    }
+    &[aria-orientation="horizontal"] {
+      max-height: 100dvh;
+    }
+  }
+`;
+export const ToolbarSideStyles = css`
+  &[data-side="top"] {
+    border-bottom-color: var(--font-color-alpha-10);
+  }
+  &[data-side="right"] {
+    border-left-color: var(--font-color-alpha-10);
+
+    &[aria-expanded="true"] {
+      menu {
+        justify-content: flex-end;
+      }
+    }
+    &[aria-expanded="false"] {
+      justify-items: end;
+    }
+  }
+  &[data-side="bottom"] {
+    border-top-color: var(--font-color-alpha-10);
+  }
+  &[data-side="left"] {
+    border-right-color: var(--font-color-alpha-10);
+
+    &[aria-expanded="true"] {
+      menu {
+        justify-content: flex-start;
+      }
+    }
+    &[aria-expanded="false"] {
+      justify-items: start;
+    }
+  }
+`;
+
+export const ToolbarWrapper = styled.menu<any>`
+  &[data-raw="false"] {
+    ${ToolbarDefaultStyles}
+    ${ToolbarSizeStyles}
+
+    ${ToolbarSideStyles}
+  }
+`;
+export const ToolbarTriggerWrapper = styled.menu<any>`
+  &[data-raw="false"] {
+    all: unset;
+    align-self: flex-end;
+  }
+`;

package/src/tooltip/Tooltip.stories.tsx

@@ -0,0 +1,60 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Tooltip } from "..";
+
+// Duplicated doc: The JSDoc content isn't rendering on Storybook.
+
+/**
+ * Toolpire are used to convey additional information while hovering a component.
+ *
+ * **Best practices:**
+ *
+ * - Ensure that the content is short and readable.
+ *
+ */
+const meta = {
+  title: "Components/Tooltip",
+  component: Tooltip,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="h-100 w-100 grid justify-center align-center">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof Tooltip>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  args: {
+    raw: false,
+    content: "",
+    delay: 200,
+    children: "",
+  },
+  argTypes: {},
+  render: () => (
+    <p className="fs-medium-20 p-large-30">
+      User analytics is applied in various&nbsp;
+      <Tooltip content="Tooltips">
+        <b>industries</b>
+      </Tooltip>
+      &nbsp;and settings to gain insights into user behavior and improve user
+      experience. By analyzing user behavior,&nbsp;
+      <Tooltip content="are">
+        <b>organizations</b>
+      </Tooltip>
+      &nbsp;can identify areas where users may be experiencing difficulties or
+      frustration, take steps to improve their product, and then, improve user
+      experience. User analytics allows you to personalize experiences and
+      better understand &nbsp;
+      <Tooltip content="Great">
+        <b>customer</b>
+      </Tooltip>
+      &nbsp; needs.
+    </p>
+  ),
+};

package/src/tooltip/index.tsx

@@ -0,0 +1,177 @@
+"use client";
+
+import React from "react";
+
+import { ContentBox, ContentWrapper } from "./styles";
+
+import { applyDataState } from "../utils";
+import { ComponentSideEnum, IComponentStyling } from "../../../../types";
+
+interface ITooltipProperties
+  extends IComponentStyling,
+    React.ComponentProps<"span"> {
+  delay?: number;
+  content: string;
+  children: React.ReactNode;
+}
+
+/**
+ * Tooltips are used to convey additional information while hovering a component.
+ *
+ * **Best practices:**
+ *
+ * - Ensure that the content is short and readable.
+ *
+ * @param {ITooltipProperties} props - The props for the Tooltip component.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {number} props.delay - The delay in ms awaited until the Tooltip is displayed. Default to 200ms.
+ * @param {string} props.content - The additional content to be rendered inside the Tooltip.
+ * @param {ReactNode} props.children - The content to be rendered as Tooltip children.
+ * @returns {ReactElement} The Tooltip component.
+ */
+const Tooltip = ({
+  delay = 200,
+  content,
+  children,
+  ...restProps
+}: ITooltipProperties) => {
+  const [visible, setVisible] = React.useState(false);
+  const [triggerProps, setTriggerProps] = React.useState<{
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    width: number;
+    height: number;
+  } | null>(null);
+  const [contentProps, setContentProps] = React.useState<{
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    width: number;
+    height: number;
+  } | null>(null);
+
+  const mounted = React.useRef(false);
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const contentRef = React.useRef<HTMLDivElement>(null);
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const contentRect = () => contentRef?.current?.getBoundingClientRect();
+  const bodyRect = React.useCallback(() => {
+    if (typeof document !== "undefined") {
+      return document.body.getBoundingClientRect();
+    }
+  }, []);
+
+  const positions = {
+    btt: `calc((${triggerProps?.top}px - ${contentProps?.height}px) - (var(--measurement-medium-10)))`,
+    ttb: `calc((${triggerProps?.top}px + ${triggerProps?.height}px) + var(--measurement-medium-10))`,
+    ltr: `${triggerProps?.left}px`,
+    rtl: `calc(${triggerProps?.left}px - (${contentProps?.width}px - ${triggerProps?.width}px))`,
+  };
+  const dimensions = {
+    body_width: bodyRect()?.width,
+    body_height: bodyRect()?.height,
+    content_width: contentProps?.width,
+    content_height: contentProps?.height,
+    content_left: contentProps?.left,
+    content_bottom: contentProps?.bottom,
+  };
+
+  const hasEnoughHorizontalSpace =
+    Number(dimensions.body_width) - Number(dimensions.content_left) >
+    Number(dimensions.content_width) * 1.1;
+
+  const hasEnoughVerticalSpace =
+    Number(dimensions.body_height) - Number(dimensions.content_bottom) >
+    Number(dimensions.content_height) * 0.9;
+
+  const showTooltip = React.useCallback(() => {
+    timeoutRef.current = setTimeout(() => setVisible(true), delay);
+  }, [delay]);
+
+  const hideTooltip = React.useCallback(() => {
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    setVisible(false);
+  }, []);
+
+  const handleMouseEnter = React.useCallback(() => {
+    const rect = containerRef.current?.getBoundingClientRect();
+    if (rect) {
+      setTriggerProps({
+        top: rect.top,
+        right: rect.right,
+        bottom: rect.bottom,
+        left: rect.left,
+        width: rect.width,
+        height: rect.height,
+      });
+      showTooltip();
+    }
+  }, [showTooltip]);
+
+  const handleMouseLeave = React.useCallback(
+    () => hideTooltip(),
+    [hideTooltip]
+  );
+
+  React.useEffect(() => {
+    mounted.current = true;
+
+    setContentProps &&
+      setContentProps({
+        top: Number(contentRect()?.top),
+        right: Number(contentRect()?.right),
+        bottom: Number(contentRect()?.bottom),
+        left: Number(contentRect()?.left),
+        width: Number(contentRect()?.width),
+        height: Number(contentRect()?.height),
+      });
+
+    return () => {
+      mounted.current = false;
+    };
+  }, [visible]);
+
+  return (
+    <ContentBox
+      ref={containerRef}
+      style={{ display: "inline-block", position: "relative" }}
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+      {...restProps}
+    >
+      {children}
+      {visible && (
+        <ContentWrapper
+          ref={contentRef}
+          style={{
+            top: hasEnoughVerticalSpace ? positions.ttb : positions.btt,
+            left: hasEnoughHorizontalSpace ? positions.ltr : positions.rtl,
+            position: "fixed",
+          }}
+          role="tooltip"
+          data-state={applyDataState(visible)}
+          data-raw={Boolean(restProps.raw)}
+          data-side={
+            hasEnoughHorizontalSpace
+              ? ComponentSideEnum.Left
+              : ComponentSideEnum.Right
+          }
+          data-align={
+            hasEnoughHorizontalSpace
+              ? ComponentSideEnum.Left
+              : ComponentSideEnum.Right
+          }
+        >
+          <div>{content}</div>
+        </ContentWrapper>
+      )}
+    </ContentBox>
+  );
+};
+Tooltip.displayName = "Tooltip";
+
+export { Tooltip };

package/src/tooltip/styles/index.ts

@@ -0,0 +1,38 @@
+import styled, { css, keyframes } from "styled-components";
+
+const FadeIn = keyframes`
+  0% {
+    opacity: 0;
+  }
+  100% {
+    opacity: 1;
+  }
+`;
+
+export const ContentBox = styled.div<any>`
+  display: inline-block;
+  position: relative;
+`;
+export const ContentWrapper = styled.span<any>`
+  &[data-raw="false"] {
+    width: fit-content;
+    max-width: var(--measurement-large-60);
+
+    * {
+      color: var(--body-color) !important;
+      white-space: nowrap;
+      text-overflow: ellipsis;
+      overflow: hidden;
+    }
+
+    background: var(--font-color);
+    padding: var(--measurement-medium-10) var(--measurement-medium-30);
+    border: var(--measurement-small-10) solid var(--font-color-alpha-10);
+    border-radius: var(--measurement-medium-20);
+    font-size: var(--fontsize-medium-10);
+    z-index: var(--depth-default-100);
+    animation-duration: 0.2s;
+    animation-name: ${FadeIn};
+    animation-fill-mode: backwards;
+  }
+`;

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export const applyDataState = (condition: boolean): string | void =>
+  condition ? "open" : "closed";

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "baseUrl": "./src",
+    "outDir": "./dist",
+    "jsx": "react",
+    "target": "es2022",
+    "module": "CommonJS",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,16 @@
+import { coverageConfigDefaults, defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    coverage: {
+      all: true,
+      enabled: true,
+      provider: "istanbul",
+      reporter: ["lcov", "html", "text", "json-summary", "json"],
+      reportOnFailure: true,
+      allowExternal: true,
+      exclude: [...coverageConfigDefaults.exclude, "**/*.stories.*"],
+    },
+  },
+});