pejay-ui 1.0.0

package/templates/form/phone-input.tsx

@@ -0,0 +1,82 @@
+import React, { useState, useEffect } from "react";
+import { Input } from "./input";
+
+/*
+ * ============================================================================
+ * Types & Interfaces
+ * ============================================================================
+ */
+
+interface PhoneInputProps extends React.ComponentProps<typeof Input> {
+  /* Maximum characters allowed in phone number input string */
+  maxLength?: number;
+}
+
+/*
+ * ============================================================================
+ * PhoneInput Component
+ * ============================================================================
+ */
+
+export const PhoneInput = ({
+  maxLength = 10,
+  onChange,
+  ...props
+}: PhoneInputProps) => {
+  /* Base phone string value state */
+  const [value, setValue] = useState((props.value as string) || "");
+
+  /* Synchronize value shifts programmatically from parents */
+  useEffect(() => {
+    if (props.value !== undefined) {
+      setValue(String(props.value));
+    }
+  }, [props.value]);
+
+  /*
+   * ------------------------------------------------------------------------
+   * Helper Math & Formatting Logic
+   * ------------------------------------------------------------------------
+   */
+
+  /* Filters input to retain only raw numerical digits up to maxLength */
+  const formatPhoneNumber = (digits: string) => {
+    if (!digits) return "";
+    return digits.replace(/\D/g, "").slice(0, maxLength);
+  };
+
+  /*
+   * ------------------------------------------------------------------------
+   * Event Action Handlers
+   * ------------------------------------------------------------------------
+   */
+
+  /* Text input change handler: sanitizes and propagates to parents */
+  const handleInternalChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const val = formatPhoneNumber(e.target.value);
+    setValue(val);
+    const event = {
+      ...e,
+      target: {
+        ...e.target,
+        value: val,
+      },
+    } as React.ChangeEvent<HTMLInputElement>;
+    onChange?.(event);
+  };
+
+  /*
+   * ------------------------------------------------------------------------
+   * Render Component Markup
+   * ------------------------------------------------------------------------
+   */
+
+  return (
+    <Input
+      {...props}
+      type="tel"
+      value={value}
+      onChange={handleInternalChange}
+    />
+  );
+};

package/templates/form/radio-group.tsx

@@ -0,0 +1,191 @@
+import React from "react";
+import { cn } from "@/utils/cn";
+import { Radio, type RadioProps } from "./radio";
+
+/*
+ * ============================================================================
+ * Types & Interfaces
+ * ============================================================================
+ */
+
+/* Represents an individual radio item configuration */
+export interface RadioOption {
+  id?: string;
+  label: string;
+  value: string;
+  description?: string;
+  disabled?: boolean;
+}
+
+/* Prop configuration for the parent RadioGroup component */
+interface RadioGroupProps extends Omit<
+  RadioProps,
+  | "label"
+  | "description"
+  | "value"
+  | "onChange"
+  | "defaultValue"
+  | "options"
+  | "error"
+> {
+  /* Title label of the group */
+  label?: string;
+  /* Help or descriptive text for the entire group */
+  description?: string;
+  /* Array of radio option objects */
+  options: RadioOption[];
+  /* Controlled selection value */
+  value?: string;
+  /* Default initial selection value */
+  defaultValue?: string;
+  /* Callback triggered on selection change */
+  onChange?: (value: string) => void;
+  /* Visual width class for the label area */
+  labelWidth?: string;
+  /* Horizontal alignment of the group label */
+  labelAlign?: "left" | "center" | "right";
+  /* Group-level validation error message */
+  error?: string;
+}
+
+/*
+ * ============================================================================
+ * RadioGroup Component
+ * ============================================================================
+ */
+
+export const RadioGroup = ({
+  name,
+  label,
+  description,
+  error,
+  value,
+  defaultValue,
+  onChange,
+  options = [],
+  className,
+  labelWidth = "w-full",
+  labelAlign = "left",
+  ...props
+}: RadioGroupProps) => {
+  const uniqueName = React.useId();
+  const groupName = name || uniqueName;
+
+  /* Pure Controlled State: Source value directly from parent-provided props */
+  const activeValue = value !== undefined ? value : (defaultValue || "");
+
+  /* Updates selected option and propagates changes back up */
+  const handleRadioChange = (optionValue: string) => {
+    onChange?.(optionValue);
+  };
+
+  return (
+    <div className={cn("flex w-full flex-col gap-3", className)}>
+      {/* Group Label Area (contains label and description) */}
+      {(label || description) && (
+        <div className={cn("flex flex-col shrink-0", labelWidth)}>
+          <div
+            className={cn(
+              "flex flex-col",
+              labelAlign === "left" && "items-start text-left",
+              labelAlign === "right" && "items-end text-right",
+              labelAlign === "center" && "items-center text-center",
+            )}
+          >
+            {label && (
+              <span className="tracking-tight uppercase text-sm font-bold text-black">
+                {label}
+              </span>
+            )}
+            {description && (
+              <span className="mt-0.5 leading-tight text-[11px] font-medium text-black">
+                {description}
+              </span>
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Radio Items Area (loops options and forwards rest parameters) */}
+      <div className="flex-1 flex flex-col gap-1.5">
+        <div className="flex gap-4 flex-col">
+          {options.map((option, index) => {
+            const isChecked = activeValue === option.value;
+
+            return (
+              <div
+                key={option.id || option.value || index}
+                className="flex items-center gap-3 w-full"
+              >
+                <Radio
+                  name={groupName}
+                  label={option.label}
+                  description={option.description}
+                  disabled={option.disabled}
+                  checked={isChecked}
+                  onChange={() => handleRadioChange(option.value)}
+                  className="flex-1 min-w-0"
+                  value={option.value}
+                  {...props}
+                />
+              </div>
+            );
+          })}
+        </div>
+
+        {/* Group Validation Error Message (displayed only once) */}
+        {error && (
+          <span className="text-[10px] font-medium mt-1.5 ml-1 block animate-in fade-in slide-in-from-top-1 text-red-500">
+            {error}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+};
+
+/*
+ * ============================================================================
+ * State Lifting Explanation & Usage Guide
+ * ============================================================================
+ *
+ * 1. What state was lifted up?
+ *    The selected option state (`internalValue` string) has been lifted out of the
+ *    local group scope. The local `useState` hook and lifecycle `useEffect` 
+ *    synchronization logic have been completely removed.
+ *
+ * 2. How to work with this pure controlled component (Standard React State):
+ *    Define a string state and its setter in the parent component:
+ *
+ *    const [selectedOpt, setSelectedOpt] = useState("email");
+ *
+ *    Then render the component:
+ *    <RadioGroup
+ *      label="Notification Preference"
+ *      value={selectedOpt}
+ *      onChange={setSelectedOpt}
+ *      options={[
+ *        { label: "Email", value: "email" },
+ *        { label: "SMS", value: "sms" }
+ *      ]}
+ *    />
+ *
+ * 3. React Hook Form Integration:
+ *    When using with React Hook Form, wrap this component inside a <Controller>:
+ *
+ *    <Controller
+ *      name="notificationPref"
+ *      control={control}
+ *      render={({ field }) => (
+ *        <RadioGroup
+ *          label="Notification Preferences"
+ *          value={field.value}
+ *          onChange={field.onChange}
+ *          options={[
+ *            { label: "Email", value: "email" },
+ *            { label: "SMS", value: "sms" }
+ *          ]}
+ *        />
+ *      )}
+ *    />
+ */

package/templates/form/radio.tsx

@@ -0,0 +1,157 @@
+import React, { useState } from "react";
+import { cn } from "@/utils/cn";
+
+/*
+ * ============================================================================
+ * Types & Interfaces
+ * ============================================================================
+ */
+
+/* Prop configuration for the Radio button component */
+export interface RadioProps extends Omit<
+  React.InputHTMLAttributes<HTMLInputElement>,
+  "type"
+> {
+  /* Title label of the radio option */
+  label?: string;
+  /* Help or descriptive text for the radio option */
+  description?: string;
+  /* Validation error message specific to this option */
+  error?: string;
+  /* Controls alignment of label relative to the radio dot */
+  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";
+}
+
+/*
+ * ============================================================================
+ * Radio Component
+ * ============================================================================
+ */
+
+export const Radio = ({
+  label,
+  description,
+  error,
+  labelPlacement = "right",
+  labelWidth,
+  "labelAlign-X": labelAlignX,
+  "labelAlign-Y": labelAlignY = "middle",
+  className,
+  id,
+  ...props
+}: RadioProps) => {
+  const radioId = id || React.useId();
+
+  /* Managed selection states supporting controlled and uncontrolled modes */
+  const [internalChecked, setInternalChecked] = useState(
+    props.defaultChecked || false,
+  );
+  const isControlled = props.checked !== undefined;
+  const checked = isControlled ? props.checked : internalChecked;
+
+  /* Form event delegation and local state synchrony on changes */
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    if (props.disabled) return;
+    const newChecked = e.target.checked;
+    if (!isControlled) setInternalChecked(newChecked);
+    props.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";
+
+  return (
+    <div className={cn("flex flex-col gap-1.5", className)}>
+      {/* Radio Input and Selection Wrapper Label */}
+      <label
+        htmlFor={radioId}
+        className={cn(
+          "group flex cursor-pointer select-none transition-all duration-200 gap-2",
+          labelPlacement === "top" && "flex-col",
+          /* labelPlacement 'left' aligns the radio button to the extreme right end */
+          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="radio"
+            id={radioId}
+            className="peer sr-only"
+            checked={checked}
+            onChange={handleChange}
+          />
+          {/* Outer circle indicator border */}
+          <div
+            className={cn(
+              "w-5 h-5 rounded-full border-[1.5px] border-black flex items-center justify-center bg-white",
+              checked && "scale-110",
+              "peer-focus-visible:ring-4 peer-focus-visible:ring-sky-500/10 peer-focus-visible:border-sky-500"
+            )}
+          >
+            {/* Inner selected dot */}
+            <div
+              className={cn(
+                "w-2.5 h-2.5 rounded-full bg-black",
+                checked ? "opacity-100 scale-100" : "opacity-0 scale-100",
+              )}
+            />
+          </div>
+        </div>
+
+        {/* Text Area (Option labels and descriptive help texts) */}
+        {(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="whitespace-normal break-words w-full text-sm font-medium text-black">
+                {label}
+                {props.required && (
+                  <span className="ml-1 font-black text-red-500">
+                    *
+                  </span>
+                )}
+              </span>
+            )}
+            {description && (
+              <span className="leading-tight whitespace-normal break-words w-full text-xs text-black">
+                {description}
+              </span>
+            )}
+          </div>
+        )}
+      </label>
+
+      {/* Option Validation Error Message */}
+      {error && (
+        <span className="text-xs font-medium ml-1 italic tracking-tight animate-in fade-in slide-in-from-top-1 text-red-500">
+          {error}
+        </span>
+      )}
+    </div>
+  );
+};

package/templates/form/range-slider.tsx

@@ -0,0 +1,210 @@
+import React from "react";
+import { cn } from "@/utils/cn";
+
+interface RangeSliderProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "onChange"> {
+  /* Title label of the range slider */
+  label?: string;
+  /* Help or descriptive text for the slider */
+  description?: string;
+  /* Validation error message specific to the slider value */
+  error?: string;
+  /* Layout alignment position of the label relative to the slider bar */
+  labelDirection?: 
+    | "label-left" | "label-left-top" | "label-left-bottom"
+    | "label-right" | "label-right-top" | "label-right-bottom"
+    | "label-top" | "label-top-right" | "label-top-center";
+  /* Custom visual width string for the label container */
+  labelWidth?: string;
+  /* Horizontal text alignment of the label */
+  labelAlign?: "left" | "center" | "right";
+  /* Visual flex-gap spacing class between the label and slider */
+  labelGap?: string;
+  /* Controls whether the current selected value is rendered numerically */
+  showValue?: boolean;
+  /* Custom unit string to append after the rendered numerical value */
+  valueSuffix?: string;
+  /* Callback triggered immediately on slider drag changes */
+  onChange?: (value: number) => void;
+}
+
+export const RangeSlider = ({
+  label,
+  description,
+  error,
+  labelDirection = "label-top",
+  labelWidth = "w-32",
+  labelAlign,
+  labelGap = "gap-4",
+  showValue = true,
+  valueSuffix = "",
+  min = 0,
+  max = 100,
+  step = 1,
+  onChange,
+  className,
+  id,
+  ...props
+}: RangeSliderProps) => {
+  const sliderId = id || React.useId();
+  
+  /* Pure Controlled State: Source value directly from parent-provided props */
+  const resolvedValue = props.value !== undefined ? Number(props.value) : Number(min);
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newValue = Number(e.target.value);
+    /* Notify parent immediately on slide changes */
+    onChange?.(newValue);
+  };
+
+  const percentage = ((resolvedValue - Number(min)) / (Number(max) - Number(min))) * 100;
+  const isSideLabel = labelDirection.startsWith("label-left") || labelDirection.startsWith("label-right");
+
+  const alignment = labelAlign || (
+    labelDirection.includes("-left") ? "left" : 
+    labelDirection.includes("-right") ? "right" : 
+    labelDirection.includes("-center") ? "center" : "left"
+  );
+
+  return (
+    <div
+      className={cn(
+        "flex w-full",
+        labelGap,
+        isSideLabel ? "flex-row" : "flex-col",
+        (labelDirection === "label-left" || labelDirection === "label-right") && "items-center",
+        labelDirection.endsWith("-top") && isSideLabel && "mt-1 items-start",
+        labelDirection.endsWith("-bottom") && isSideLabel && "items-end",
+        labelDirection.startsWith("label-right") && "flex-row-reverse",
+        className
+      )}
+    >
+      {label && (
+        <div 
+          className={cn(
+            "flex flex-col",
+            isSideLabel ? "shrink-0" : "w-full",
+            labelDirection.endsWith("-top") && isSideLabel && "mt-1.5"
+          )}
+        >
+          <div className={cn(
+            isSideLabel ? labelWidth : "w-full", 
+            "flex flex-col gap-1", 
+            alignment === "left" && "items-start text-left", 
+            alignment === "right" && "items-end text-right", 
+            alignment === "center" && "items-center text-center"
+          )}>
+            {/* Row 1: Label & Number */}
+            <div className="flex justify-between items-center w-full gap-4">
+              <label
+                htmlFor={sliderId}
+                className="text-sm font-medium text-black cursor-pointer select-none whitespace-normal wrap-break-word"
+              >
+                {label}
+              </label>
+              {showValue && !isSideLabel && (
+                <span className="text-sm font-bold tabular-nums text-black shrink-0 leading-none">
+                  {resolvedValue}{valueSuffix}
+                </span>
+              )}
+            </div>
+            
+            {/* Row 2: Description */}
+            {description && (
+              <span className="text-xs text-black leading-tight whitespace-normal wrap-break-word w-full">
+                {description}
+              </span>
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Row 3: Slider */}
+      <div className="flex-1 flex items-center gap-4">
+        {showValue && isSideLabel && labelDirection.startsWith("label-left") && (
+          <span className="text-sm font-semibold tabular-nums text-black shrink-0 min-w-[3ch] text-right">
+            {resolvedValue}{valueSuffix}
+          </span>
+        )}
+
+        <div className="relative flex-1 flex items-center h-6 group">
+          <div className="absolute w-full h-[6px] bg-black/20 rounded-full overflow-hidden">
+            <div 
+              className="h-full bg-black transition-all duration-100 ease-out"
+              style={{ width: `${percentage}%` }}
+            />
+          </div>
+
+          <input
+            {...props}
+            type="range"
+            id={sliderId}
+            min={min}
+            max={max}
+            step={step}
+            value={resolvedValue}
+            onChange={handleChange}
+            className={cn(
+              "absolute w-full h-6 appearance-none bg-transparent cursor-pointer z-10",
+              "focus:outline-none focus:ring-4 focus:ring-sky-500/10 rounded-lg",
+              "[&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-[18px] [&::-webkit-slider-thumb]:h-[18px] [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-white [&::-webkit-slider-thumb]:border [&::-webkit-slider-thumb]:border-black/20 [&::-webkit-slider-thumb]:shadow-sm [&::-webkit-slider-thumb]:transition-transform [&::-webkit-slider-thumb]:duration-150 [&::-webkit-slider-thumb]:active:scale-90",
+              "[&::-moz-range-thumb]:w-[18px] [&::-moz-range-thumb]:h-[18px] [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:bg-white [&::-moz-range-thumb]:border [&::-moz-range-thumb]:border-black/20 [&::-moz-range-thumb]:shadow-sm [&::-moz-range-thumb]:transition-transform [&::-moz-range-thumb]:duration-150 [&::-moz-range-thumb]:active:scale-90"
+            )}
+          />
+        </div>
+
+        {showValue && isSideLabel && labelDirection.startsWith("label-right") && (
+          <span className="text-sm font-semibold tabular-nums text-black shrink-0 min-w-[3ch] text-left">
+            {resolvedValue}{valueSuffix}
+          </span>
+        )}
+      </div>
+
+      {error && (
+        <span className="text-xs font-medium text-red-500 italic tracking-tight">
+          {error}
+        </span>
+      )}
+    </div>
+  );
+};
+
+/*
+ * ============================================================================
+ * State Lifting Explanation & Usage Guide
+ * ============================================================================
+ *
+ * 1. What state was lifted up?
+ *    The slider value state (`internalValue` number) has been lifted out of the
+ *    local component scope. The local `useState` hook and lifecycle `useEffect` 
+ *    synchronization logic have been completely removed.
+ *
+ * 2. How to work with this pure controlled component (Standard React State):
+ *    Define a numeric state and its setter in the parent component:
+ *
+ *    const [sliderVal, setSliderVal] = useState(50);
+ *
+ *    Then render the component:
+ *    <RangeSlider
+ *      label="Expense Limit"
+ *      min={0}
+ *      max={100}
+ *      value={sliderVal}
+ *      onChange={setSliderVal}
+ *    />
+ *
+ * 3. React Hook Form Integration:
+ *    When using with React Hook Form, wrap this component inside a <Controller>:
+ *
+ *    <Controller
+ *      name="budgetLimit"
+ *      control={control}
+ *      render={({ field }) => (
+ *        <RangeSlider
+ *          label="Monthly Budget"
+ *          value={field.value}
+ *          onChange={field.onChange}
+ *        />
+ *      )}
+ *    />
+ */
+