@usefui/components 1.5.3 → 1.7.0

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

@@ -0,0 +1,138 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Avatar, Field, MessageBubble, Page, ScrollArea, Textarea } from "..";
+
+const meta = {
+  title: "Components/MessageBubble",
+  component: MessageBubble,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <Page>
+        <Page.Content className="p-medium-30">
+          <Story />
+        </Page.Content>
+      </Page>
+    ),
+  ],
+} 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: () => (
+    <ScrollArea className="h-100 w-100 flex flex-column g-medium-30 " scrollbar>
+      {(
+        [
+          {
+            variant: "border",
+            side: "left",
+            message: "Hey, how are you doing?",
+          },
+          {
+            variant: "primary",
+            side: "right",
+            message: "All good! What about you?",
+          },
+          {
+            variant: "border",
+            side: "left",
+            message: "Pretty great, thanks for asking",
+          },
+          {
+            variant: "primary",
+            side: "right",
+            message:
+              "Hic dolorum esse magnam sint quibusdam porro reprehenderit, enim, repellendus ipsam, iste est! Deserunt ipsam ullam dolores expedita rem, magni iste eveniet.",
+          },
+          {
+            variant: "hint",
+            side: "right",
+            message: "Hic dolorum esse magnam sint quibusdam.",
+          },
+          {
+            variant: "meta",
+            side: "right",
+            message: "Ipsa nisi fugiat doloribus.",
+          },
+        ] as const
+      ).map(({ variant, side, message }, index) => (
+        <MessageBubble.Root key={index}>
+          <MessageBubble side={side}>
+            {side === "left" && (
+              <Field.Meta variant="hint">
+                <Avatar
+                  sizing="small"
+                  alt="foundation-logo"
+                  src="https://www.untitledui.com/images/avatars/olivia-rhye?fm=webp&q=80"
+                  shape="smooth"
+                >
+                  <Avatar.Badge
+                    alt="foundation-logo"
+                    src="https://www.untitledui.com/logos/images/Layers.jpg"
+                  />
+                </Avatar>
+              </Field.Meta>
+            )}
+
+            <MessageBubble.Content variant={variant} className="fs-medium-20">
+              {message}
+            </MessageBubble.Content>
+            <MessageBubble.Meta createdAt={MOCK_DATE} />
+          </MessageBubble>
+        </MessageBubble.Root>
+      ))}
+    </ScrollArea>
+  ),
+};

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,171 @@
+"use client";
+
+import React from "react";
+import { useMessageBubble, MessageBubbleProvider } from "./hooks";
+
+import {
+  MessageBubbleWrapper,
+  MessageBubbleBadge,
+  MessageBubbleContentWrapper,
+  MessageBubbleMetaWrapper,
+} from "./styles";
+
+import {
+  ComponentShapeEnum,
+  ComponentSizeEnum,
+  ComponentVariantEnum,
+  IComponentShape,
+  IComponentSize,
+  IComponentStyling,
+  IReactChildren,
+  TComponentVariant,
+  TComponentVariantExtended,
+} 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,
+    IComponentShape,
+    IComponentSize,
+    React.HTMLAttributes<HTMLDivElement> {
+  variant?: TComponentVariant | TComponentVariantExtended;
+  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 { sizing, shape, variant, children, raw, ...restProps } = props;
+  const { id, states } = useMessageBubble();
+
+  return (
+    <MessageBubbleBadge
+      data-raw={Boolean(raw)}
+      data-side={states?.side}
+      variant={variant ?? ComponentVariantEnum.Border}
+      shape={shape ?? ComponentShapeEnum.Smooth}
+      sizing={sizing ?? ComponentSizeEnum.Medium}
+      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}`}
+      className="fs-small-60 opacity-default-60"
+      {...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,58 @@
+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;
+
+  &[data-side="left"] {
+    border-top-left-radius: 0 !important;
+  }
+
+  &[data-side="right"] {
+    border-top-right-radius: 0 !important;
+  }
+`;
+
+export const MessageBubbleContentWrapper = styled.div`
+  line-height: 1.3;
+  font-weight: 500;
+  word-break: keep-all;
+  width: 100%;
+
+  * {
+    font-size: inherit !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/OTPField.stories.tsx

@@ -1,6 +1,4 @@
 import React from "react";
-import type { Meta, StoryObj } from "@storybook/react";
-
 import { Field, OTPField, Page } from "..";
 
 const meta = {
@@ -8,13 +6,17 @@ const meta = {
   component: OTPField,
   tags: ["autodocs"],
   decorators: [
-    (Story) => (
-      <div className="m-medium-30">
-        <Story />
-      </div>
+    (Story: any) => (
+      <Page>
+        <Page.Content className="p-medium-30">
+          <div className="flex flex-column align-center justify-center h-100">
+            <Story />
+          </div>
+        </Page.Content>
+      </Page>
     ),
   ],
-} satisfies Meta<typeof OTPField>;
+};
 export default meta;
 
 export const Default = {
@@ -27,24 +29,20 @@ export const Default = {
       setValue(value.trim());
     }, []);
     return (
-      <Page>
-        <Page.Content>
-          <form aria-label="story-form">
-            <Field.Wrapper className="w-100">
-              <Field.Label>Confirmation code</Field.Label>
-              <OTPField length={6} onComplete={handleComplete}>
-                <OTPField.Group>
-                  {Array.from({ length: 6 }).map((_, index) => (
-                    <OTPField.Slot key={index} index={index} />
-                  ))}
-                </OTPField.Group>
-              </OTPField>
+      <form aria-label="story-form" style={{ width: 325 }}>
+        <Field.Wrapper className="w-100">
+          <Field.Label>Confirmation code</Field.Label>
+          <OTPField length={6} onComplete={handleComplete}>
+            <OTPField.Group>
+              {Array.from({ length: 6 }).map((_, index) => (
+                <OTPField.Slot key={index} index={index} />
+              ))}
+            </OTPField.Group>
+          </OTPField>
 
-              {value}
-            </Field.Wrapper>
-          </form>
-        </Page.Content>
-      </Page>
+          {value}
+        </Field.Wrapper>
+      </form>
     );
   },
 };

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

@@ -6,6 +6,11 @@ import { useOTPField, OTPFieldContext } from "./hooks";
 import { OTPCell } from "./styles";
 
 import type { OTPFieldProps, OTPFieldSlotProps } from "./types";
+import {
+  ComponentShapeEnum,
+  ComponentSizeEnum,
+  ComponentVariantEnum,
+} from "../../../../types";
 
 export interface IOTPFieldComposition {
   Slot: typeof OTPFieldSlot;
@@ -26,7 +31,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 +126,7 @@ const OTPField = ({ children, length, onComplete }: OTPFieldProps) => {
      */
     const timeout = setTimeout(
       () => inputRefs.current[targetIndex]?.select(),
-      0
+      0,
     );
 
     return () => clearTimeout(timeout);
@@ -191,6 +196,8 @@ OTPFieldGroup.displayName = "OTPField.Group";
  */
 const OTPFieldSlot = ({
   index,
+  shape,
+  raw,
   ...props
 }: OTPFieldSlotProps & React.InputHTMLAttributes<HTMLInputElement>) => {
   const context = useOTPField();
@@ -209,10 +216,14 @@ 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}
+      data-shape={shape ?? ComponentShapeEnum.Smooth}
+      data-raw={Boolean(raw)}
       autoComplete="one-time-code"
       maxLength={1}
       value={otp[index] || ""}

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

@@ -1,33 +1,131 @@
-import styled from "styled-components";
+import styled, { css } from "styled-components";
 
-export const OTPCell = styled.input`
+const OTPShapeStyles = css`
+  &[data-shape="square"] {
+    border-radius: 0;
+  }
+  &[data-shape="smooth"] {
+    border-radius: var(--measurement-medium-20);
+  }
+  &[data-shape="round"] {
+    border-radius: var(--measurement-large-90);
+    padding-left: var(--measurement-medium-50) !important;
+  }
+`;
+
+const OTPCellDefaultStyles = css`
+  outline: none;
+  cursor: text;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  box-sizing: border-box;
+
+  font-size: var(--fontsize-medium-20);
+
+  padding: 0 var(--measurement-medium-30);
   width: var(--measurement-medium-90);
   height: var(--measurement-medium-90);
-  border: var(--measurement-small-10) solid var(--font-color-alpha-10);
 
-  border-radius: var(--measurement-medium-30);
+  line-height: 1;
+  letter-spacing: calc(
+    var(--fontsize-small-10) - ((var(--fontsize-small-10) * 1.066))
+  );
+
+  border: var(--measurement-small-10) solid transparent;
+
   backdrop-filter: blur(var(--measurement-small-10));
+  color: var(--font-color-alpha-60);
 
-  text-align: center;
-  font-size: var(--fontsize-medium-10);
-  font-weight: 500;
+  transition: all ease-in-out 0.2s;
 
-  color: var(--font-color-alpha-10);
-  text-shadow: 0 0 0 var(--font-color);
+  svg,
+  span,
+  img {
+    opacity: 0.6;
+  }
+
+  &:hover,
+  &:focus,
+  &:active,
+  &:focus-within,
+  &:has(:active) {
+    color: var(--font-color);
+    svg,
+    span,
+    img {
+      opacity: 1;
+    }
+  }
+
+  &::placeholder {
+    color: var(--font-color-alpha-30);
+  }
+
+  &:disabled,
+  &:has(:disabled) {
+    cursor: not-allowed;
+    opacity: 0.6;
+  }
 
   background-color: transparent;
-  transition: all 0.2s ease-in-out;
-  outline: none;
+  border-color: var(--font-color-alpha-10);
 
-  &:focus:not(:active) {
-    background-color: var(--font-color-alpha-10);
+  &:hover,
+  &:focus,
+  &:active,
+  &:focus-within,
+  &:has(:hover),
+  &:has(:active) {
+    border-color: var(--font-color-alpha-20);
   }
 
-  &:hover:not(:active) {
+  &:focus,
+  &:active,
+  &:focus-within,
+  &:has(:active) {
+    box-shadow: 0 0 0 var(--measurement-small-30) var(--alpha-accent-30);
+  }
+
+  background-color: transparent;
+  border-color: var(--font-color-alpha-10);
+
+  &:hover,
+  &:focus,
+  &:active,
+  &:focus-within,
+  &:has(:hover),
+  &:has(:active) {
     border-color: var(--font-color-alpha-20);
   }
 
-  &::placeholder {
-    opacity: var(--opacity-default-10);
+  &:focus,
+  &:active,
+  &:focus-within,
+  &:has(:active) {
+    box-shadow: 0 0 0 var(--measurement-small-30) var(--font-color-alpha-10);
+  }
+
+  &[data-error="true"] {
+    color: var(--color-red);
+    border-color: var(--alpha-red-10);
+
+    &:hover,
+    &:focus,
+    &:active,
+    &:focus-within,
+    &:has(:hover),
+    &:has(:active) {
+      background-color: var(--alpha-red-10);
+      box-shadow: 0 0 0 var(--measurement-small-30) var(--alpha-red-10);
+    }
+  }
+`;
+
+export const OTPCell = styled.input`
+  &[data-raw="false"] {
+    ${OTPCellDefaultStyles}
+    ${OTPShapeStyles}
   }
 `;