@usefui/components 1.5.2 → 1.6.0

package/src/dialog/hooks/index.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import React, { useState, createContext, useContext } from "react";
 import { IReactChildren, IComponentAPI } from "../../../../../types";
 
@@ -9,7 +11,9 @@ const defaultComponentAPI = {
 const DialogContext = createContext<IComponentAPI>(defaultComponentAPI);
 export const useDialog = () => useContext(DialogContext);
 
-export const DialogProvider = ({ children }: IReactChildren): JSX.Element => {
+export const DialogProvider = ({
+  children,
+}: IReactChildren): React.JSX.Element => {
   const context = useDialogProvider();
 
   return (

package/src/dropdown/hooks/index.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import React from "react";
 import { IReactChildren, IComponentAPI } from "../../../../../types";
 
@@ -22,7 +24,7 @@ export const useDropdownMenu = () => React.useContext(DropdownMenuContext);
 
 export const DropdownMenuProvider = ({
   children,
-}: IReactChildren): JSX.Element => {
+}: IReactChildren): React.JSX.Element => {
   const context = useDropdownMenuProvider();
 
   return (

package/src/dropdown/index.tsx

@@ -14,18 +14,15 @@ import {
 } from "../../../../types";
 
 export interface IDropdownContentProperties
-  extends IComponentStyling,
-    IComponentSize,
-    React.ComponentPropsWithRef<"ul"> {
+  extends IComponentStyling, IComponentSize, React.ComponentPropsWithRef<"ul"> {
   defaultOpen?: boolean;
 }
 export interface IDropdownItemProperties
-  extends IComponentStyling,
-    React.ComponentProps<"li"> {
+  extends IComponentStyling, React.ComponentProps<"li"> {
   radio?: boolean;
   disabled?: boolean;
   onClick?: (
-    event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>
+    event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>,
   ) => void;
   onKeyDown?: (event: React.KeyboardEvent<HTMLLIElement>) => void;
 }
@@ -52,7 +49,7 @@ export interface IDropdownComposition {
  * @returns {ReactElement} The DropdownMenu component.
  */
 const DropdownMenu = ({ children }: React.ComponentProps<"div">) => {
-  const DropdownContentRef = React.useRef(null);
+  const DropdownContentRef = React.useRef<HTMLDivElement | null>(null);
   const { states, methods } = useDropdownMenu();
   const { toggleOpen } = methods;
 
@@ -60,7 +57,10 @@ const DropdownMenu = ({ children }: React.ComponentProps<"div">) => {
     if (states.open && toggleOpen) toggleOpen();
   };
 
-  useClickOutside(DropdownContentRef, handleClickOutside);
+  useClickOutside(
+    DropdownContentRef as React.RefObject<HTMLElement>,
+    handleClickOutside,
+  );
   useDisabledScroll(Boolean(states.open));
   return <RootWrapper ref={DropdownContentRef}>{children}</RootWrapper>;
 };
@@ -266,7 +266,7 @@ const DropdownMenuItem = (props: IDropdownItemProperties) => {
     click: (
       event:
         | React.MouseEvent<HTMLLIElement>
-        | React.KeyboardEvent<HTMLLIElement>
+        | React.KeyboardEvent<HTMLLIElement>,
     ) => {
       if (onClick) onClick(event);
     },

package/src/field/hooks/index.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import React, { createContext, useContext } from "react";
 import { IReactChildren, IComponentAPI } from "../../../../../types";
 
@@ -9,7 +11,9 @@ const defaultComponentAPI = {
 const FieldContext = createContext<IComponentAPI>(defaultComponentAPI);
 export const useField = () => useContext(FieldContext);
 
-export const FieldProvider = ({ children }: IReactChildren): JSX.Element => {
+export const FieldProvider = ({
+  children,
+}: IReactChildren): React.JSX.Element => {
   const context = useFieldProvider();
 
   return (

package/src/field/styles/index.ts

@@ -6,6 +6,7 @@ export const FieldDefaultStyles = css`
   display: flex;
   align-items: center;
   justify-content: center;
+  box-sizing: border-box;
 
   font-size: var(--fontsize-medium-20);
 

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./dialog";
 export * from "./divider";
 export * from "./dropdown";
 export * from "./field";
+export * from "./message-bubble";
 export * from "./otp-field";
 export * from "./overlay";
 export * from "./page";
@@ -18,6 +19,7 @@ export * from "./portal";
 export * from "./privacy-field";
 export * from "./resizable";
 export * from "./sheet";
+export * from "./shimmer";
 export * from "./scrollarea";
 export * from "./spinner";
 export * from "./skeleton";
@@ -28,6 +30,7 @@ export * from "./text-area";
 export * from "./toggle";
 export * from "./toolbar";
 export * from "./tooltip";
+export * from "./tree";
 
 export { useAccordion } from "./accordion/hooks";
 export { useCheckbox } from "./checkbox/hooks";
@@ -39,3 +42,6 @@ export { useSheet } from "./sheet/hooks";
 export { useSwitch } from "./switch/hooks";
 export { useTabs } from "./tabs/hooks";
 export { useToolbar } from "./toolbar/hooks";
+export { useMessageBubble } from "./message-bubble/hooks";
+export { useTree } from "./tree/hooks/tree-provider";
+export { useTreeNode } from "./tree/hooks/tree-node-provider";

package/src/message-bubble/MessageBubble.stories.tsx

@@ -0,0 +1,91 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { MessageBubble } from "..";
+
+const meta = {
+  title: "Components/MessageBubble",
+  component: MessageBubble,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="m-medium-30">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof MessageBubble>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const MOCK_DATE = new Date("2026-03-17T13:00:00Z");
+const MOCK_MESSAGE = "Hey, how are you doing?";
+
+export const Default: Story = {
+  args: {
+    side: "left",
+    raw: false,
+  },
+  argTypes: {
+    side: {
+      options: ["left", "right"],
+      control: { type: "radio" },
+    },
+    raw: {
+      control: { type: "boolean" },
+    },
+  },
+  render: ({ ...args }) => (
+    <MessageBubble.Root>
+      <MessageBubble {...args}>
+        <MessageBubble.Content>{MOCK_MESSAGE}</MessageBubble.Content>
+        <MessageBubble.Meta createdAt={MOCK_DATE} />
+      </MessageBubble>
+    </MessageBubble.Root>
+  ),
+};
+
+export const Left: Story = {
+  render: () => (
+    <MessageBubble.Root>
+      <MessageBubble side="left">
+        <MessageBubble.Content>{MOCK_MESSAGE}</MessageBubble.Content>
+        <MessageBubble.Meta createdAt={MOCK_DATE} />
+      </MessageBubble>
+    </MessageBubble.Root>
+  ),
+};
+
+export const Right: Story = {
+  render: () => (
+    <MessageBubble.Root>
+      <MessageBubble side="right">
+        <MessageBubble.Content>{MOCK_MESSAGE}</MessageBubble.Content>
+        <MessageBubble.Meta createdAt={MOCK_DATE} />
+      </MessageBubble>
+    </MessageBubble.Root>
+  ),
+};
+
+export const Conversation: Story = {
+  render: () => (
+    <React.Fragment>
+      {(
+        [
+          { side: "left", message: "Hey, how are you doing?" },
+          { side: "right", message: "All good! What about you?" },
+          { side: "left", message: "Pretty great, thanks for asking 🐻" },
+          { side: "right", message: "Glad to hear it! 🐻❄️" },
+        ] as const
+      ).map(({ side, message }, index) => (
+        <MessageBubble.Root key={index}>
+          <MessageBubble side={side}>
+            <MessageBubble.Content>{message}</MessageBubble.Content>
+            <MessageBubble.Meta createdAt={MOCK_DATE} />
+          </MessageBubble>
+        </MessageBubble.Root>
+      ))}
+    </React.Fragment>
+  ),
+};

package/src/message-bubble/hooks/index.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+import React, { useState, createContext, useContext } from "react";
+
+import { IReactChildren, IComponentAPI } from "../../../../../types";
+import { MessageBubbleSide } from "../";
+
+const defaultComponentAPI = {
+  id: "",
+  states: {},
+  methods: {},
+};
+const MessageBubbleContext = createContext<IComponentAPI>(defaultComponentAPI);
+export const useMessageBubble = () => useContext(MessageBubbleContext);
+
+export const MessageBubbleProvider = ({
+  children,
+}: IReactChildren): React.JSX.Element => {
+  const context = useMessageBubbleProvider();
+
+  return (
+    <MessageBubbleContext.Provider value={context}>
+      {children}
+    </MessageBubbleContext.Provider>
+  );
+};
+
+function useMessageBubbleProvider(): IComponentAPI {
+  const [side, setSide] = useState<MessageBubbleSide | null>(null);
+  const MessageBubbleId = React.useId();
+
+  return {
+    id: MessageBubbleId,
+    states: {
+      side,
+    },
+    methods: {
+      applySide: (side: MessageBubbleSide): string | void => setSide(side),
+    },
+  };
+}

package/src/message-bubble/index.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+import React from "react";
+import { useMessageBubble, MessageBubbleProvider } from "./hooks";
+
+import {
+  MessageBubbleWrapper,
+  MessageBubbleBadge,
+  MessageBubbleContentWrapper,
+  MessageBubbleMetaWrapper,
+} from "./styles";
+
+import { IComponentStyling, IReactChildren } from "../../../../types";
+
+export type MessageBubbleSide = "left" | "right";
+
+export interface IMessageBubbleContext {
+  side: MessageBubbleSide;
+}
+
+export interface IMessageBubbleProperties
+  extends IComponentStyling, React.HTMLAttributes<HTMLDivElement> {
+  side: MessageBubbleSide;
+}
+
+export interface IMessageBubbleContentProperties
+  extends IComponentStyling, React.HTMLAttributes<HTMLDivElement> {
+  children: string;
+}
+
+export interface IMessageBubbleMetaProperties
+  extends IComponentStyling, React.HTMLAttributes<HTMLDivElement> {
+  createdAt: Date;
+}
+
+const MessageBubbleRoot = ({ children }: IReactChildren) => {
+  return <MessageBubbleProvider>{children}</MessageBubbleProvider>;
+};
+MessageBubbleRoot.displayName = "MessageBubble.Root";
+
+/**
+ * MessageBubble is used to display a chat message with an optional side and raw layout.
+ *
+ * **Best practices:**
+ *
+ * - Always wrap MessageBubble inside a MessageBubble.Root to provide the necessary context.
+ * - Use `side` to visually distinguish between sent and received messages.
+ * - Pair with MessageBubble.Content and MessageBubble.Meta for a complete message layout.
+ *
+ * @param {IMessageBubbleProperties} props - The props for the MessageBubble component.
+ * @param {"left" | "right"} props.side - The side the bubble is aligned to. Propagated to all child compounds via context.
+ * @param {boolean} props.raw - When true, removes default styling for custom layouts.
+ * @param {ReactNode} props.children - The content to be rendered inside the bubble.
+ * @returns {ReactElement} The MessageBubble component.
+ */
+const MessageBubble = (props: IMessageBubbleProperties) => {
+  const { side, raw, children, ...restProps } = props;
+  const { methods } = useMessageBubble();
+
+  React.useEffect(() => {
+    if (side && methods?.applySide) methods.applySide(side);
+  }, [side]);
+
+  return (
+    <MessageBubbleWrapper
+      data-raw={Boolean(raw)}
+      data-side={side}
+      aria-label={restProps["aria-label"] ?? `message-bubble-${side}`}
+      {...restProps}
+    >
+      {children}
+    </MessageBubbleWrapper>
+  );
+};
+MessageBubble.displayName = "MessageBubble";
+
+/**
+ * MessageBubble.Content is used to display the text or rich content of the message.
+ *
+ * **Best practices:**
+ *
+ * - Place MessageBubble.Content inside a MessageBubble to inherit the correct side context.
+ * - Avoid nesting interactive elements inside the content that may conflict with bubble focus management.
+ *
+ * @param {IMessageBubbleContentProperties} props - The props for the MessageBubble.Content component.
+ * @param {boolean} props.raw - When true, removes default styling for custom layouts.
+ * @param {ReactNode} props.children - The message text or rich content to render.
+ * @returns {ReactElement} The MessageBubble.Content component.
+ */
+const MessageBubbleContent = (props: IMessageBubbleContentProperties) => {
+  const { children, raw, ...restProps } = props;
+  const { id, states } = useMessageBubble();
+
+  return (
+    <MessageBubbleBadge
+      variant="secondary"
+      data-raw={Boolean(raw)}
+      data-side={states?.side}
+      aria-label={`message-bubble-content-${id}`}
+      {...restProps}
+    >
+      <MessageBubbleContentWrapper>{children}</MessageBubbleContentWrapper>
+    </MessageBubbleBadge>
+  );
+};
+MessageBubbleContent.displayName = "MessageBubble.Content";
+
+/**
+ * MessageBubble.Meta is used to display metadata associated with the message, such as its timestamp.
+ *
+ * **Best practices:**
+ *
+ * - Always provide a valid `createdAt` date for accurate timestamp display.
+ * - Place MessageBubble.Meta after MessageBubble.Content for a natural reading flow.
+ * - The side is automatically inherited from context — do not pass it manually.
+ *
+ * @param {IMessageBubbleMetaProperties} props - The props for the MessageBubble.Meta component.
+ * @param {Date} props.createdAt - The date the message was created. Formatted as medium date and short time.
+ * @param {boolean} props.raw - When true, removes default styling for custom layouts.
+ * @returns {ReactElement} The MessageBubble.Meta component.
+ */
+const MessageBubbleMeta = (props: IMessageBubbleMetaProperties) => {
+  const { createdAt, raw, ...restProps } = props;
+  const { states } = useMessageBubble();
+
+  const formattedDate = new Intl.DateTimeFormat("en-US", {
+    dateStyle: "medium",
+    timeStyle: "short",
+  }).format(createdAt);
+
+  return (
+    <MessageBubbleMetaWrapper
+      data-raw={Boolean(raw)}
+      data-side={states?.side}
+      aria-label={`message-bubble-meta-${states?.side}`}
+      {...restProps}
+    >
+      {formattedDate}
+    </MessageBubbleMetaWrapper>
+  );
+};
+MessageBubbleMeta.displayName = "MessageBubble.Meta";
+
+MessageBubble.Root = MessageBubbleRoot;
+MessageBubble.Content = MessageBubbleContent;
+MessageBubble.Meta = MessageBubbleMeta;
+
+export {
+  MessageBubble,
+  MessageBubbleRoot,
+  MessageBubbleContent,
+  MessageBubbleMeta,
+};

package/src/message-bubble/styles/index.ts

@@ -0,0 +1,61 @@
+import styled from "styled-components";
+import { Badge, IBadgeProperties } from "../../";
+
+export const MessageBubbleWrapper = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--measurement-medium-10);
+
+  &[data-side="right"] {
+    align-items: flex-end;
+  }
+
+  &[data-side="left"] {
+    align-items: flex-start;
+  }
+`;
+
+export const MessageBubbleBadge: React.FC<IBadgeProperties> = styled(Badge)`
+  position: relative;
+  max-width: var(--measurement-large-90);
+  width: 100%;
+  justify-self: flex-end;
+  padding: var(--measurement-medium-30) var(--measurement-medium-50) !important;
+  border-radius: var(--measurement-medium-60) !important;
+
+  &[data-side="left"] {
+    background-color: var(--contrast-color) !important;
+    border-bottom-left-radius: 0 !important;
+  }
+
+  &[data-side="right"] {
+    background-color: var(--font-color-alpha-10) !important;
+    border-bottom-right-radius: 0 !important;
+  }
+`;
+
+export const MessageBubbleContentWrapper = styled.div`
+  line-height: 1.5;
+  font-weight: 500;
+  word-break: keep-all;
+  width: 100%;
+
+  * {
+    font-size: var(--fontsize-medium-10) !important;
+  }
+`;
+
+export const MessageBubbleMetaWrapper = styled.div`
+  display: flex;
+  align-items: center;
+  gap: var(--measurement-medium-10);
+  width: 100%;
+
+  &[data-side="right"] {
+    justify-content: flex-end;
+  }
+
+  &[data-side="left"] {
+    justify-content: flex-start;
+  }
+`;

package/src/otp-field/hooks/index.tsx

@@ -1,9 +1,11 @@
+"use client";
+
 import React from "react";
 
 import type { OTPFieldContextType } from "../types";
 
 export const OTPFieldContext = React.createContext<OTPFieldContextType | null>(
-  null
+  null,
 );
 export const useOTPField = () => {
   const context = React.useContext(OTPFieldContext);

package/src/otp-field/index.tsx

@@ -26,7 +26,7 @@ const OTPField = ({ children, length, onComplete }: OTPFieldProps) => {
 
   const inputRefs = React.useRef<(HTMLInputElement | null)[]>([]);
   const [otp, setOtp] = React.useState<string[]>(
-    Array.from({ length: defaultLength }, () => "")
+    Array.from({ length: defaultLength }, () => ""),
   );
   const [activeIndex, setActiveIndex] = React.useState<number>(0);
 
@@ -121,7 +121,7 @@ const OTPField = ({ children, length, onComplete }: OTPFieldProps) => {
      */
     const timeout = setTimeout(
       () => inputRefs.current[targetIndex]?.select(),
-      0
+      0,
     );
 
     return () => clearTimeout(timeout);
@@ -209,7 +209,9 @@ const OTPFieldSlot = ({
 
   return (
     <OTPCell
-      ref={(el) => (inputRefs.current[index] = el)}
+      ref={(el) => {
+        inputRefs.current[index] = el;
+      }}
       type="text"
       data-testid="otp-field-slot"
       data-active={activeIndex === index}

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,95 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Shimmer } from "..";
+
+const meta = {
+  title: "Components/Shimmer",
+  component: Shimmer,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="m-medium-30">
+        <Story />
+      </div>
+    ),
+  ],
+} 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>
+  ),
+};