@usefui/components 1.6.0 → 1.7.1

package/src/select/index.tsx

@@ -0,0 +1,331 @@
+"use client";
+
+import React from "react";
+
+import { useClickOutside } from "@usefui/hooks";
+import { SelectProvider, useSelect } from "./hooks";
+
+import { Wrapper, Trigger, Label, Content, List, Item } from "./styles";
+import { ScrollArea } from "../scrollarea";
+
+import { applyDataState } from "../utils";
+import { IButtonProperties } from "../button";
+import {
+  IComponentStyling,
+  ComponentVariantEnum,
+  ComponentShapeEnum,
+  ComponentSizeEnum,
+} from "../../../../types";
+
+export interface ISelectTriggerProperties extends IButtonProperties {
+  error?: boolean;
+  children?: React.ReactNode;
+}
+
+export interface ISelectContentProperties
+  extends IComponentStyling, React.ComponentPropsWithRef<"ul"> {
+  defaultOpen?: boolean;
+}
+
+export interface ISelectItemProperties
+  extends IComponentStyling, Omit<React.ComponentProps<"li">, "onClick"> {
+  value?: string;
+  disabled?: boolean;
+  onClick?: (
+    event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>,
+  ) => void;
+}
+
+const SelectRoot = ({ children }: { children: React.ReactElement }) => {
+  return <SelectProvider>{children}</SelectProvider>;
+};
+SelectRoot.displayName = "Select.Root";
+
+/**
+ * Select is used to allow users to choose a single value from a list of options.
+ *
+ * **Best practices:**
+ *
+ * - Use a clear and descriptive label for the trigger that accurately conveys he purpose of the select.
+ * - Ensure that the select can be opened and closed using the keyboard.
+ * - Ensure that the select is dismissed when the user clicks outside of it or presses the Esc key.
+ * - Wrap this component with `Select.Root` to provide the necessary context.
+ *
+ * @param {React.ComponentProps<"div">} props - The props for the Select component.
+ * @param {ReactNode} props.children - The content to be rendered inside the select.
+ * @returns {ReactElement} The Select component.
+ */
+const Select = ({ children }: React.ComponentProps<"div">) => {
+  const selectRef = React.useRef<HTMLDivElement | null>(null);
+  const { states, methods } = useSelect();
+
+  const handleClickOutside = () => {
+    if (states.open && methods.setOpen) {
+      methods.setOpen(false);
+    }
+  };
+
+  useClickOutside(
+    selectRef as React.RefObject<HTMLElement>,
+    handleClickOutside,
+  );
+
+  return <Wrapper ref={selectRef}>{children}</Wrapper>;
+};
+Select.displayName = "Select";
+
+/**
+ * Select.Trigger is used to control the expansion and collapse of the associated Select.Content component.
+ *
+ * **Best practices:**
+ *
+ * - Use a clear and descriptive label that accurately conveys the purpose of the select field.
+ * - Ensure that the trigger can be operated using only the keyboard.
+ * - Ensure that the focus is properly managed when the trigger is activated.
+ * - Use the `error` prop to indicate a validation error state.
+ *
+ * @param {ISelectTriggerProperties} props - The props for the Select.Trigger component.
+ * @param {ComponentVariantEnum} props.variant - The visual variant of the trigger. Defaults to "secondary".
+ * @param {ComponentShapeEnum} props.shape - The shape of the trigger. Defaults to "smooth".
+ * @param {ComponentSizeEnum} props.sizing - The size of the trigger. Defaults to "medium".
+ * @param {boolean} props.error - Whether the trigger should display an error state. Defaults to false.
+ * @param {boolean} props.disabled - Whether the trigger is disabled.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {ReactNode} props.children - The content to be rendered inside the trigger.
+ * @returns {ReactElement} The Select.Trigger component.
+ */
+const SelectTrigger = (props: ISelectTriggerProperties) => {
+  const {
+    raw,
+    variant,
+    shape,
+    sizing,
+    error = false,
+    disabled,
+    children,
+    ...restProps
+  } = props;
+
+  const triggerRef = React.useRef<HTMLButtonElement>(null);
+  const triggerRect = () => triggerRef.current?.getBoundingClientRect();
+
+  const { id, states, methods } = useSelect();
+  const { toggleOpen, setTriggerProps } = methods;
+
+  const handleClick = () => {
+    if (disabled) return;
+    if (toggleOpen) toggleOpen();
+    if (setTriggerProps) {
+      setTriggerProps({
+        top: Number(triggerRect()?.top),
+        right: Number(triggerRect()?.right),
+        bottom: Number(triggerRect()?.bottom),
+        left: Number(triggerRect()?.left),
+        width: Number(triggerRect()?.width),
+        height: Number(triggerRect()?.height),
+      });
+    }
+  };
+
+  return (
+    <Trigger
+      ref={triggerRef}
+      type="button"
+      role="combobox"
+      id={id.split("|").at(0)}
+      onClick={handleClick}
+      aria-haspopup="listbox"
+      aria-expanded={Boolean(states.open)}
+      aria-controls={id.split("|").at(-1)}
+      data-state={states.open ? "open" : "closed"}
+      data-variant={variant ?? ComponentVariantEnum.Secondary}
+      data-shape={shape ?? ComponentShapeEnum.Smooth}
+      data-size={sizing ?? ComponentSizeEnum.Medium}
+      data-error={error}
+      data-raw={Boolean(raw)}
+      disabled={disabled}
+      {...restProps}
+    >
+      <Label>{children}</Label>
+    </Trigger>
+  );
+};
+SelectTrigger.displayName = "Select.Trigger";
+
+/**
+ * Select.Content contains the list of options associated with the Select.Trigger component.
+ *
+ * **Best practices:**
+ *
+ * - Ensure that the content is hidden when the select is collapsed.
+ * - Ensure that the content is properly positioned relative to the trigger,
+ *   accounting for available viewport space.
+ * - Ensure that the content can be dismissed using the Esc key.
+ *
+ * @param {ISelectContentProperties} props - The props for the Select.Content component.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {boolean} props.defaultOpen - The initial open state of the select. Defaults to false.
+ * @param {ReactNode} props.children - The list of Select.Item components to render.
+ * @returns {ReactElement} The Select.Content component.
+ */
+const SelectContent = (props: ISelectContentProperties) => {
+  const { raw, defaultOpen, children, ...restProps } = props;
+  const { id, states, methods } = useSelect();
+  const { toggleOpen, setContentProps } = methods;
+
+  const mounted = React.useRef(false);
+  const contentRef = React.useRef<HTMLDivElement>(null);
+
+  const contentRect = () => contentRef?.current?.getBoundingClientRect();
+  const bodyRect = (): DOMRect | undefined => {
+    if (typeof document !== "undefined") {
+      return document?.body?.getBoundingClientRect();
+    }
+    return undefined;
+  };
+
+  const positions = {
+    btt: `calc((${states?.triggerProps?.top}px - ${states?.contentProps?.height}px) - (var(--measurement-medium-10) * 2))`,
+    ttb: `calc((${states?.triggerProps?.top}px + ${states?.triggerProps?.height}px) + var(--measurement-medium-10))`,
+  };
+
+  const dimensions = {
+    body_height: bodyRect()?.height ?? 0,
+    content_height: states.contentProps.height,
+    content_bottom: states.contentProps.bottom,
+  };
+
+  const hasEnoughVerticalSpace =
+    dimensions.body_height - dimensions.content_bottom >
+    dimensions.content_height - dimensions.content_height * 0.9;
+
+  React.useEffect(() => {
+    if (defaultOpen && toggleOpen) toggleOpen();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  React.useEffect(() => {
+    mounted.current = true;
+
+    if (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;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [states.open]);
+
+  React.useEffect(() => {
+    if (!states.open) return;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape" && methods.setOpen) {
+        methods.setOpen(false);
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [states.open]);
+
+  if (!states.open) return null;
+  return (
+    <ScrollArea
+      scrollbar
+      as={Content}
+      ref={contentRef}
+      id={id.split("|").at(-1)}
+      role="listbox"
+      tabIndex={-1}
+      aria-labelledby={id.split("|").at(0)}
+      data-state={applyDataState(Boolean(states.open))}
+      data-side={hasEnoughVerticalSpace ? "bottom" : "top"}
+      data-raw={Boolean(raw)}
+      style={{
+        top: hasEnoughVerticalSpace ? positions.ttb : positions.btt,
+        left: `${states?.triggerProps?.left}px`,
+        width: `${states?.triggerProps?.width}px`,
+      }}
+      {...restProps}
+    >
+      {children}
+    </ScrollArea>
+  );
+};
+SelectContent.displayName = "Select.Content";
+
+/**
+ * Select.Item represents a single option within Select.Content.
+ *
+ * **Best practices:**
+ *
+ * - Use a clear and concise label that accurately describes the option.
+ * - Ensure that the item can be selected using only the keyboard (Space or Enter).
+ * - Use the `disabled` prop to prevent selection of unavailable options.
+ * - Provide a meaningful `value` prop that will be stored in the select state upon selection.
+ *
+ * @param {ISelectItemProperties} props - The props for the Select.Item component.
+ * @param {string} props.value - The value associated with this option, stored in the select state on selection.
+ * @param {boolean} props.disabled - Whether the item is disabled and cannot be selected. Defaults to false.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {Function} props.onClick - Optional callback fired when the item is selected via click or keyboard.
+ * @param {ReactNode} props.children - The content to be rendered inside the item.
+ * @returns {ReactElement} The Select.Item component.
+ */
+const SelectItem = (props: ISelectItemProperties) => {
+  const { raw, value, disabled, onClick, children, ...restProps } = props;
+  const { states, methods } = useSelect();
+
+  const isSelected = states?.value === value;
+  const handleSelect = (
+    event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>,
+  ) => {
+    if (disabled) return;
+
+    if (methods.setValue) methods.setValue(value);
+    if (methods.setOpen) methods.setOpen(false);
+    if (onClick) onClick(event);
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLLIElement>) => {
+    if (["Space", "Enter"].includes(event.code || event.key) && !disabled) {
+      event.preventDefault();
+      handleSelect(event);
+    }
+  };
+
+  return (
+    <List
+      role="option"
+      tabIndex={0}
+      aria-disabled={disabled}
+      aria-selected={isSelected}
+      data-orientation="vertical"
+      data-selected={isSelected}
+      data-raw={Boolean(raw)}
+      onClick={handleSelect}
+      onKeyDown={handleKeyDown}
+      {...restProps}
+    >
+      <Item>{children}</Item>
+    </List>
+  );
+};
+SelectItem.displayName = "Select.Item";
+
+Select.Root = SelectRoot;
+Select.Trigger = SelectTrigger;
+Select.Content = SelectContent;
+Select.Item = SelectItem;
+
+export { SelectRoot, Select, SelectTrigger, SelectContent, SelectItem };

package/src/select/styles/index.tsx

@@ -0,0 +1,156 @@
+// select/styles.ts
+import styled from "styled-components";
+import {
+  FieldDefaultStyles,
+  FieldVariantsStyles,
+  FieldSizeStyles,
+  FieldShapeStyles,
+} from "../../field/styles";
+
+export const Wrapper = styled.div`
+  position: relative;
+  width: 100%;
+`;
+
+export const Trigger = styled.button<any>`
+  all: unset;
+  box-sizing: border-box;
+
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--measurement-medium-10);
+
+  ${FieldDefaultStyles}
+  ${FieldVariantsStyles}
+  ${FieldShapeStyles}
+  ${FieldSizeStyles}
+
+
+  cursor: pointer !important;
+`;
+
+export const Label = styled.span<any>`
+  flex: 1;
+  text-align: left;
+  font-weight: 400;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+`;
+
+export const Content = styled.ul<any>`
+  @keyframes select-slide-in-down {
+    0% {
+      opacity: 0;
+      transform: translateY(calc(var(--measurement-small-60) * -1));
+    }
+    100% {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  @keyframes select-slide-in-up {
+    0% {
+      opacity: 0;
+      transform: translateY(var(--measurement-small-60));
+    }
+    100% {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  &[data-raw="false"] {
+    position: fixed;
+    margin: 0;
+    box-sizing: border-box;
+
+    padding: var(--measurement-medium-30);
+
+    list-style: none;
+
+    background-color: var(--body-color);
+    border: var(--measurement-small-10) solid var(--font-color-alpha-10);
+    border-radius: var(--measurement-medium-30);
+
+    z-index: var(--depth-default-100);
+
+    height: auto;
+    max-height: var(--measurement-large-90);
+    overflow-y: auto;
+
+    animation-duration: 0.2s;
+    animation-fill-mode: backwards;
+
+    &[data-side="bottom"] {
+      animation-name: select-slide-in-down;
+    }
+
+    &[data-side="top"] {
+      animation-name: select-slide-in-up;
+    }
+  }
+`;
+
+export const List = styled.li<any>`
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  user-select: none;
+
+  &[data-raw="false"] {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--measurement-medium-10);
+
+    padding: var(--measurement-medium-30);
+    border-radius: var(--measurement-medium-20);
+
+    text-align: left;
+
+    color: var(--font-color);
+
+    outline: none;
+    cursor: pointer;
+
+    transition: all ease-in-out 0.2s;
+
+    &:hover,
+    &:focus,
+    &:active,
+    &:focus-within,
+    &:has(:active) {
+      background-color: var(--contrast-color);
+    }
+
+    &[data-selected="true"] {
+      color: var(--font-color);
+      background-color: var(--contrast-color);
+
+      &:hover,
+      &:focus,
+      &:active {
+        background-color: var(--font-color-alpha-10);
+      }
+    }
+  }
+
+  &[aria-disabled="true"] {
+    cursor: not-allowed;
+    opacity: 0.6;
+  }
+`;
+
+export const Item = styled.span`
+  display: flex;
+  align-items: center;
+  gap: var(--measurement-small-60);
+  flex: 1;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+`;

package/src/shimmer/Shimmer.stories.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 
-import { Shimmer } from "..";
+import { Page, Shimmer } from "..";
 
 const meta = {
   title: "Components/Shimmer",
@@ -9,9 +9,11 @@ const meta = {
   tags: ["autodocs"],
   decorators: [
     (Story) => (
-      <div className="m-medium-30">
-        <Story />
-      </div>
+      <Page>
+        <Page.Content className="p-medium-30">
+          <Story />
+        </Page.Content>
+      </Page>
     ),
   ],
 } satisfies Meta<typeof Shimmer>;

package/src/skeleton/index.tsx

@@ -4,16 +4,17 @@ import React from "react";
 import { SkeletonLoader } from "./styles";
 
 import {
+  ComponentShapeEnum,
   ComponentSizeEnum,
+  type IComponentShape,
   type IComponentSize,
-  type TComponentShape,
 } from "../../../../types";
 
 export interface SkeletonProperties
-  extends IComponentSize,
-    React.ComponentPropsWithRef<"span"> {
-  shape?: TComponentShape;
-}
+  extends
+    IComponentSize,
+    IComponentShape,
+    React.ComponentPropsWithRef<"span"> {}
 
 /**
  * Skeletons are used to convoy a loading state information.
@@ -26,7 +27,7 @@ export interface SkeletonProperties
 export const Skeleton = (props: SkeletonProperties): React.ReactElement => {
   const {
     sizing = ComponentSizeEnum.Medium,
-    shape = "smooth",
+    shape = ComponentShapeEnum.Smooth,
     ...restProps
   } = props;
 

package/src/spinner/Spinner.stories.tsx

@@ -8,6 +8,17 @@ import { Page, Spinner } from "..";
 const meta = {
   title: "Components/Spinner",
   component: Spinner,
+  decorators: [
+    (Story) => (
+      <Page>
+        <Page.Content className="p-medium-30">
+          <div className="flex flex-column align-center justify-center h-100 g-medium-30">
+            <Story />
+          </div>
+        </Page.Content>
+      </Page>
+    ),
+  ],
   tags: ["autodocs"],
 } satisfies Meta<typeof Spinner>;
 export default meta;
@@ -16,12 +27,26 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {},
   render: ({ ...args }) => (
-    <Page>
-      <Page.Content className="g-medium-60 flex align-center justify-center h-100 w-100">
+    <React.Fragment>
+      <div className="flex align-center g-medium-30">
         <Spinner sizing="small" {...args} />
         <Spinner sizing="medium" {...args} />
         <Spinner sizing="large" {...args} />
-      </Page.Content>
-    </Page>
+      </div>
+    </React.Fragment>
+  ),
+};
+export const Variants: Story = {
+  args: {},
+  render: ({ ...args }) => (
+    <React.Fragment>
+      {["circle", "circle-filled"].map((variant) => (
+        <div className="flex align-center g-medium-30" key={variant}>
+          <Spinner sizing="small" variant={variant} />
+          <Spinner sizing="medium" variant={variant} />
+          <Spinner sizing="large" variant={variant} />
+        </div>
+      ))}
+    </React.Fragment>
   ),
 };

package/src/spinner/index.tsx

@@ -2,18 +2,28 @@
 
 import React from "react";
 
-import { RotatingSpinner } from "./styles";
+import { AnimatedSpinner } from "./styles";
 import type { IComponentSize } from "../../../../types";
 
-interface SpinnerProperties extends IComponentSize {}
+type SpinnerVariant = "circle" | "circle-filled";
+
+interface SpinnerProperties extends IComponentSize {
+  variant?: SpinnerVariant;
+}
 
 /**
- * Spinners are used to convoy a loading state information.
+ * Spinners are used to convey a loading state information.
  *
- * @param {TextareaProps} props - The props for the Spinner component.
- * @param {ComponentSizeEnum} props.sizing - The size of the component. Defaults to `medium`.
+ * @param {SpinnerProperties} props - The props for the Spinner component.
+ * @param {string} props.sizing - The size of the component. Defaults to `medium`.
+ * @param {SpinnerVariant} props.variant - The spinner animation variant. Defaults to `circle`.
  * @returns {ReactElement} The Spinner component.
  */
 export const Spinner = (props: SpinnerProperties) => {
-  return <RotatingSpinner data-size={props.sizing ?? "medium"} />;
+  return (
+    <AnimatedSpinner
+      data-variant={props?.variant ?? "circle"}
+      data-size={props?.sizing ?? "medium"}
+    />
+  );
 };