@usefui/components 1.5.1

package/src/otp-field/types/index.ts

@@ -0,0 +1,23 @@
+export interface OTPFieldContextType {
+  otp: string[];
+  inputRefs: React.MutableRefObject<(HTMLInputElement | null)[]>;
+  length: number;
+  activeIndex: number;
+  handleChange: (index: number, value: string) => void;
+  handleKeyDown: (index: number, e: React.KeyboardEvent) => void;
+  handleClick: (index: number) => void;
+  handlePaste: (e: React.ClipboardEvent) => void;
+  handleFocus: (index: number) => void;
+}
+
+export interface OTPFieldProps {
+  name?: string;
+  id?: string;
+  children: React.ReactNode;
+  length?: number;
+  onComplete?: (value: string) => void;
+}
+
+export interface OTPFieldSlotProps {
+  index: number;
+}

package/src/overlay/Overlay.stories.tsx

@@ -0,0 +1,59 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Overlay, Button } from "..";
+
+// Duplicated doc: The JSDoc content isn't rendering on Storybook.
+
+/**
+ * Overlay are used to display content on top of the current layer.
+ *
+ * **Best practices:**
+ *
+ * - Use semantic HTML elements to structure the content of the overlay.
+ * - Ensure that the overlay is visible and accessible to all users, including those using assistive technologies.
+ * - Use keyboard shortcuts to provide an alternative way of interacting with the overlay.
+ * - Ensure that the overlay is responsive and adapts to different screen sizes and orientations.
+ *
+ */
+const meta = {
+  title: "Components/Overlay",
+  component: Overlay,
+  tags: ["autodocs"],
+} satisfies Meta<typeof Overlay>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  args: {
+    raw: false,
+    visible: false,
+    closeOnInteract: false,
+  },
+  render: ({ ...args }) => {
+    const [displayed, setDisplayed] = React.useState(args.visible);
+    return (
+      <React.Fragment>
+        <Button onClick={() => setDisplayed(true)}>Show</Button>
+        <Overlay visible={displayed} />
+      </React.Fragment>
+    );
+  },
+};
+export const Visible: Story = {
+  args: {
+    raw: false,
+    visible: true,
+    closeOnInteract: false,
+  },
+  render: ({ ...args }) => <Overlay visible={args.visible} />,
+};
+export const CloseOnInteraction: Story = {
+  args: {
+    raw: false,
+    visible: true,
+    closeOnInteract: true,
+  },
+  render: ({ ...args }) => (
+    <Overlay visible={args.visible} closeOnInteract={args.closeOnInteract} />
+  ),
+};

package/src/overlay/index.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import React from "react";
+import { OverlayWrapper } from "./styles";
+import { IComponentStyling } from "../../../../types";
+
+export interface IOverlayProperties
+  extends IComponentStyling,
+    React.ComponentProps<"div"> {
+  visible?: boolean;
+  closeOnInteract?: boolean;
+}
+
+/**
+ * Overlay are used to display content on top of the current layer.
+ *
+ * **Best practices:**
+ *
+ * - Use semantic HTML elements to structure the content of the overlay.
+ * - Ensure that the overlay is visible and accessible to all users, including those using assistive technologies.
+ * - Use keyboard shortcuts to provide an alternative way of interacting with the overlay.
+ * - Ensure that the overlay is responsive and adapts to different screen sizes and orientations.
+ *
+ * @param {IOverlayProperties} props - The props for the Overlay component.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {boolean} props.visible - Whether the component is visible or not.
+ * @param {boolean} props.closeOnInteract - Whether the overlay should be closed when the user interacts with it.
+ * @param {function} props.onClick - The callback function to be invoked when the overlay is clicked.
+ * @returns {ReactElement} The Overlay component.
+ */
+export const Overlay = (props: IOverlayProperties) => {
+  const { raw, visible, closeOnInteract, onClick, ...restProps } = props;
+  const [mounted, setMounted] = React.useState<boolean>(Boolean(visible));
+
+  const handleClick = (event: React.MouseEvent<HTMLDivElement>) => {
+    if (onClick) onClick(event);
+    if (closeOnInteract) setMounted(false);
+  };
+
+  React.useEffect(() => {
+    if (visible !== mounted) setMounted(Boolean(visible));
+  }, [visible]);
+
+  return (
+    <>
+      {mounted && (
+        <OverlayWrapper
+          tabIndex={-1}
+          onClick={handleClick}
+          aria-hidden={true}
+          data-raw={Boolean(raw)}
+          {...restProps}
+        />
+      )}
+    </>
+  );
+};
+Overlay.displayName = "Overlay";

package/src/overlay/styles/index.ts

@@ -0,0 +1,26 @@
+import styled from "styled-components";
+
+export const OverlayWrapper = styled.div<any>`
+  @keyframes animate-fade {
+    0% {
+      opacity: 0;
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: var(--depth-default-90);
+
+  &[data-raw="false"] {
+    background-color: rgba(0, 0, 0, 0.6); // Always forced to black
+    animation-duration: 0.2s;
+    animation-name: animate-fade;
+    animation-fill-mode: backwards;
+  }
+`;

package/src/page/Page.stories.tsx

@@ -0,0 +1,85 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Page } from "..";
+import {
+  ComponentSizeEnum,
+  ComponentSideEnum,
+  ComponentHeightEnum,
+} from "../../../../types";
+
+const meta = {
+  title: "Components/Page",
+  component: Page,
+  tags: ["autodocs"],
+} satisfies Meta<typeof Page>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+export const Composed: Story = {
+  args: {
+    raw: false,
+    defaultOpen: false,
+    showoncollapse: false,
+    showfirstchild: false,
+    shortcut: false,
+    hotkey: ":",
+    bindkey: null,
+  },
+  argTypes: {
+    side: {
+      options: [
+        ComponentSideEnum.Top,
+        ComponentSideEnum.Right,
+        ComponentSideEnum.Bottom,
+        ComponentSideEnum.Left,
+      ],
+      control: { type: "radio" },
+    },
+    sizing: {
+      options: [
+        ComponentSizeEnum.Small,
+        ComponentSizeEnum.Medium,
+        ComponentSizeEnum.Large,
+      ],
+      control: { type: "radio" },
+    },
+    height: {
+      options: [ComponentHeightEnum.Fullscreen, ComponentHeightEnum.Auto],
+      control: { type: "radio" },
+    },
+  },
+  render: ({ ...args }) => {
+    return (
+      <Page>
+        <Page.Tools
+          shortcut
+          hotkey=";"
+          showoncollapse
+          side={ComponentSideEnum.Left}
+          sizing={ComponentSizeEnum.Medium}
+        />
+        <div style={{ height: "100dvh" }}>
+          <Page.Navigation>🐻</Page.Navigation>
+          <Page.Menu>🐻‍❄️</Page.Menu>
+          <Page.Content>🦊</Page.Content>
+          <Page.Panel
+            shortcut
+            hotkey=","
+            side={ComponentSideEnum.Bottom}
+            sizing={ComponentSizeEnum.Large}
+          >
+            🐱
+          </Page.Panel>
+        </div>
+        <Page.Tools
+          shortcut
+          hotkey=":"
+          defaultOpen
+          side={ComponentSideEnum.Right}
+          sizing={ComponentSizeEnum.Large}
+        />
+      </Page>
+    );
+  },
+};

package/src/page/index.tsx

@@ -0,0 +1,265 @@
+"use client";
+
+import React from "react";
+import {
+  Toolbar,
+  IToolbarBodyProperties,
+  IToolbarSectionProperties,
+  ScrollArea,
+  IScrollAreaProperties,
+  IButtonProperties,
+} from "..";
+import {
+  PageRootWrapper,
+  PageNavWrapper,
+  PageMenuWrapper,
+  PagePanelWrapper,
+  PageSectionWrapper,
+  PageBodyWrapper,
+} from "./styles";
+
+export interface IPageToolsProperties
+  extends IToolbarBodyProperties,
+    IToolbarSectionProperties {
+  trigger?: React.ReactNode | string;
+  triggerProps?: IButtonProperties;
+  fixed?: boolean;
+}
+export interface IPageWrapperProperties {
+  $menus?: number;
+  $navigations?: number;
+}
+
+/**
+ * Pages are structured components used to build User Interface layouts.
+ *
+ * @param {React.ComponentProps<"div">} props - The props for the Page component.
+ * @returns {ReactElement} The Page component.
+ */
+const Page = (props: React.ComponentProps<"div">) => {
+  const { children } = props;
+  return (
+    <PageRootWrapper className="flex" {...props}>
+      {children}
+    </PageRootWrapper>
+  );
+};
+Page.displayName = "Page";
+
+/**
+ * Navigations are used to hold links and actions.
+ *
+ * @param {React.ComponentProps<"div">} props - The props for the Page.Navigation component.
+ * @returns {ReactElement} The Page.Navigation component.
+ */
+const PageNavigation = (props: React.ComponentProps<"nav">) => {
+  const { children } = props;
+  return <PageNavWrapper {...props}>{children}</PageNavWrapper>;
+};
+PageNavigation.displayName = "Page.Navigation";
+
+/**
+ * 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 Page.Toolbar.
+ * - Ensure that the Page.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 Page.Toolbar.
+ * - Ensure that the Page.Toolbar is responsive and adapts to different screen sizes and orientations.
+ *
+ * @param {IPageToolsProperties} props - The props for the Page.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 Page.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 {ComponentSizeEnum} props.sizing - The size of the Page.Toolbar.
+ * @param {ComponentHeightEnum} props.height - The height definition of the Page.Toolbar.
+ * @param {TComponentSide} props.side - The side of the Page.Toolbar.
+ * @param {boolean} props.defaultOpen - Whether the Page.Toolbar should be open by default.
+ * @param {ReactNode} props.children - The content to be rendered inside the Page.Toolbar.
+ * @returns {ReactElement} The Page.Toolbar component.
+ */
+const PageTools = (props: IPageToolsProperties) => {
+  const {
+    shortcut,
+    hotkey,
+    bindkey,
+    raw,
+    sizing,
+    side,
+    defaultOpen,
+    fixed,
+    showoncollapse,
+    onClick,
+    trigger,
+    triggerProps,
+    children,
+  } = props;
+
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    if (onClick) onClick(event);
+  };
+
+  return (
+    <Toolbar.Root>
+      <Toolbar
+        raw={raw}
+        sizing={sizing}
+        side={side}
+        shortcut={!fixed && shortcut}
+        hotkey={hotkey}
+        bindkey={bindkey}
+        defaultOpen={defaultOpen}
+        {...props}
+      >
+        <Toolbar.Section showoncollapse={showoncollapse}>
+          {children}
+        </Toolbar.Section>
+
+        {!fixed && (
+          <Toolbar.Trigger
+            title={
+              shortcut ? `${bindkey ?? "ctrl"} + ${hotkey}` : "toolbar-trigger"
+            }
+            onClick={handleClick}
+            {...triggerProps}
+          >
+            {trigger ?? <span>&harr;</span>}
+          </Toolbar.Trigger>
+        )}
+      </Toolbar>
+    </Toolbar.Root>
+  );
+};
+PageTools.displayName = "Page.Tools";
+
+const PageContent = (
+  props: React.ComponentProps<"div"> & IScrollAreaProperties
+) => {
+  const { children } = props;
+  return (
+    <ScrollArea as={PageSectionWrapper} {...props}>
+      {children}
+    </ScrollArea>
+  );
+};
+PageContent.displayName = "Page.Content";
+
+const PageWrapper = (
+  props: IPageWrapperProperties & React.ComponentProps<"div">
+) => {
+  const { children } = props;
+  return <PageBodyWrapper {...props}>{children}</PageBodyWrapper>;
+};
+PageWrapper.displayName = "Page.Wrapper";
+
+/**
+ * Panel 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 Page.Panel.
+ * - Ensure that the Page.Panel is visible and accessible to all users, including those using assistive technologies.
+ * - Use keyboard shortcuts to provide an alternative way of interacting with the Page.Panel.
+ * - Ensure that the Page.Panel is responsive and adapts to different screen sizes and orientations.
+ *
+ * @param {IPageToolsProperties} props - The props for the Page.Panel 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 Page.Panel.
+ * @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 {ComponentSizeEnum} props.sizing - The size of the Page.Panel.
+ * @param {ComponentHeightEnum} props.height - The height definition of the Page.Panel.
+ * @param {TComponentSide} props.side - The side of the Page.Panel.
+ * @param {boolean} props.defaultOpen - Whether the Page.Panel should be open by default.
+ * @param {ReactNode} props.children - The content to be rendered inside the Page.Panel.
+ * @returns {ReactElement} The Page.Panel component.
+ */
+const PagePanel = (props: IPageToolsProperties) => {
+  const {
+    shortcut,
+    hotkey,
+    bindkey,
+    raw,
+    sizing,
+    height = "auto",
+    side,
+    defaultOpen,
+    fixed,
+    showoncollapse,
+    onClick,
+    trigger,
+    triggerProps,
+    children,
+  } = props;
+
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    if (onClick) onClick(event);
+  };
+
+  return (
+    <Toolbar.Root>
+      <PagePanelWrapper
+        as={Toolbar}
+        raw={raw}
+        sizing={sizing}
+        height={height}
+        side={side}
+        shortcut={!fixed && shortcut}
+        hotkey={hotkey}
+        bindkey={bindkey}
+        defaultOpen={defaultOpen}
+        aria-label={props["aria-label"]}
+      >
+        {!fixed && (
+          <Toolbar.Trigger
+            title={
+              shortcut ? `${bindkey ?? "ctrl"} + ${hotkey}` : "toolbar-trigger"
+            }
+            onClick={handleClick}
+            {...triggerProps}
+          >
+            {trigger ?? (
+              <span style={{ transform: "rotate(90deg)" }}>&harr;</span>
+            )}
+          </Toolbar.Trigger>
+        )}
+
+        <Toolbar.Section showoncollapse={showoncollapse}>
+          {children}
+        </Toolbar.Section>
+      </PagePanelWrapper>
+    </Toolbar.Root>
+  );
+};
+PagePanel.displayName = "Page.Panel";
+
+/**
+ * Menus are used to hold links and actions.
+ *
+ * @param {React.ComponentProps<"menu">} props - The props for the Page.Menu component.
+ * @returns {ReactElement} The Page.Menu component.
+ */
+const PageMenu = (props: React.ComponentProps<"menu">) => {
+  const { children } = props;
+  return <PageMenuWrapper {...props}>{children}</PageMenuWrapper>;
+};
+PageMenu.displayName = "Page.Menu";
+
+Page.Navigation = PageNavigation;
+Page.Tools = PageTools;
+Page.Wrapper = PageWrapper;
+Page.Content = PageContent;
+Page.Panel = PagePanel;
+Page.Menu = PageMenu;
+
+export {
+  Page,
+  PageNavigation,
+  PageTools,
+  PagePanel,
+  PageWrapper,
+  PageContent,
+  PageMenu,
+};

package/src/page/styles/index.ts

@@ -0,0 +1,59 @@
+import styled from "styled-components";
+import { HiddenScrollbar } from "../../scrollarea/styles";
+
+export const PageRootWrapper = styled.div<any>`
+  height: 100dvh;
+  width: 100%;
+`;
+export const PageNavWrapper = styled.nav<any>`
+  background-color: var(--body-color);
+  border: var(--measurement-small-10) solid transparent;
+  border-bottom-color: var(--font-color-alpha-10);
+  width: 100%;
+  height: 100%;
+  max-height: var(--measurement-large-20);
+  padding: var(--measurement-medium-30);
+`;
+export const PageMenuWrapper = styled.menu<any>`
+  background-color: var(--body-color);
+  border: var(--measurement-small-10) solid transparent;
+  border-bottom-color: var(--font-color-alpha-10);
+  width: 100%;
+  height: 100%;
+  max-height: var(--measurement-large-30);
+  margin: 0;
+  padding: var(--measurement-medium-60) var(--measurement-medium-30);
+`;
+export const PagePanelWrapper = styled.aside<any>`
+  position: absolute;
+  bottom: 0;
+  width: 100%;
+  overflow: scroll;
+  ${HiddenScrollbar}
+`;
+export const PageSectionWrapper = styled.div<any>`
+  background: var(--body-color);
+  width: 100%;
+  height: 100%;
+`;
+export const PageBodyWrapper = styled.div<any>`
+  --menus-height: calc(
+    var(--measurement-large-30) *
+      ${({ $menus }) => ($menus ? Number($menus) : 0)}
+  );
+  --navs-height: calc(
+    var(--measurement-large-20) *
+      ${({ $navigations }) => ($navigations ? Number($navigations) : 0)}
+  );
+  --page-height: calc(100dvh - (var(--menus-height) + var(--navs-height)));
+
+  outline: none;
+  display: inline-block;
+
+  height: var(--page-height);
+  max-height: var(--page-height);
+
+  width: 100%;
+  overflow: scroll;
+  ${HiddenScrollbar}
+`;

package/src/portal/Portal.stories.tsx

@@ -0,0 +1,27 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Portal } from "..";
+
+// Duplicated doc: The JSDoc content isn't rendering on Storybook.
+/**
+ * Portal are used to render children into a DOM node that exists outside the DOM hierarchy of the parent component.
+ */
+const meta = {
+  title: "Components/Portal",
+  component: Portal,
+  tags: ["autodocs"],
+} satisfies Meta<typeof Portal>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  args: {
+    container: "",
+  },
+  render: ({ ...args }) => (
+    <React.Fragment>
+      <div id="portal-container" />
+      <Portal container="portal-container">🐻🐻‍❄️🦊🐱🐶</Portal>
+    </React.Fragment>
+  ),
+};

package/src/portal/index.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import React from "react";
+import { createPortal } from "react-dom";
+
+export interface IPortalProperties {
+  container: string;
+  children?: React.ReactNode;
+}
+
+/**
+ * Portal are used to render children into a DOM node that exists outside the DOM hierarchy of the parent component.
+ *
+ * @param {IPortalProperties} props - The props for the Portal component.
+ * @param {string} props.container - The ID of the DOM element to render the portal into.
+ * @param {ReactNode} props.children - The content to be rendered inside the portal.
+ * @returns {ReactElement} The Portal component.
+ */
+export const Portal = (props: IPortalProperties) => {
+  // Handle SSR in Next.js and Electron's renderer process
+  if (typeof document === "undefined") return null;
+
+  const { container, children } = props;
+
+  const [hasMounted, setHasMounted] = React.useState<boolean>(false);
+  const [portalRoot, setPortalRoot] = React.useState<Element | null>(null);
+
+  React.useEffect(() => {
+    setHasMounted(true);
+    setPortalRoot(document.querySelector(`#${container}`));
+  }, [container]);
+
+  if (!hasMounted || !portalRoot) return null;
+  return createPortal(children, portalRoot);
+};
+Portal.displayName = "Portal";