pejay-ui 1.0.0

package/templates/form/switch.tsx

@@ -0,0 +1,134 @@
+import React from "react";
+import { cn } from "@/utils/cn";
+
+interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "onChange"> {
+  /* Title label of the switch toggle */
+  label?: string;
+  /* Help or descriptive text for the switch */
+  description?: string;
+  /* Validation error message specific to this switch */
+  error?: string;
+  /* Controls placement of label relative to the switch toggle */
+  labelPlacement?: "top" | "left" | "right";
+  /* Sizing parameter for the label container width */
+  labelWidth?: string;
+  /* Horizontal alignment of the text label */
+  "labelAlign-X"?: "left" | "center" | "right";
+  /* Vertical alignment of the text label */
+  "labelAlign-Y"?: "top" | "middle" | "bottom";
+  /* Callback triggered on switch selection change */
+  onChange?: (checked: boolean) => void;
+}
+
+export const Switch = ({
+  label,
+  description,
+  error,
+  labelPlacement = "right",
+  labelWidth,
+  "labelAlign-X": labelAlignX,
+  "labelAlign-Y": labelAlignY = "middle",
+  onChange,
+  className,
+  id,
+  ...props
+}: SwitchProps) => {
+  const switchId = id || React.useId();
+  
+  /* Pure Controlled State: Read checked directly from parent-provided props */
+  const checked = props.checked || false;
+
+  const handleToggle = (e: React.MouseEvent | React.KeyboardEvent) => {
+    if (props.disabled) return;
+    e.preventDefault();
+    /* Immediately notify parent of the state transition */
+    onChange?.(!checked);
+  };
+
+  const isSideLabel = labelPlacement === "left" || labelPlacement === "right";
+  const xAlignment = labelAlignX || (labelPlacement === "left" ? "left" : labelPlacement === "right" ? "right" : "left");
+  const yAlignmentClass = labelAlignY === "top" ? "items-start" : labelAlignY === "bottom" ? "items-end" : "items-center";
+
+  return (
+    <div className={cn("flex flex-col gap-1.5", className)}>
+      <label
+        htmlFor={switchId}
+        onClick={handleToggle}
+        className={cn(
+          "group flex cursor-pointer select-none transition-all duration-200 gap-4",
+          labelPlacement === "top" && "flex-col",
+          labelPlacement === "left" && cn("flex-row-reverse justify-between w-full", yAlignmentClass),
+          labelPlacement === "right" && cn("flex-row justify-start", yAlignmentClass),
+          props.disabled && "opacity-50 cursor-not-allowed"
+        )}
+      >
+        <div className="relative flex items-center shrink-0">
+          <input 
+            {...props} 
+            type="checkbox" 
+            id={switchId} 
+            className="peer sr-only" 
+            checked={checked} 
+            readOnly 
+          />
+          <div className={cn(
+            "w-[44px] h-[24px] rounded-full transition-all duration-200 ease-in-out border-[1.5px] border-black relative",
+            checked ? "bg-black" : "bg-black/10",
+            "peer-focus-visible:ring-4 peer-focus-visible:ring-sky-500/10 peer-focus-visible:border-sky-500"
+          )}>
+            <div className={cn(
+              "w-4 h-4 rounded-full transition-all duration-200 ease-in-out absolute top-[2.5px] left-[3.5px]",
+              checked ? "bg-white translate-x-[18px]" : "bg-black translate-x-0"
+            )} />
+          </div>
+        </div>
+
+        {(label || description) && (
+          <div className={cn("flex flex-col gap-0.5 min-w-0", isSideLabel ? (labelWidth || "flex-1") : "w-full", xAlignment === "left" && "items-start text-left", xAlignment === "right" && "items-end text-right", xAlignment === "center" && "items-center text-center")}>
+            {label && <span className="text-sm font-medium text-black whitespace-normal break-words w-full">{label}{props.required && <span className="text-red-500 ml-1 font-black">*</span>}</span>}
+            {description && <span className="text-xs text-black leading-tight whitespace-normal break-words w-full">{description}</span>}
+          </div>
+        )}
+      </label>
+      {error && <span className="text-xs font-medium text-red-500 ml-1 italic tracking-tight animate-in fade-in slide-in-from-top-1">{error}</span>}
+    </div>
+  );
+};
+
+/*
+ * ============================================================================
+ * State Lifting Explanation & Usage Guide
+ * ============================================================================
+ *
+ * 1. What state was lifted up?
+ *    The selection/toggle state (`checked` boolean) has been completely lifted
+ *    out of the local component scope. The local `useState` hook and corresponding
+ *    effects have been removed.
+ *
+ * 2. How to work with this pure controlled component (Standard React State):
+ *    Define a boolean state and its setter in the parent component:
+ *
+ *    const [isActive, setIsActive] = useState(false);
+ *
+ *    Then render the component:
+ *    <Switch
+ *      label="Toggle Active State"
+ *      checked={isActive}
+ *      onChange={setIsActive}
+ *    />
+ *
+ * 3. React Hook Form Integration:
+ *    When using with React Hook Form, wrap this component inside a <Controller>:
+ *
+ *    <Controller
+ *      name="subscribe"
+ *      control={control}
+ *      render={({ field }) => (
+ *        <Switch
+ *          label="Subscribe"
+ *          checked={field.value}
+ *          onChange={field.onChange}
+ *        />
+ *      )}
+ *    />
+ */

package/templates/form/textarea.tsx

@@ -0,0 +1,253 @@
+import React, { useState, useRef, useLayoutEffect } from "react";
+import { cn } from "@/utils/cn";
+
+/*
+ * ============================================================================
+ * Types & Interfaces for TextArea Component
+ * ============================================================================
+ */
+interface TextAreaProps extends Omit<
+  React.TextareaHTMLAttributes<HTMLTextAreaElement>,
+  "prefix"
+> {
+  /** Main label displayed above or next to the textarea */
+  label?: string;
+  /** Helper description text shown below the label */
+  description?: string;
+  /** Validation error message that triggers error styling and displays at the bottom */
+  error?: string;
+  /** Corner style variant for the input container */
+  variant?: "rounded" | "curved" | "square";
+  /** Position of the label relative to the textarea input box */
+  labelPlacement?: "top" | "left" | "right";
+  /** Explicit width constraints when using horizontal/side labels */
+  labelWidth?: string;
+  /** Horizontal alignment of the label text */
+  "labelAlign-X"?: "left" | "center" | "right";
+  /** Vertical alignment of side labels relative to the input container */
+  "labelAlign-Y"?: "top" | "middle" | "bottom";
+  /** Auto-resizes the height of the textarea based on content length */
+  autoResize?: boolean;
+  /** Maximum height constraint when autoResize is enabled */
+  maxHeight?: string;
+  /** Native resize behavior constraint */
+  allowResize?: "none" | "both" | "vertical" | "horizontal";
+  /** Controls displaying character, word, or both counters in the bottom right corner */
+  showCount?: "characters" | "words" | "both" | "none";
+  /** Enforces a strict word count limit on user inputs */
+  maxWordLimit?: number;
+  /** Additional tailwind custom classes for the outer wrapper */
+  wrapperClassName?: string;
+  /** Additional tailwind custom classes for the textarea element */
+  inputClassName?: string;
+}
+
+/*
+ * ============================================================================
+ * TextArea Component (ForwardRef Enabled)
+ * ============================================================================
+ */
+export const TextArea = React.forwardRef<HTMLTextAreaElement, TextAreaProps>(
+  (
+    {
+      label,
+      description,
+      error,
+      variant = "curved",
+      labelPlacement = "top",
+      labelWidth = "w-32",
+      "labelAlign-X": labelAlignX,
+      "labelAlign-Y": labelAlignY = "middle",
+      autoResize = false,
+      maxHeight,
+      allowResize = "none",
+      showCount = "none",
+      maxWordLimit,
+      wrapperClassName,
+      inputClassName,
+      className,
+      onFocus,
+      onBlur,
+      onChange,
+      ...props
+    },
+    ref,
+  ) => {
+    const [isFocused, setIsFocused] = useState(false);
+    const [internalHasContent, setInternalHasContent] = useState(
+      !!props.defaultValue || !!props.value,
+    );
+    const [wordCount, setWordCount] = useState(0);
+    const [charCount, setCharCount] = useState(0);
+    const internalRef = useRef<HTMLTextAreaElement>(null);
+
+    // Merge outer forwarded ref with our internal ref for autoResize calculations
+    const setRefs = (node: HTMLTextAreaElement) => {
+      if (typeof ref === "function") {
+        ref(node);
+      } else if (ref) {
+        (ref as any).current = node;
+      }
+      (internalRef as any).current = node;
+    };
+
+    // Calculate height adjustment on text change if autoResize is enabled
+    useLayoutEffect(() => {
+      if (autoResize && internalRef.current) {
+        internalRef.current.style.height = "auto";
+        const newHeight = internalRef.current.scrollHeight;
+        internalRef.current.style.height = maxHeight
+          ? `${Math.min(newHeight, parseInt(maxHeight))}px`
+          : `${newHeight}px`;
+      }
+    }, [props.value, internalHasContent, autoResize, maxHeight]);
+
+    const handleFocus = (e: React.FocusEvent<HTMLTextAreaElement>) => {
+      setIsFocused(true);
+      onFocus?.(e);
+    };
+
+    const handleBlur = (e: React.FocusEvent<HTMLTextAreaElement>) => {
+      setIsFocused(false);
+      setInternalHasContent(e.target.value !== "");
+      onBlur?.(e);
+    };
+
+    const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+      const val = e.target.value;
+
+      // Enforce word limits if configured
+      if (maxWordLimit) {
+        const words = val.trim().split(/\s+/).filter(Boolean);
+        if (words.length > maxWordLimit) return;
+      }
+
+      setInternalHasContent(val !== "");
+      setCharCount(val.length);
+      setWordCount(val.trim().split(/\s+/).filter(Boolean).length);
+
+      onChange?.(e);
+    };
+
+    const isSideLabel = labelPlacement === "left" || labelPlacement === "right";
+
+    const xAlignment =
+      labelAlignX || (labelPlacement === "left" ? "right" : "left");
+
+    const yAlignmentClass =
+      labelAlignY === "top"
+        ? "items-start"
+        : labelAlignY === "bottom"
+          ? "items-end"
+          : "items-center";
+
+    const radiusClass =
+      variant === "square"
+        ? "rounded-none"
+        : variant === "curved"
+          ? "rounded-lg"
+          : "rounded-full";
+
+    return (
+      <div
+        className={cn(
+          "flex w-full",
+          labelPlacement === "top" && "flex-col gap-1.5",
+          labelPlacement === "left" && cn("flex-row gap-4", yAlignmentClass),
+          labelPlacement === "right" &&
+            cn("flex-row-reverse gap-4", yAlignmentClass),
+          className,
+        )}
+      >
+        {/* Standard Label Element */}
+        {label && (
+          <div
+            className={cn(
+              "flex flex-col",
+              isSideLabel ? "shrink-0" : "w-full",
+              labelAlignY === "top" && isSideLabel && "mt-2.5",
+            )}
+          >
+            <div
+              className={cn(
+                isSideLabel ? labelWidth : "w-full",
+                "flex flex-col",
+                xAlignment === "left" && "items-start text-left",
+                xAlignment === "right" && "items-end text-right",
+                xAlignment === "center" && "items-center text-center",
+              )}
+            >
+              <span className="text-md font-medium text-black">
+                {label}
+              </span>
+              {description && (
+                <span className="text-xs text-black font-medium mt-0.5">
+                  {description}
+                </span>
+              )}
+            </div>
+          </div>
+        )}
+
+        {/* Input Wrapper Group */}
+        <div className="flex-1 flex flex-col relative group">
+          {/* Styled wrapper container for borders and states */}
+          <div
+            className={cn(
+              "relative w-full bg-white border-[1.5px] border-black transition-all duration-200 min-h-[80px]",
+              radiusClass,
+              isFocused
+                ? "border-sky-500 ring-4 ring-sky-500/10 shadow-sm"
+                : "hover:border-gray-800",
+              error ? "border-red-600 ring-4 ring-red-600/10" : "",
+              wrapperClassName,
+            )}
+          >
+            <textarea
+              ref={setRefs}
+              {...props}
+              onFocus={handleFocus}
+              onBlur={handleBlur}
+              onChange={handleChange}
+              placeholder={props.placeholder}
+              style={{ resize: allowResize }}
+              className={cn(
+                "w-full bg-transparent border-none text-md text-black outline-none p-2.5 pb-1",
+                "placeholder:text-black/40 placeholder:text-sm placeholder:font-medium",
+                autoResize && "overflow-hidden",
+                inputClassName,
+              )}
+            />
+
+            {/* Display character/word counters in a dedicated footer row to prevent overlap */}
+            {showCount !== "none" && (
+              <div className="flex justify-end gap-3 px-4 pb-2 select-none pointer-events-none">
+                {(showCount === "characters" || showCount === "both") && (
+                  <span className="text-[10px] font-semibold text-black/40 uppercase">
+                    {charCount}
+                    {props.maxLength ? ` / ${props.maxLength}` : ""} CHR
+                  </span>
+                )}
+                {(showCount === "words" || showCount === "both") && (
+                  <span className="text-[10px] font-semibold text-black/40 uppercase">
+                    {wordCount}
+                    {maxWordLimit ? ` / ${maxWordLimit}` : ""} WRD
+                  </span>
+                )}
+              </div>
+            )}
+          </div>
+
+          {/* Validation Error Message Display */}
+          {error && (
+            <span className="text-xs font-medium text-red-600 mt-1.5 ml-1 block animate-in fade-in slide-in-from-top-1">
+              {error}
+            </span>
+          )}
+        </div>
+      </div>
+    );
+  },
+);
+
+TextArea.displayName = "TextArea";