pejay-ui 1.0.0

package/templates/form/amount-input.tsx

@@ -0,0 +1,252 @@
+import React, { useState, useEffect } from "react";
+import { Input } from "./input";
+import { Plus, Minus } from "lucide-react";
+import { cn } from "@/utils/cn";
+
+/*
+ * ============================================================================
+ * Types & Interfaces
+ * ============================================================================
+ */
+
+interface AmountInputProps extends React.ComponentProps<typeof Input> {
+  /* Minimum value constraint */
+  min?: string | number;
+  /* Maximum value constraint */
+  max?: string | number;
+  /* Allows typing and submitting negative values */
+  allowNegative?: boolean;
+  /* Forces trailing decimal precision on blur (e.g. 10 -> 10.00) */
+  fixedDecimalOnBlur?: boolean;
+  /* Controls visibility of right-side increment/decrement steppers */
+  showSteppers?: boolean;
+  /* Value delta to apply when stepping up or down */
+  step?: number;
+}
+
+/*
+ * ============================================================================
+ * AmountInput Component
+ * ============================================================================
+ */
+
+export const AmountInput = ({
+  min,
+  max,
+  allowNegative = false,
+  fixedDecimalOnBlur = false,
+  showSteppers = false,
+  step = 1,
+  onChange,
+  onBlur,
+  className,
+  ...props
+}: AmountInputProps) => {
+  /* Base amount 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
+   * ------------------------------------------------------------------------
+   */
+
+  /* Resolve the decimal scale: use max/min precision if present, else default to 2 */
+  const getPrecision = (num?: string | number) => {
+    if (num === undefined) return null;
+    const parts = String(num).split(".");
+    return parts.length > 1 ? parts[1].length : 0;
+  };
+
+  const maxPrecision = getPrecision(max);
+  const minPrecision = getPrecision(min);
+  let resolvedScale = 2;
+  if (maxPrecision !== null || minPrecision !== null) {
+    const derivedPrecision = Math.max(maxPrecision || 0, minPrecision || 0);
+    resolvedScale = derivedPrecision > 0 ? derivedPrecision : 2;
+  }
+
+  /* Default min to 0 unless allowNegative is enabled */
+  const resolvedMin = min !== undefined 
+    ? (typeof min === "number" ? min : parseFloat(String(min))) 
+    : (allowNegative ? undefined : 0);
+
+  const resolvedMax = max !== undefined 
+    ? (typeof max === "number" ? max : parseFloat(String(max))) 
+    : undefined;
+
+  /* Formats raw strings with dynamic decimal constraints and thousands groupings */
+  const formatAmount = (val: string) => {
+    if (!val || val === "-") return val;
+    const isNegative = val.startsWith("-");
+    const clean = val.replace(/[^\d.]/g, "");
+    const parts = clean.split(".");
+    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+
+    let result = parts[0];
+    if (parts.length >= 2) {
+      result += `.${parts[1].slice(0, resolvedScale)}`;
+    }
+
+    return isNegative ? `-${result}` : result;
+  };
+
+  /* Unified value updater: performs min/max boundaries and RHF event propagation */
+  const updateValue = (newVal: string | number, baseEvent?: React.ChangeEvent<HTMLInputElement>) => {
+    const stringVal = String(newVal);
+    let numeric = parseFloat(stringVal.replace(/,/g, ""));
+    
+    /* Handle empty/NaN values, including intermediate minus sign */
+    if (isNaN(numeric)) {
+      const emptyVal = allowNegative && stringVal === "-" ? "-" : "";
+      setValue(emptyVal);
+      
+      const event = baseEvent ? {
+        ...baseEvent,
+        target: { ...baseEvent.target, value: emptyVal }
+      } : {
+        target: { value: emptyVal }
+      } as React.ChangeEvent<HTMLInputElement>;
+      onChange?.(event);
+      return;
+    }
+
+    /* Clamp numeric boundaries */
+    if (resolvedMin !== undefined && numeric < resolvedMin) numeric = resolvedMin;
+    if (resolvedMax !== undefined && numeric > resolvedMax) numeric = resolvedMax;
+
+    /* Build clean string value while preserving trailing decimals and typing state */
+    let finalVal = formatAmount(String(numeric));
+    if (stringVal.endsWith(".") && !finalVal.includes(".")) {
+      finalVal += ".";
+    } else if (stringVal.includes(".")) {
+      const [_, fractional] = stringVal.split(".");
+      const [formattedInt] = finalVal.split(".");
+      finalVal = `${formattedInt}.${fractional.slice(0, resolvedScale)}`;
+    }
+
+    setValue(finalVal);
+    
+    /* Propagate change up to React Hook Form listener */
+    const event = baseEvent ? {
+      ...baseEvent,
+      target: { ...baseEvent.target, value: finalVal }
+    } : {
+      target: { value: finalVal }
+    } as React.ChangeEvent<HTMLInputElement>;
+    onChange?.(event);
+  };
+
+  /*
+   * ------------------------------------------------------------------------
+   * Event Action Handlers
+   * ------------------------------------------------------------------------
+   */
+
+  /* Stepper button increment click action */
+  const handleIncrement = () => {
+    const current = parseFloat(value.replace(/,/g, "")) || 0;
+    updateValue(current + step);
+  };
+
+  /* Stepper button decrement click action */
+  const handleDecrement = () => {
+    const current = parseFloat(value.replace(/,/g, "")) || 0;
+    updateValue(current - step);
+  };
+
+  /* Input blur handler: enforces trailing precision logic */
+  const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+    if (fixedDecimalOnBlur && value && value !== "-") {
+      const numeric = parseFloat(value.replace(/,/g, ""));
+      if (!isNaN(numeric)) {
+        let fixedValue = value;
+
+        /* Force decimal formatting on blur if no decimals exist */
+        if (!value.includes(".")) {
+          fixedValue = formatAmount(numeric.toFixed(resolvedScale));
+        }
+
+        if (fixedValue !== value) {
+          setValue(fixedValue);
+          const event = {
+            ...e,
+            target: { ...e.target, value: fixedValue },
+          } as unknown as React.ChangeEvent<HTMLInputElement>;
+          onChange?.(event);
+        }
+      }
+    }
+    onBlur?.(e);
+  };
+
+  /* Text input change handler: sanitizes and forwards to unified value updater */
+  const handleInternalChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    let rawValue = e.target.value;
+
+    /* Lock raw text patterns based on negation rules */
+    if (allowNegative) {
+      rawValue = rawValue.replace(/(?!^)-/g, "").replace(/[^\d.-]/g, "");
+      const dotParts = rawValue.split(".");
+      if (dotParts.length > 2) rawValue = `${dotParts[0]}.${dotParts[1]}`;
+    } else {
+      rawValue = rawValue.replace(/[^\d.]/g, "");
+    }
+
+    updateValue(rawValue, e);
+  };
+
+  /*
+   * ------------------------------------------------------------------------
+   * Render Component Markup
+   * ------------------------------------------------------------------------
+   */
+
+  return (
+    <Input
+      {...props}
+      type="text"
+      value={value}
+      onChange={handleInternalChange}
+      onBlur={handleBlur}
+      className={className}
+      rightIcon={
+        (showSteppers || props.rightIcon) && (
+          <div className="flex items-center gap-1.5 pl-2 ml-1">
+            {showSteppers && (
+              <div
+                className={cn(
+                  "flex items-center gap-1",
+                  props.rightIcon && "border-r border-gray-250 pr-2 mr-1"
+                )}
+              >
+                <button
+                  type="button"
+                  onClick={handleDecrement}
+                  className="p-0.5 rounded transition-colors bg-black text-white cursor-pointer hover:bg-gray-800"
+                >
+                  <Minus size={14} />
+                </button>
+                <button
+                  type="button"
+                  onClick={handleIncrement}
+                  className="p-0.5 rounded transition-colors bg-black text-white cursor-pointer hover:bg-gray-800"
+                >
+                  <Plus size={14} />
+                </button>
+              </div>
+            )}
+            {props.rightIcon}
+          </div>
+        )
+      }
+    />
+  );
+};

package/templates/form/checkbox-group.tsx

@@ -0,0 +1,235 @@
+import React from "react";
+import { cn } from "@/utils/cn";
+import { Checkbox, type CheckboxProps } from "./checkbox";
+
+/*
+ * ============================================================================
+ * Types & Interfaces
+ * ============================================================================
+ */
+
+/* Represents an individual checkbox item configuration */
+interface CheckboxOption {
+  id?: string;
+  label: string;
+  value: string;
+  description?: string;
+  disabled?: boolean;
+  indicator?: React.ReactNode | "bullet" | "number";
+}
+
+/* Prop configuration for the parent CheckboxGroup component extending CheckboxProps */
+interface CheckboxGroupProps extends Omit<
+  CheckboxProps,
+  | "label"
+  | "description"
+  | "value"
+  | "onChange"
+  | "defaultValue"
+  | "options"
+  | "error"
+> {
+  /* Title label of the group */
+  label?: string;
+  /* Help or descriptive text for the entire group */
+  description?: string;
+  /* Group-level validation error message */
+  error?: string;
+  /* Support single selection or multiple checkbox checks */
+  type?: "single" | "multiple";
+  /* Controlled selection value(s) */
+  value?: string | string[];
+  /* Default initial selection value(s) */
+  defaultValue?: string | string[];
+  /* Callback triggered on selection change */
+  onChange?: (value: any) => void;
+  /* Array of checkbox option objects */
+  options: CheckboxOption[];
+  /* Visual width class for the label area */
+  labelWidth?: string;
+  /* Horizontal alignment of the group label */
+  labelAlign?: "left" | "center" | "right";
+  /* Group-level bullets or numerical index prefix markers */
+  indicator?: "dots" | "numbers" | React.ReactNode;
+}
+
+/*
+ * ============================================================================
+ * CheckboxGroup Component
+ * ============================================================================
+ */
+
+export const CheckboxGroup = ({
+  label,
+  description,
+  error,
+  type = "multiple",
+  value,
+  defaultValue,
+  onChange,
+  options = [],
+  className,
+  labelWidth = "w-full",
+  labelAlign = "left",
+  indicator,
+  ...props
+}: CheckboxGroupProps) => {
+  /* Pure Controlled State: Source value directly from parent-provided props */
+  const activeValue = value !== undefined ? value : (defaultValue || (type === "multiple" ? [] : ""));
+
+  /* Appends/removes option keys in array for multi-mode, or toggles value for single-mode */
+  const handleCheckboxChange = (optionValue: string) => {
+    let newValue: string | string[];
+
+    if (type === "single") {
+      newValue = activeValue === optionValue ? "" : optionValue;
+    } else {
+      const currentValues = Array.isArray(activeValue) ? activeValue : [];
+      newValue = currentValues.includes(optionValue)
+        ? currentValues.filter(v => v !== optionValue)
+        : [...currentValues, optionValue];
+    }
+
+    onChange?.(newValue);
+  };
+
+  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>
+      )}
+
+      {/* Checkbox Options Area */}
+      <div className="flex-1 flex flex-col gap-1.5">
+        <div className="flex gap-4 flex-col">
+          {options.map((option, index) => {
+            const isChecked =
+              type === "single"
+                ? activeValue === option.value
+                : Array.isArray(activeValue) &&
+                  activeValue.includes(option.value);
+
+            /* Resolves bullet, number index, or custom indicators */
+            const optIndicator = option.indicator || indicator;
+            let indicatorNode = null;
+            if (optIndicator === "bullet" || optIndicator === "dots") {
+              indicatorNode = (
+                <div className="w-1.5 h-1.5 rounded-full bg-white shrink-0 mt-2" />
+              );
+            } else if (
+              optIndicator === "number" ||
+              optIndicator === "numbers"
+            ) {
+              indicatorNode = (
+                <span className="text-sm font-bold shrink-0 mt-0.5 w-4 text-center text-gray-500">
+                  {index + 1}.
+                </span>
+              );
+            } else if (optIndicator) {
+              indicatorNode = (
+                <div className="shrink-0 mt-0.5 flex items-center justify-center text-sm font-medium text-gray-500">
+                  {optIndicator}
+                </div>
+              );
+            }
+
+            return (
+              <div
+                key={option.id || option.value || index}
+                className="flex gap-3 items-start"
+              >
+                {indicatorNode}
+                <Checkbox
+                  id={option.id}
+                  label={option.label}
+                  description={option.description}
+                  disabled={option.disabled}
+                  checked={isChecked}
+                  onChange={() => handleCheckboxChange(option.value)}
+                  className="shrink-0 flex-1"
+                  {...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 selection states (`internalValue` single string or array of strings) 
+ *    have been completely 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 an array state and its setter in the parent component:
+ *
+ *    const [selectedItems, setSelectedItems] = useState(["design"]);
+ *
+ *    Then render the component:
+ *    <CheckboxGroup
+ *      label="Interests"
+ *      type="multiple"
+ *      value={selectedItems}
+ *      onChange={setSelectedItems}
+ *      options={[
+ *        { label: "Technology", value: "technology" },
+ *        { label: "Design", value: "design" }
+ *      ]}
+ *    />
+ *
+ * 3. React Hook Form Integration:
+ *    When using with React Hook Form, wrap this component inside a <Controller>:
+ *
+ *    <Controller
+ *      name="interests"
+ *      control={control}
+ *      render={({ field }) => (
+ *        <CheckboxGroup
+ *          label="Interests"
+ *          value={field.value}
+ *          onChange={field.onChange}
+ *          options={[
+ *            { label: "Technology", value: "technology" },
+ *            { label: "Design", value: "design" }
+ *          ]}
+ *        />
+ *      )}
+ *    />
+ */

package/templates/form/checkbox.tsx

@@ -0,0 +1,148 @@
+import React, { useState } from "react";
+import { Check } from "lucide-react";
+import { cn } from "@/utils/cn";
+
+/*
+ * ============================================================================
+ * Types & Interfaces
+ * ============================================================================
+ */
+
+/* Prop configuration for the Checkbox component */
+export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "onChange"> {
+  /* Title label of the checkbox */
+  label?: string;
+  /* Help or descriptive text for the checkbox */
+  description?: string;
+  /* Validation error message specific to this checkbox */
+  error?: string;
+  /* Controls placement of label relative to the checkbox square */
+  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";
+  /* Visual border radius variant */
+  variant?: "rounded" | "curved" | "square" | "circle";
+  /* Callback triggered on selection change */
+  onChange?: (checked: boolean) => void;
+}
+
+/*
+ * ============================================================================
+ * Checkbox Component
+ * ============================================================================
+ */
+
+export const Checkbox = ({
+  label,
+  description,
+  error,
+  labelPlacement = "left",
+  labelWidth,
+  "labelAlign-X": labelAlignX,
+  "labelAlign-Y": labelAlignY = "middle",
+  variant = "rounded",
+  onChange,
+  className,
+  id,
+  ...props
+}: CheckboxProps) => {
+  const checkboxId = id || React.useId();
+  
+  /* Managed checked 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);
+    onChange?.(newChecked);
+  };
+
+  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";
+  const borderRadius = variant === "circle" ? "rounded-full" : variant === "square" ? "rounded-none" : variant === "curved" ? "rounded-md" : "rounded-lg";
+
+  return (
+    <div className={cn("flex flex-col gap-1.5", className)}>
+      {/* Checkbox Input and Selection Wrapper Label */}
+      <label
+        htmlFor={checkboxId}
+        className={cn(
+          "group flex cursor-pointer select-none transition-all duration-200 gap-4",
+          labelPlacement === "top" && "flex-col",
+          /* labelPlacement 'left' aligns the checkbox dot 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="checkbox" 
+            id={checkboxId} 
+            className="peer sr-only" 
+            checked={checked} 
+            onChange={handleChange} 
+          />
+          {/* Outer checkbox border and container */}
+          <div
+            className={cn(
+              "w-5 h-5 transition-all duration-200 flex items-center justify-center border-[1.5px] border-black",
+              borderRadius,
+              checked
+                ? "bg-white scale-110"
+                : "bg-white",
+              "peer-focus-visible:ring-4 peer-focus-visible:ring-sky-500/10 peer-focus-visible:border-sky-500"
+            )}
+          >
+            {/* Checked checkmark icon indicator */}
+            <Check
+              size={12}
+              strokeWidth={4}
+              className={cn(
+                "transition-all duration-200 transform",
+                checked ? "scale-100 opacity-100" : "scale-50 opacity-0",
+                "text-black"
+              )}
+            />
+          </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 capitalize 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>
+  );
+};