@arolariu/components 0.5.0 → 1.0.0

package/src/components/ui/typewriter.tsx

@@ -1,33 +1,60 @@
 "use client";
 
-import {cn} from "@/lib/utilities";
 import {motion, stagger, useAnimate, useInView} from "motion/react";
 import * as React from "react";
 
-export const TypewriterText = ({
-  words,
-  className,
-  cursorClassName,
-}: {
-  words: {
-    text: string;
-    className?: string;
-  }[];
+import {cn} from "@/lib/utilities";
+import styles from "./typewriter.module.css";
+
+/** Single word definition consumed by the typewriter components. */
+export interface TypewriterWord {
+  /** Word content split into animated characters at render time. @default undefined */
+  text: string;
+  /** Additional CSS classes merged with each rendered character. @default undefined */
   className?: string;
+}
+
+/** Props accepted by {@link TypewriterText} and {@link TypewriterTextSmooth}. */
+export interface TypewriterTextProps {
+  /** Ordered list of words rendered by the typewriter animation. @default undefined */
+  words: ReadonlyArray<TypewriterWord>;
+  /** Additional CSS classes merged with the outer container. @default undefined */
+  className?: string;
+  /** Additional CSS classes merged with the blinking cursor element. @default undefined */
   cursorClassName?: string;
-}): React.JSX.Element => {
-  // split text inside of words into array of characters
-  const wordsArray = words.map((word) => {
-    return {
+}
+
+/**
+ * Reveals text one character at a time with a stepped typewriter animation.
+ *
+ * @remarks
+ * - Animated component using the `motion` library
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ * - Client-side only (`"use client"` directive)
+ *
+ * @example
+ * ```tsx
+ * <TypewriterText words={[{text: "Hello"}, {text: "world"}]} />
+ * ```
+ *
+ * @see {@link TypewriterTextProps} for available props
+ */
+const TypewriterText = React.forwardRef<HTMLDivElement, TypewriterTextProps>(
+  ({words, className, cursorClassName}: Readonly<TypewriterTextProps>, ref): React.JSX.Element => {
+    const wordsArray = words.map((word) => ({
       ...word,
       text: [...word.text],
-    };
-  });
+    }));
+
+    const [scope, animate] = useAnimate();
+    const isInView = useInView(scope);
+
+    React.useEffect(() => {
+      if (!isInView) {
+        return;
+      }
 
-  const [scope, animate] = useAnimate();
-  const isInView = useInView(scope);
-  React.useEffect(() => {
-    if (isInView) {
       animate(
         "span",
         {
@@ -41,133 +68,108 @@ export const TypewriterText = ({
           ease: "easeInOut",
         },
       );
-    }
-  }, [isInView]);
+    }, [animate, isInView]);
 
-  const renderWords = () => {
     return (
-      <motion.div
-        ref={scope}
-        className='inline'>
-        {wordsArray.map((word, idx) => {
-          return (
+      <div
+        ref={ref}
+        className={cn(styles.root, className)}>
+        <motion.div
+          ref={scope}
+          className={styles.inline}>
+          {wordsArray.map((word, wordIndex) => (
             <div
-              key={`word-${idx}`}
-              className='inline-block'>
-              {word.text.map((char, index) => (
+              key={`word-${wordIndex}`}
+              className={styles.word}>
+              {word.text.map((character, characterIndex) => (
                 <motion.span
                   initial={{}}
-                  key={`char-${index}`}
-                  className={cn(`hidden text-black opacity-0 dark:text-white`, word.className)}>
-                  {char}
+                  key={`char-${characterIndex}`}
+                  className={cn(styles.hiddenCharacter, word.className)}>
+                  {character}
                 </motion.span>
               ))}
               &nbsp;
             </div>
-          );
-        })}
-      </motion.div>
+          ))}
+        </motion.div>
+        <motion.span
+          initial={{opacity: 0}}
+          animate={{opacity: 1}}
+          transition={{duration: 0.8, repeat: Infinity, repeatType: "reverse"}}
+          className={cn(styles.cursor, cursorClassName)}
+        />
+      </div>
     );
-  };
-  return (
-    <div className={cn("text-center text-base font-bold sm:text-xl md:text-3xl lg:text-5xl", className)}>
-      {renderWords()}
-      <motion.span
-        initial={{
-          opacity: 0,
-        }}
-        animate={{
-          opacity: 1,
-        }}
-        transition={{
-          duration: 0.8,
-          repeat: Infinity,
-          repeatType: "reverse",
-        }}
-        className={cn("inline-block h-4 w-[4px] rounded-sm bg-blue-500 md:h-6 lg:h-10", cursorClassName)}></motion.span>
-    </div>
-  );
-};
+  },
+);
+TypewriterText.displayName = "TypewriterText";
 
-export const TypewriterTextSmooth = ({
-  words,
-  className,
-  cursorClassName,
-}: {
-  words: {
-    text: string;
-    className?: string;
-  }[];
-  className?: string;
-  cursorClassName?: string;
-}): React.JSX.Element => {
-  // split text inside of words into array of characters
-  const wordsArray = words.map((word) => {
-    return {
+/**
+ * Reveals text with a continuous width-based typewriter sweep animation.
+ *
+ * @remarks
+ * - Animated component using the `motion` library
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ * - Client-side only (`"use client"` directive)
+ *
+ * @example
+ * ```tsx
+ * <TypewriterTextSmooth words={[{text: "Smooth"}, {text: "typing"}]} />
+ * ```
+ *
+ * @see {@link TypewriterTextProps} for available props
+ */
+const TypewriterTextSmooth = React.forwardRef<HTMLDivElement, TypewriterTextProps>(
+  ({words, className, cursorClassName}: Readonly<TypewriterTextProps>, ref): React.JSX.Element => {
+    const wordsArray = words.map((word) => ({
       ...word,
       text: [...word.text],
-    };
-  });
-  const renderWords = () => {
-    return (
-      <div>
-        {wordsArray.map((word, idx) => {
-          return (
+    }));
+
+    const renderWords = (): React.JSX.Element => {
+      return (
+        <div>
+          {wordsArray.map((word, wordIndex) => (
             <div
-              key={`word-${idx}`}
-              className='inline-block'>
-              {word.text.map((char, index) => (
+              key={`word-${wordIndex}`}
+              className={styles.word}>
+              {word.text.map((character, characterIndex) => (
                 <span
-                  key={`char-${index}`}
-                  className={cn(`text-black dark:text-white`, word.className)}>
-                  {char}
+                  key={`char-${characterIndex}`}
+                  className={cn(styles.visibleCharacter, word.className)}>
+                  {character}
                 </span>
               ))}
               &nbsp;
             </div>
-          );
-        })}
+          ))}
+        </div>
+      );
+    };
+
+    return (
+      <div
+        ref={ref}
+        className={cn(styles.smoothRoot, className)}>
+        <motion.div
+          className={styles.smoothViewport}
+          initial={{width: "0%"}}
+          whileInView={{width: "fit-content"}}
+          transition={{duration: 2, ease: "linear", delay: 1}}>
+          <div className={styles.smoothText}>{renderWords()}</div>
+        </motion.div>
+        <motion.span
+          initial={{opacity: 0}}
+          animate={{opacity: 1}}
+          transition={{duration: 0.8, repeat: Infinity, repeatType: "reverse"}}
+          className={cn(styles.smoothCursor, cursorClassName)}
+        />
       </div>
     );
-  };
-
-  return (
-    <div className={cn("my-6 flex space-x-1", className)}>
-      <motion.div
-        className='overflow-hidden pb-2'
-        initial={{
-          width: "0%",
-        }}
-        whileInView={{
-          width: "fit-content",
-        }}
-        transition={{
-          duration: 2,
-          ease: "linear",
-          delay: 1,
-        }}>
-        <div
-          className='lg:text:3xl text-xs font-bold sm:text-base md:text-xl xl:text-5xl'
-          style={{
-            whiteSpace: "nowrap",
-          }}>
-          {renderWords()}{" "}
-        </div>{" "}
-      </motion.div>
-      <motion.span
-        initial={{
-          opacity: 0,
-        }}
-        animate={{
-          opacity: 1,
-        }}
-        transition={{
-          duration: 0.8,
+  },
+);
+TypewriterTextSmooth.displayName = "TypewriterTextSmooth";
 
-          repeat: Infinity,
-          repeatType: "reverse",
-        }}
-        className={cn("block h-4 w-[4px] rounded-sm bg-blue-500 sm:h-6 xl:h-12", cursorClassName)}></motion.span>
-    </div>
-  );
-};
+export {TypewriterText, TypewriterTextSmooth};

package/src/components/ui/visually-hidden.module.css

@@ -0,0 +1,11 @@
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/components/ui/visually-hidden.tsx

@@ -0,0 +1,50 @@
+import * as React from "react";
+
+import {cn} from "@/lib/utilities";
+import styles from "./visually-hidden.module.css";
+
+/**
+ * Represents the configurable props for the {@link VisuallyHidden} component.
+ *
+ * @remarks
+ * Extends native `<span>` attributes so hidden assistive text can carry ARIA metadata,
+ * testing hooks, and composed class overrides while remaining available to screen readers.
+ */
+interface VisuallyHiddenProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /**
+   * Content that is hidden visually but remains accessible to assistive technology.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Hides content visually while keeping it accessible to screen readers.
+ *
+ * @remarks
+ * **Rendering Context**: Server- and client-compatible presentational component.
+ *
+ * Renders a `<span>` that uses the classic clipping technique to remove content from the
+ * visual flow without removing it from the accessibility tree. Use it to provide labels
+ * for icon-only controls, clarify status changes, or add extra context for assistive tech.
+ *
+ * @example
+ * ```tsx
+ * <button type="button">
+ *   <TrashIcon aria-hidden="true" />
+ *   <VisuallyHidden>Delete item</VisuallyHidden>
+ * </button>
+ * ```
+ *
+ * @see {@link https://www.w3.org/WAI/tutorials/forms/labels/#note-on-hiding-elements | W3C hiding elements guidance}
+ */
+const VisuallyHidden = React.forwardRef<HTMLSpanElement, VisuallyHiddenProps>(({className, ...props}, ref) => (
+  <span
+    ref={ref}
+    className={cn(styles.visuallyHidden, className)}
+    {...props}
+  />
+));
+VisuallyHidden.displayName = "VisuallyHidden";
+
+export {VisuallyHidden};
+export type {VisuallyHiddenProps};

package/src/css-modules.d.ts

@@ -0,0 +1,9 @@
+declare module "*.module.css" {
+  const styles: Record<string, string>;
+  export default styles;
+}
+
+declare module "*.module.scss" {
+  const styles: Record<string, string>;
+  export default styles;
+}

package/src/hooks/useAnnounce.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import * as React from "react";
+
+type Politeness = "polite" | "assertive";
+
+/**
+ * Creates off-screen ARIA live regions and returns an announcement function for screen readers.
+ *
+ * @returns A callback that announces a message using the requested politeness level.
+ *
+ * @example
+ * ```tsx
+ * const announce = useAnnounce();
+ *
+ * announce("Item deleted successfully");
+ * announce("Error: invalid input", "assertive");
+ * ```
+ */
+export function useAnnounce(): (message: string, politeness?: Politeness) => void {
+  const politeRef = React.useRef<HTMLDivElement | null>(null);
+  const assertiveRef = React.useRef<HTMLDivElement | null>(null);
+
+  React.useEffect(() => {
+    const createRegion = (politeness: Politeness): HTMLDivElement => {
+      const element = document.createElement("div");
+
+      element.setAttribute("role", "status");
+      element.setAttribute("aria-live", politeness);
+      element.setAttribute("aria-atomic", "true");
+
+      Object.assign(element.style, {
+        position: "absolute",
+        width: "1px",
+        height: "1px",
+        padding: "0",
+        margin: "-1px",
+        overflow: "hidden",
+        clip: "rect(0,0,0,0)",
+        whiteSpace: "nowrap",
+        border: "0",
+      });
+
+      document.body.append(element);
+
+      return element;
+    };
+
+    politeRef.current = createRegion("polite");
+    assertiveRef.current = createRegion("assertive");
+
+    return () => {
+      politeRef.current?.remove();
+      assertiveRef.current?.remove();
+      politeRef.current = null;
+      assertiveRef.current = null;
+    };
+  }, []);
+
+  return React.useCallback((message: string, politeness: Politeness = "polite") => {
+    const region = politeness === "assertive" ? assertiveRef.current : politeRef.current;
+
+    if (!region) {
+      return;
+    }
+
+    region.textContent = "";
+
+    requestAnimationFrame(() => {
+      region.textContent = message;
+    });
+  }, []);
+}

package/src/hooks/useBreakpoint.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+import {useMediaQuery} from "./useMediaQuery";
+
+const BREAKPOINTS = [
+  ["2xl", "(min-width: 1536px)"],
+  ["xl", "(min-width: 1280px)"],
+  ["lg", "(min-width: 1024px)"],
+  ["md", "(min-width: 768px)"],
+  ["sm", "(min-width: 640px)"],
+] as const;
+
+type Breakpoint = (typeof BREAKPOINTS)[number][0];
+
+/**
+ * Returns the name of the current CSS breakpoint based on viewport width.
+ * Evaluates breakpoints from largest to smallest and returns the first match.
+ *
+ * @returns The active breakpoint name: `"sm"`, `"md"`, `"lg"`, `"xl"`, or `"2xl"`.
+ *   Returns `"sm"` when no breakpoint matches (viewport narrower than 640px).
+ *
+ * @example
+ * ```tsx
+ * const bp = useBreakpoint(); // "lg" on a 1200px viewport
+ * ```
+ */
+export function useBreakpoint(): Breakpoint {
+  const is2xl = useMediaQuery("(min-width: 1536px)");
+  const isXl = useMediaQuery("(min-width: 1280px)");
+  const isLg = useMediaQuery("(min-width: 1024px)");
+  const isMd = useMediaQuery("(min-width: 768px)");
+
+  if (is2xl) return "2xl";
+  if (isXl) return "xl";
+  if (isLg) return "lg";
+  if (isMd) return "md";
+
+  return "sm";
+}
+
+export type {Breakpoint};

package/src/hooks/useColorScheme.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import {useMediaQuery} from "./useMediaQuery";
+
+type ColorScheme = "light" | "dark";
+
+/**
+ * Returns the user's system color scheme preference.
+ *
+ * @returns `"dark"` when the system prefers dark mode, `"light"` otherwise.
+ *
+ * @example
+ * ```tsx
+ * const scheme = useColorScheme(); // "dark"
+ * ```
+ */
+export function useColorScheme(): ColorScheme {
+  const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
+
+  return prefersDark ? "dark" : "light";
+}
+
+export type {ColorScheme};

package/src/hooks/useFocusManager.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import * as React from "react";
+
+const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button:not(:disabled)",
+  "input:not(:disabled)",
+  "select:not(:disabled)",
+  "textarea:not(:disabled)",
+  '[tabindex]:not([tabindex="-1"])',
+  "[contenteditable]",
+].join(", ");
+
+/**
+ * Represents the focus movement helpers returned by {@link useFocusManager}.
+ */
+interface FocusManager {
+  /**
+   * Focuses the first focusable element in the container.
+   */
+  focusFirst: () => void;
+  /**
+   * Focuses the last focusable element in the container.
+   */
+  focusLast: () => void;
+  /**
+   * Focuses the next focusable element after the currently focused one.
+   */
+  focusNext: () => void;
+  /**
+   * Focuses the previous focusable element before the currently focused one.
+   */
+  focusPrevious: () => void;
+}
+
+/**
+ * Provides programmatic focus movement helpers for a container element.
+ *
+ * @param containerRef - Ref pointing to the container whose focusable descendants should be managed.
+ * @returns Focus helpers for moving to the first, last, next, or previous focusable descendant.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = React.useRef<HTMLDivElement>(null);
+ * const {focusNext, focusPrevious} = useFocusManager(containerRef);
+ * ```
+ */
+export function useFocusManager(containerRef: React.RefObject<HTMLElement | null>): FocusManager {
+  const getFocusable = React.useCallback((): HTMLElement[] => {
+    if (!containerRef.current) {
+      return [];
+    }
+
+    return [...containerRef.current.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)].filter(
+      (element) => !element.hasAttribute("disabled") && element.tabIndex >= 0,
+    );
+  }, [containerRef]);
+
+  const focusFirst = React.useCallback(() => {
+    getFocusable()[0]?.focus();
+  }, [getFocusable]);
+
+  const focusLast = React.useCallback(() => {
+    const items = getFocusable();
+
+    items.at(-1)?.focus();
+  }, [getFocusable]);
+
+  const focusNext = React.useCallback(() => {
+    const items = getFocusable();
+    const current = document.activeElement;
+    const index = items.indexOf(current as HTMLElement);
+    const next = items[index + 1] ?? items[0];
+
+    next?.focus();
+  }, [getFocusable]);
+
+  const focusPrevious = React.useCallback(() => {
+    const items = getFocusable();
+    const current = document.activeElement;
+    const index = items.indexOf(current as HTMLElement);
+    const previous = items[index - 1] ?? items.at(-1);
+
+    previous?.focus();
+  }, [getFocusable]);
+
+  return {focusFirst, focusLast, focusNext, focusPrevious};
+}

package/src/hooks/useFocusVisible.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Represents the focus handlers returned by {@link useFocusVisible}.
+ *
+ * @remarks
+ * Spread these handlers onto the interactive element that should respond to keyboard
+ * focus visibility. They coordinate transient focus styling without owning rendering.
+ */
+interface FocusVisibleProps {
+  /**
+   * Called when the target receives focus.
+   */
+  onFocus: (event: React.FocusEvent) => void;
+  /**
+   * Called when the target loses focus.
+   */
+  onBlur: () => void;
+}
+
+/**
+ * Detects whether the current focus originated from keyboard navigation.
+ *
+ * @remarks
+ * Tracks global keyboard and pointer input so consumers can render focus rings only when
+ * users are tabbing through the interface. This mirrors the intent of `:focus-visible`
+ * while remaining available to JavaScript-driven components and custom states.
+ *
+ * @returns An object containing the current focus-visible state and focus handlers to spread on the target element.
+ *
+ * @example
+ * ```tsx
+ * const {isFocusVisible, focusProps} = useFocusVisible();
+ *
+ * return (
+ *   <button
+ *     type="button"
+ *     {...focusProps}
+ *     className={isFocusVisible ? "ring" : undefined}>
+ *     Click
+ *   </button>
+ * );
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible | MDN :focus-visible}
+ */
+export function useFocusVisible(): {
+  isFocusVisible: boolean;
+  focusProps: FocusVisibleProps;
+} {
+  const [isFocusVisible, setIsFocusVisible] = React.useState(false);
+  const isKeyboardRef = React.useRef(false);
+
+  React.useEffect(() => {
+    const onKeyDown = () => {
+      isKeyboardRef.current = true;
+    };
+    const onPointerDown = () => {
+      isKeyboardRef.current = false;
+    };
+
+    globalThis.document.addEventListener("keydown", onKeyDown, true);
+    globalThis.document.addEventListener("pointerdown", onPointerDown, true);
+
+    return () => {
+      globalThis.document.removeEventListener("keydown", onKeyDown, true);
+      globalThis.document.removeEventListener("pointerdown", onPointerDown, true);
+    };
+  }, []);
+
+  const focusProps = React.useMemo<FocusVisibleProps>(
+    () => ({
+      onFocus: (_event: React.FocusEvent) => {
+        if (isKeyboardRef.current) {
+          setIsFocusVisible(true);
+        }
+      },
+      onBlur: () => {
+        setIsFocusVisible(false);
+      },
+    }),
+    [],
+  );
+
+  return {isFocusVisible, focusProps};
+}