@usefui/components 1.5.3 → 1.7.0

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/sheet/hooks/index.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import React from "react";
 import { IReactChildren } from "../../../../../types";
 
@@ -15,7 +17,9 @@ const SheetContext = React.createContext<IContextProperties>({
 });
 export const useSheet = () => React.useContext(SheetContext);
 
-export const SheetProvider = ({ children }: IReactChildren): JSX.Element => {
+export const SheetProvider = ({
+  children,
+}: IReactChildren): React.JSX.Element => {
   const context = useSheetProvider();
 
   return (

package/src/shimmer/Shimmer.stories.tsx

@@ -0,0 +1,97 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Page, Shimmer } from "..";
+
+const meta = {
+  title: "Components/Shimmer",
+  component: Shimmer,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <Page>
+        <Page.Content className="p-medium-30">
+          <Story />
+        </Page.Content>
+      </Page>
+    ),
+  ],
+} satisfies Meta<typeof Shimmer>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: "Loading your content…",
+    duration: 2,
+    spread: 200,
+    shimmerColor: "var(--font-color-alpha-60)",
+    baseColor: "var(--font-color-alpha-30)",
+  },
+  argTypes: {
+    duration: {
+      control: { type: "number", min: 0.5, max: 10, step: 0.5 },
+    },
+    spread: {
+      control: { type: "number", min: 100, max: 500, step: 50 },
+    },
+    shimmerColor: {
+      control: { type: "color" },
+    },
+    baseColor: {
+      control: { type: "color" },
+    },
+  },
+  render: ({ ...args }) => <Shimmer {...args} />,
+};
+
+export const SlowAnimation: Story = {
+  render: ({ ...args }) => (
+    <Shimmer duration={6} spread={200}>
+      Slowly shimmering text…
+    </Shimmer>
+  ),
+};
+
+export const FastAnimation: Story = {
+  render: ({ ...args }) => (
+    <Shimmer duration={0.8} spread={200}>
+      Rapidly shimmering text…
+    </Shimmer>
+  ),
+};
+
+export const WideSpread: Story = {
+  render: ({ ...args }) => (
+    <Shimmer spread={400}>Wide spread shimmer effect</Shimmer>
+  ),
+};
+
+export const CustomColors: Story = {
+  render: ({ ...args }) => (
+    <Shimmer
+      shimmerColor="var(--alpha-blue-80)"
+      baseColor="var(--alpha-blue-30)"
+    >
+      Custom branded shimmer
+    </Shimmer>
+  ),
+};
+
+export const Group: Story = {
+  render: ({ ...args }) => (
+    <React.Fragment>
+      {[
+        "Fetching user profile…",
+        "Loading dashboard…",
+        "Syncing your data…",
+        "Preparing your workspace…",
+      ].map((label) => (
+        <div key={label} className="m-b-medium-30">
+          <Shimmer>{label}</Shimmer>
+        </div>
+      ))}
+    </React.Fragment>
+  ),
+};

package/src/shimmer/index.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import React from "react";
+import { TextShimmerWrapper } from "./styles";
+import { IComponentStyling } from "../../../../types";
+
+const DEFAULT_DURATION = 2;
+const DEFAULT_SPREAD = 200;
+const DEFAULT_SHIMMER_COLOR = "var(--font-color-alpha-60)";
+const DEFAULT_BASE_COLOR = "var(--font-color-alpha-30)";
+
+export interface ITextShimmerProperties
+  extends IComponentStyling, React.HTMLAttributes<HTMLSpanElement> {
+  duration?: number;
+  spread?: number;
+  shimmerColor?: string;
+  baseColor?: string;
+}
+
+/**
+ * Shimmer applies an animated shimmer gradient effect to inline text content.
+ *
+ * **Best practices:**
+ *
+ * - Use to indicate loading states for text content.
+ * - Prefer CSS custom properties for `shimmerColor` and `baseColor` to stay consistent with your design tokens.
+ * - Avoid using on large blocks of text; favour short labels or headings.
+ *
+ * @param {ITextShimmerProperties} props - The props for the Shimmer component.
+ * @param {ReactNode} props.children - The text content to apply the shimmer effect to.
+ * @param {boolean} props.raw - Whether the component is unstyled.
+ * @param {number} props.duration - Animation cycle duration in seconds. Defaults to 2.
+ * @param {number} props.spread - Gradient spread width as a percentage. Defaults to 200.
+ * @param {string} props.shimmerColor - Highlight color of the shimmer. Defaults to `--font-color-alpha-60`.
+ * @param {string} props.baseColor - Base text gradient color. Defaults to `--font-color-alpha-30`.
+ * @returns {ReactElement} The Shimmer component.
+ */
+export const Shimmer = (props: ITextShimmerProperties) => {
+  const {
+    children,
+    raw,
+    duration = DEFAULT_DURATION,
+    spread = DEFAULT_SPREAD,
+    shimmerColor = DEFAULT_SHIMMER_COLOR,
+    baseColor = DEFAULT_BASE_COLOR,
+    ...restProps
+  } = props;
+
+  return (
+    <TextShimmerWrapper
+      data-raw={Boolean(raw)}
+      data-duration={duration}
+      data-spread={spread}
+      data-shimmer-color={shimmerColor}
+      data-base-color={baseColor}
+      aria-label={restProps["aria-label"] ?? "shimmer-text"}
+      {...restProps}
+    >
+      {children}
+    </TextShimmerWrapper>
+  );
+};
+
+Shimmer.displayName = "Shimmer";

package/src/shimmer/styles/index.ts

@@ -0,0 +1,33 @@
+import styled, { keyframes } from "styled-components";
+
+const shimmer = keyframes`
+  0% {
+    background-position: 200% center;
+  }
+  100% {
+    background-position: -200% center;
+  }
+`;
+
+export const TextShimmerWrapper = styled.span<{
+  "data-duration": number;
+  "data-spread": number;
+  "data-shimmer-color": string;
+  "data-base-color": string;
+}>`
+  background: linear-gradient(
+    90deg,
+    ${({ "data-base-color": baseColor }) => baseColor} 0%,
+    ${({ "data-shimmer-color": shimmerColor }) => shimmerColor} 40%,
+    ${({ "data-base-color": baseColor }) => baseColor} 60%,
+    ${({ "data-base-color": baseColor }) => baseColor} 100%
+  );
+  background-size: ${({ "data-spread": spread }) => spread}% auto;
+  background-clip: text;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  color: transparent;
+  animation: ${shimmer} ${({ "data-duration": duration }) => duration}s linear
+    infinite;
+  display: inline-block;
+`;