@usefui/components 1.5.1

package/src/field/index.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+import React from "react";
+import { FieldProvider, useField } from "./hooks";
+import { Fieldset, Sup, Input, Label, Def } from "./styles";
+import {
+  IReactChildren,
+  IComponentStyling,
+  ComponentSizeEnum,
+  IComponentSize,
+  ComponentVariantEnum,
+  IComponentVariant,
+} from "../../../../types";
+
+export enum MetaVariantEnum {
+  Default = "default",
+  Hint = "hint",
+  Emphasis = "emphasis",
+  Error = "error",
+}
+
+export type TMetaVariant = "default" | "hint" | "emphasis" | "error";
+
+export interface IField
+  extends React.ComponentProps<"input">,
+    IComponentSize,
+    IComponentVariant,
+    IComponentStyling {
+  hint?: string;
+  error?: string;
+}
+export interface IFieldLabel
+  extends React.ComponentProps<"label">,
+    IComponentStyling {
+  optional?: boolean;
+}
+export interface IFieldMeta
+  extends React.ComponentProps<"small">,
+    IComponentStyling {
+  variant?: TMetaVariant;
+}
+export interface IFieldComposition {
+  Root: typeof FieldRoot;
+  Wrapper: typeof FieldWrapper;
+  Label: typeof FieldLabel;
+  Meta: typeof FieldMeta;
+}
+
+/**
+ * Fields are input element that provides additional functionality such as error and hint messages.
+ *
+ * **Best practices:**
+ *
+ * - Provide clear and descriptive labels for all input elements.
+ * - Ensure that error and hint messages are visible and easily identifiable by users.
+ *
+ * @param {IField} props - The props for the Field component.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {ComponentSizeEnum} props.sizing - The size of the component. Defaults to `medium`.
+ * @param {string} props.variant - The style definition used by the component.
+ * @param {string} props.error - The error message to display.
+ * @param {string} props.hint - The hint message to display.
+ * @returns {ReactElement} The Field component.
+ */
+const Field = (props: IField) => {
+  const {
+    raw,
+    sizing = ComponentSizeEnum.Medium,
+    variant = ComponentVariantEnum.Primary,
+    error,
+    hint,
+    ...restProps
+  } = props;
+
+  const metaId = React.useId();
+  const { id } = useField();
+
+  return (
+    <>
+      <Input
+        id={id}
+        aria-invalid={!!error}
+        aria-describedby={metaId}
+        aria-errormessage={error}
+        data-error={Boolean(error)}
+        data-variant={variant}
+        data-size={sizing}
+        data-raw={Boolean(raw)}
+        {...restProps}
+      />
+      {(error ?? hint) && (
+        <FieldMeta
+          raw={raw}
+          data-variant={error ? MetaVariantEnum.Error : MetaVariantEnum.Hint}
+        >
+          {error ?? hint}
+        </FieldMeta>
+      )}
+    </>
+  );
+};
+Field.displayName = "Field";
+
+const FieldRoot = ({ children }: IReactChildren) => {
+  return <FieldProvider>{children}</FieldProvider>;
+};
+FieldRoot.displayName = "Field.Root";
+
+const FieldWrapper = ({
+  children,
+  ...restProps
+}: IReactChildren & React.ComponentProps<"fieldset">) => {
+  return <Fieldset {...restProps}>{children}</Fieldset>;
+};
+FieldWrapper.displayName = "Field.Wrapper";
+
+/**
+ * Labels are component used to describe the expected value of an input.
+ *
+ * **Best practices:**
+ *
+ * - Provide a clear and descriptive label for each input.
+ * - The `required` criteria of an input must be reflected in the label.
+ *
+ * @param {IFieldLabel} props - The props for the Field.Label component.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {boolean} props.optional - Whether the form field is required or not.
+ * @param {string} props.children - The label text.
+ * @returns {ReactElement} The Field.Label component.
+ */
+const FieldLabel = (props: IFieldLabel) => {
+  const { raw, optional = false, children, ...restProps } = props;
+  const { id } = useField();
+
+  return (
+    <Label htmlFor={id} data-raw={Boolean(raw)} {...restProps}>
+      {children}
+      {!optional && <Sup>*</Sup>}
+    </Label>
+  );
+};
+FieldLabel.displayName = "Field.Label";
+
+/**
+ * Meta are component used to bring more context about an input's usage.
+ *
+ * @param {IFieldMeta} props - The props for the Field.Meta component.
+ * @param {boolean} props.raw - Define whether the component is styled or not.
+ * @param {TMetaVariant} props.variant - The style definition used by the component.
+ * @param {string} props.children - The meta text.
+ * @returns {ReactElement} The Field.Meta component.
+ */
+const FieldMeta = (props: IFieldMeta) => {
+  const {
+    raw,
+    variant = MetaVariantEnum.Emphasis,
+    children,
+    ...restProps
+  } = props;
+
+  const metaId = React.useId();
+  const { id } = useField();
+
+  return (
+    <Def
+      id={metaId}
+      aria-details={id}
+      data-variant={variant}
+      data-raw={Boolean(raw)}
+      {...restProps}
+    >
+      {children}
+    </Def>
+  );
+};
+FieldMeta.displayName = "Field.Meta";
+
+Field.Root = FieldRoot;
+Field.Wrapper = FieldWrapper;
+Field.Label = FieldLabel;
+Field.Meta = FieldMeta;
+
+export { Field, FieldRoot, FieldWrapper, FieldLabel, FieldMeta };

package/src/field/styles/index.ts

@@ -0,0 +1,166 @@
+import styled, { css } from "styled-components";
+
+const FieldDefaultStyles = css`
+  outline: none;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  font-size: var(--fontsize-small-80);
+  font-weight: 500;
+  line-height: 1.1;
+  letter-spacing: calc(
+    var(--fontsize-small-10) - ((var(--fontsize-small-10) * 1.066))
+  );
+
+  border: var(--measurement-small-10) solid transparent;
+  border-radius: var(--measurement-medium-30);
+  backdrop-filter: blur(var(--measurement-small-10));
+  color: var(--font-color-alpha-60);
+  width: fit-content;
+  height: fit-content;
+
+  transition: all ease-in-out 0.2s;
+
+  svg,
+  span,
+  img {
+    opacity: 0.6;
+  }
+
+  &:hover,
+  &:focus,
+  &:active {
+    color: var(--font-color);
+
+    svg,
+    span,
+    img {
+      opacity: 1;
+    }
+  }
+  &::placeholder {
+    color: var(--font-color-alpha-30);
+  }
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.6;
+  }
+`;
+const FieldVariantsStyles = css`
+  &[data-variant="primary"] {
+    background-color: var(--font-color-alpha-10);
+
+    &[data-error="true"] {
+      color: var(--color-red);
+      background-color: var(--alpha-red-10);
+      border-color: var(--alpha-red-10);
+    }
+  }
+
+  &[data-variant="secondary"] {
+    background-color: transparent;
+    border-color: var(--font-color-alpha-10);
+
+    &:hover,
+    &:focus,
+    &:active {
+      background-color: var(--font-color-alpha-10);
+    }
+
+    &[data-error="true"] {
+      color: var(--color-red);
+      border-color: var(--alpha-red-10);
+
+      &:hover,
+      &:focus,
+      &:active {
+        background-color: var(--alpha-red-10);
+      }
+    }
+  }
+
+  &[data-variant="ghost"] {
+    padding: 0;
+    border: none;
+    background-color: transparent;
+    min-width: fit-content;
+    min-height: var(--measurement-medium-60);
+    color: var(--font-color-alpha-60);
+
+    &:hover,
+    &:focus,
+    &:active {
+      color: var(--font-color);
+    }
+
+    &[data-error="true"] {
+      color: var(--color-red);
+    }
+  }
+`;
+const FieldSizeStyles = css`
+  &[data-size="small"] {
+    gap: var(--measurement-medium-10);
+    padding: 0 var(--measurement-medium-30);
+    min-width: var(--measurement-medium-60);
+    min-height: var(--measurement-medium-80);
+  }
+  &[data-size="medium"] {
+    gap: var(--measurement-medium-30);
+    padding: 0 var(--measurement-medium-30);
+    min-width: var(--measurement-medium-90);
+    min-height: var(--measurement-medium-90);
+    width: fit-content;
+  }
+  &[data-size="large"] {
+    padding: var(--measurement-medium-20) var(--measurement-medium-40);
+    min-width: var(--measurement-medium-90);
+    min-height: var(--measurement-medium-90);
+  }
+`;
+
+export const Fieldset = styled.fieldset<any>`
+  all: unset;
+  display: grid;
+  gap: var(--measurement-medium-10);
+`;
+export const Sup = styled.sup`
+  color: var(--color-red);
+`;
+export const Input = styled.input<any>`
+  &[data-raw="false"] {
+    ${FieldDefaultStyles}
+    ${FieldVariantsStyles}
+    ${FieldSizeStyles}
+
+  &[data-error="true"] {
+      &::placeholder {
+        color: var(--alpha-red-30);
+      }
+    }
+  }
+`;
+export const Label = styled.label<any>`
+  &[data-raw="false"] {
+    font-weight: 500;
+    line-height: 1.1;
+    letter-spacing: calc(
+      var(--fontsize-small-10) - ((var(--fontsize-small-10) * 1.066))
+    );
+  }
+`;
+export const Def = styled.dfn<any>`
+  &[data-raw="false"] {
+    font-style: normal;
+    font-size: var(--fontsize-medium-10);
+
+    &[data-variant="hint"] {
+      color: var(--font-color-alpha-30);
+    }
+    &[data-variant="error"] {
+      color: var(--color-red);
+    }
+  }
+`;

package/src/index.ts

@@ -0,0 +1,33 @@
+export * from "./accordion";
+export * from "./avatar";
+export * from "./badge";
+export * from "./button";
+export * from "./checkbox";
+export * from "./collapsible";
+export * from "./dialog";
+export * from "./divider";
+export * from "./dropdown";
+export * from "./field";
+export * from "./otp-field";
+export * from "./overlay";
+export * from "./page";
+export * from "./portal";
+export * from "./sheet";
+export * from "./scrollarea";
+export * from "./switch";
+export * from "./table";
+export * from "./tabs";
+export * from "./toggle";
+export * from "./toolbar";
+export * from "./tooltip";
+
+export { useAccordion } from "./accordion/hooks";
+export { useCheckbox } from "./checkbox/hooks";
+export { useCollapsible } from "./collapsible/hooks";
+export { useDialog } from "./dialog/hooks";
+export { useDropdownMenu } from "./dropdown/hooks";
+export { useField } from "./field/hooks";
+export { useSheet } from "./sheet/hooks";
+export { useSwitch } from "./switch/hooks";
+export { useTabs } from "./tabs/hooks";
+export { useToolbar } from "./toolbar/hooks";

package/src/otp-field/OTPField.stories.tsx

@@ -0,0 +1,50 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Field, OTPField, Page } from "..";
+
+const meta = {
+  title: "Components/OTPField",
+  component: OTPField,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="m-medium-30">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof OTPField>;
+export default meta;
+
+export const Default = {
+  args: {},
+  argTypes: {},
+  render: () => {
+    const [value, setValue] = React.useState("");
+
+    const handleComplete = React.useCallback((value: string) => {
+      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>
+
+              {value}
+            </Field.Wrapper>
+          </form>
+        </Page.Content>
+      </Page>
+    );
+  },
+};

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

@@ -0,0 +1,13 @@
+import React from "react";
+
+import type { OTPFieldContextType } from "../types";
+
+export const OTPFieldContext = React.createContext<OTPFieldContextType | null>(
+  null
+);
+export const useOTPField = () => {
+  const context = React.useContext(OTPFieldContext);
+
+  if (!context) return null;
+  return context;
+};

package/src/otp-field/index.tsx

@@ -0,0 +1,234 @@
+"use client";
+
+import React from "react";
+
+import { useOTPField, OTPFieldContext } from "./hooks";
+import { OTPCell } from "./styles";
+
+import type { OTPFieldProps, OTPFieldSlotProps } from "./types";
+
+export interface IOTPFieldComposition {
+  Slot: typeof OTPFieldSlot;
+}
+
+/**
+ * A field for entering one-time passwords.
+ * This component holds the state and logic for the entire OTP input group.
+ *
+ * @param {OTPFieldProps} props - The props for the OTPField component.
+ * @param {ReactNode} props.children - The content to be rendered, typically OTPField.Group.
+ * @param {number} [props.length=6] - The number of characters in the OTP.
+ * @param {function} [props.onComplete] - Callback fired when all inputs are filled.
+ * @returns {ReactElement} The OTPField component.
+ */
+const OTPField = ({ children, length, onComplete }: OTPFieldProps) => {
+  const defaultLength = length ?? 6;
+
+  const inputRefs = React.useRef<(HTMLInputElement | null)[]>([]);
+  const [otp, setOtp] = React.useState<string[]>(
+    Array.from({ length: defaultLength }, () => "")
+  );
+  const [activeIndex, setActiveIndex] = React.useState<number>(0);
+
+  const handleChange = (index: number, value: string) => {
+    const newOtp = [...otp];
+    newOtp[index] = value.substring(value.length - 1);
+    setOtp(newOtp);
+
+    if (value && index < defaultLength - 1) {
+      setActiveIndex(index + 1);
+      inputRefs.current[index + 1]?.focus();
+    }
+  };
+
+  const handleKeyDown = (index: number, e: React.KeyboardEvent) => {
+    /**
+     * Keyboard Navigation Behavior for OTP Field:
+     *
+     * Backspace/Delete:
+     * - If current slot has a value: clear it and stay in current slot
+     * - If current slot is empty: move to previous slot and clear its value
+     *
+     * Arrow Keys, Home, End:
+     * - Prevent navigation when current slot is empty
+     * - Allow navigation only when current slot has a value
+     *
+     * Tab:
+     * - Prevent forward navigation (Tab) when current slot is empty
+     * - Allow backward navigation (Shift+Tab) regardless of slot state
+     **/
+
+    const enabledBehaviorKeys = ["Backspace", "Delete"];
+    const disabledBehaviorKeys = [
+      "Tab",
+      "ArrowLeft",
+      "ArrowRight",
+      "Home",
+      "End",
+    ];
+
+    if (enabledBehaviorKeys.includes(e.key)) {
+      if (otp[index]) {
+        const newOtp = [...otp];
+        newOtp[index] = "";
+        setOtp(newOtp);
+        return;
+      }
+
+      if (index > 0) {
+        setActiveIndex(index - 1);
+        inputRefs.current[index - 1]?.focus();
+      }
+
+      return;
+    }
+
+    if (disabledBehaviorKeys.includes(e.key) && !otp[index]) {
+      e.preventDefault();
+    }
+  };
+
+  const handleFocus = (index: number) => setActiveIndex(index);
+
+  const handlePaste = (e: React.ClipboardEvent) => {
+    e.preventDefault();
+    const pasteData = e.clipboardData.getData("text");
+    const pasteArray = pasteData.slice(0, defaultLength).split("");
+
+    const newOtp = [...otp];
+    pasteArray.forEach((char, index) => {
+      if (index < defaultLength) newOtp[index] = char;
+    });
+
+    setOtp(newOtp);
+
+    const nextIndex = Math.min(pasteArray.length, defaultLength - 1);
+    setActiveIndex(nextIndex);
+    inputRefs.current[nextIndex]?.focus();
+  };
+
+  const handleClick = () => {
+    const firstEmptyIndex = otp.findIndex((digit) => digit === "");
+    const targetIndex =
+      firstEmptyIndex === -1 ? defaultLength - 1 : firstEmptyIndex;
+
+    setActiveIndex(targetIndex);
+    inputRefs.current[targetIndex]?.focus();
+
+    /**
+     * setTimeout is used to prevent the input from being selected
+     * when the focus is set and is set to 0 to select the correct slot immediately
+     */
+    const timeout = setTimeout(
+      () => inputRefs.current[targetIndex]?.select(),
+      0
+    );
+
+    return () => clearTimeout(timeout);
+  };
+
+  React.useEffect(() => {
+    const otpString = otp.join("");
+    if (otpString.length === defaultLength && onComplete) {
+      onComplete(otpString);
+    }
+  }, [otp, defaultLength, onComplete]);
+
+  const contextValue = React.useMemo(() => {
+    return {
+      otp,
+      activeIndex,
+      inputRefs,
+      length: defaultLength,
+      handleChange,
+      handleKeyDown,
+      handleFocus,
+      handleClick,
+      handlePaste,
+    };
+  }, [
+    otp,
+    activeIndex,
+    inputRefs,
+    defaultLength,
+    handleChange,
+    handleKeyDown,
+    handleFocus,
+    handleClick,
+    handlePaste,
+  ]);
+
+  return (
+    <OTPFieldContext.Provider value={contextValue}>
+      {children}
+    </OTPFieldContext.Provider>
+  );
+};
+OTPField.displayName = "OTPField";
+
+/**
+ * A container for the OTP input slots.
+ *
+ * @param {React.HTMLAttributes<HTMLSpanElement>} props - The props for the OTPField.Group component.
+ * @returns {ReactElement} The OTPField.Group component.
+ */
+const OTPFieldGroup = React.forwardRef<
+  HTMLSpanElement,
+  React.HTMLAttributes<HTMLSpanElement>
+>(({ ...props }, ref) => {
+  return (
+    <span ref={ref} className="flex g-medium-10 align-center" {...props} />
+  );
+});
+OTPFieldGroup.displayName = "OTPField.Group";
+
+/**
+ * Represents a single character input slot in the OTP field.
+ *
+ * @param {OTPFieldSlotProps & React.InputHTMLAttributes<HTMLInputElement>} props - The props for the OTPField.Slot component.
+ * @param {number} props.index - The zero-based index of the slot.
+ * @returns {ReactElement} The OTPField.Slot component.
+ */
+const OTPFieldSlot = ({
+  index,
+  ...props
+}: OTPFieldSlotProps & React.InputHTMLAttributes<HTMLInputElement>) => {
+  const context = useOTPField();
+  if (!context) return null;
+
+  const {
+    otp,
+    activeIndex,
+    inputRefs,
+    handleChange,
+    handleKeyDown,
+    handleFocus,
+    handleClick,
+    handlePaste,
+  } = context;
+
+  return (
+    <OTPCell
+      ref={(el) => (inputRefs.current[index] = el)}
+      type="text"
+      data-testid="otp-field-slot"
+      data-active={activeIndex === index}
+      autoComplete="one-time-code"
+      maxLength={1}
+      value={otp[index] || ""}
+      placeholder={props.placeholder || "-"}
+      onChange={(e) => handleChange(index, e.target.value)}
+      onKeyDown={(e) => handleKeyDown(index, e)}
+      onFocus={() => handleFocus(index)}
+      onMouseDown={() => handleClick(index)}
+      onClick={() => handleClick(index)}
+      onPaste={handlePaste}
+      {...props}
+    />
+  );
+};
+OTPFieldSlot.displayName = "OTPField.Slot";
+
+OTPField.Group = OTPFieldGroup;
+OTPField.Slot = OTPFieldSlot;
+export { OTPField, OTPFieldSlot };

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

@@ -0,0 +1,33 @@
+import styled from "styled-components";
+
+export const OTPCell = styled.input`
+  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);
+  backdrop-filter: blur(var(--measurement-small-10));
+
+  text-align: center;
+  font-size: var(--fontsize-medium-10);
+  font-weight: 500;
+
+  color: var(--font-color-alpha-10);
+  text-shadow: 0 0 0 var(--font-color);
+
+  background-color: transparent;
+  transition: all 0.2s ease-in-out;
+  outline: none;
+
+  &:focus:not(:active) {
+    background-color: var(--font-color-alpha-10);
+  }
+
+  &:hover:not(:active) {
+    border-color: var(--font-color-alpha-20);
+  }
+
+  &::placeholder {
+    opacity: var(--opacity-default-10);
+  }
+`;