nexstruct 1.0.0

package/templates/ui/shadcn/src/components/common/fields/assets/components/check-field.component.tsx

@@ -0,0 +1,52 @@
+import { FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form.component';
+import { Checkbox } from '@/components/ui/checkbox.component';
+import type { CheckboxProps } from '../interface/input-props.type';
+
+export const CheckField = ({
+  form, name, labelName, required = false, disabled = false, options = [],
+}: CheckboxProps & { options: { label: string; value: string }[] }) => {
+  if (!form) return null;
+
+  return (
+    <FormField
+      control={form.control}
+      name={name}
+      render={() => (
+        <FormItem>
+          {labelName && (
+            <label className="font-semibold leading-6 text-[14px] tracking-[0.02em]">
+              {labelName}
+              {required && <span className="text-destructive">&nbsp;*</span>}
+            </label>
+          )}
+          {options.map((opt) => (
+            <FormField
+              key={opt.value}
+              control={form.control}
+              name={name}
+              render={({ field }) => (
+                <div className="flex items-center space-x-2">
+                  <FormControl>
+                    <Checkbox
+                      checked={field.value?.includes(opt.value)}
+                      onCheckedChange={(checked) => {
+                        const current = field.value || [];
+                        const updated = checked
+                          ? [...current, opt.value]
+                          : current.filter((v: string) => v !== opt.value);
+                        field.onChange(updated);
+                      }}
+                      disabled={disabled}
+                    />
+                  </FormControl>
+                  <FormLabel className="font-normal">{opt.label}</FormLabel>
+                </div>
+              )}
+            />
+          ))}
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+};

package/templates/ui/shadcn/src/components/common/fields/assets/components/date-picker-field.component.tsx

@@ -0,0 +1,62 @@
+import { FormControl, FormField, FormItem, FormMessage } from '@/components/ui/form.component';
+import { Input } from '@/components/ui/input.component';
+import { LabelAndPlaceholderTextFormat } from '@/lib/utils.util';
+import type { InputInterface } from '../interface/input-props.type';
+
+export const DatePickerField = ({
+  form, name, labelName, placeholder, required = false, disabled = false,
+  viewOnly = false, disableLabelFormatting = false, customMessage,
+}: InputInterface['DatePicker']) => {
+  const placeholderText = disableLabelFormatting
+    ? placeholder || labelName
+    : LabelAndPlaceholderTextFormat(placeholder || labelName || '');
+
+  const LabelEl = () =>
+    labelName ? (
+      <label className="font-semibold leading-6 text-[14px] tracking-[0.02em]">
+        {disableLabelFormatting ? labelName : LabelAndPlaceholderTextFormat(labelName)}
+        {required && <span className="text-destructive">&nbsp;*</span>}
+      </label>
+    ) : null;
+
+  if (form) {
+    return (
+      <FormField
+        control={form.control}
+        name={name || 'date'}
+        render={({ field }) => {
+          const error = form.formState.errors?.[name || ''];
+          return (
+            <FormItem>
+              <LabelEl />
+              {viewOnly ? (
+                <div className="py-2 px-3 text-sm text-foreground bg-background rounded-md border border-border min-h-10">
+                  {field.value ? new Date(field.value).toLocaleDateString() : ''}
+                </div>
+              ) : (
+                <>
+                  <FormControl>
+                    <Input
+                      type="date"
+                      placeholder={placeholderText}
+                      disabled={disabled}
+                      {...field}
+                    />
+                  </FormControl>
+                  <FormMessage>{error ? String(error?.message || '') : customMessage || ''}</FormMessage>
+                </>
+              )}
+            </FormItem>
+          );
+        }}
+      />
+    );
+  }
+
+  return (
+    <>
+      <LabelEl />
+      <Input type="date" placeholder={placeholderText} />
+    </>
+  );
+};

package/templates/ui/shadcn/src/components/common/fields/assets/components/dynamic-file-upload-field.component.tsx

@@ -0,0 +1,152 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+'use client';
+
+import { FormControl, FormField, FormItem, FormMessage } from '@/components/ui/form.component';
+import { Button } from '@/components/ui/button.component';
+import { Upload, X, File, Eye } from 'lucide-react';
+import { useRef, useState } from 'react';
+
+interface FilePreview {
+  id: string;
+  name: string;
+  url: string;
+  size: number;
+  isUploaded: boolean;
+}
+
+interface DynamicFileUploadFieldProps {
+  form: any;
+  name: string;
+  labelName?: string;
+  optional?: boolean;
+  viewOnly?: boolean;
+  multiple?: boolean;
+  maxSizeMB?: number;
+  accept?: string;
+  onUpload?: (file: File) => Promise<string>;
+}
+
+/**
+ * DynamicFileUploadField — Drag-and-drop style file upload.
+ *
+ * ⚠️ Stores URL strings in the form value, NOT raw File objects.
+ * - If onUpload is provided: stores the returned URL after upload
+ * - If onUpload is omitted: stores an object with file metadata
+ *   (no raw File objects in form state)
+ */
+export const DynamicFileUploadField = ({
+  form, name, labelName, optional = false, viewOnly = false,
+  multiple = false, maxSizeMB = 5, accept = '*', onUpload,
+}: DynamicFileUploadFieldProps) => {
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const filesRef = useRef<Map<string, File>>(new Map());
+  const [uploading, setUploading] = useState(false);
+  const [previews, setPreviews] = useState<FilePreview[]>([]);
+
+  const handleFiles = async (files: FileList | null) => {
+    if (!files?.length) return;
+    const fileArray = Array.from(files);
+
+    for (const file of fileArray) {
+      if (file.size > maxSizeMB * 1024 * 1024) {
+        alert(`File ${file.name} exceeds ${maxSizeMB}MB`);
+        return;
+      }
+    }
+
+    const newPreviews: FilePreview[] = fileArray.map((f) => ({
+      id: `${f.name}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      name: f.name,
+      url: URL.createObjectURL(f),
+      size: f.size,
+      isUploaded: false,
+    }));
+
+    // Store File refs for later upload
+    newPreviews.forEach((p, i) => filesRef.current.set(p.id, fileArray[i]));
+
+    if (onUpload) {
+      setUploading(true);
+      try {
+        const urls = await Promise.all(fileArray.map((f) => onUpload(f)));
+        const updated = newPreviews.map((p, i) => ({ ...p, url: urls[i], isUploaded: true }));
+        setPreviews((prev) => [...prev, ...updated]);
+        // Store URL strings in form
+        form.setValue(name, multiple ? updated.map((u) => u.url) : updated[0].url, { shouldValidate: true });
+      } finally {
+        setUploading(false);
+      }
+    } else {
+      // No upload handler: store metadata objects (strings only, no File objects)
+      const metadata = newPreviews.map((p) => ({ id: p.id, name: p.name, size: p.size, type: 'pending' }));
+      setPreviews((prev) => [...prev, ...newPreviews]);
+      form.setValue(name, multiple ? metadata : metadata[0], { shouldValidate: true });
+    }
+  };
+
+  const handleRemove = (id: string) => {
+    setPreviews((prev) => {
+      const removed = prev.find((p) => p.id === id);
+      if (removed) URL.revokeObjectURL(removed.url);
+      const updated = prev.filter((p) => p.id !== id);
+      filesRef.current.delete(id);
+      // Update form value
+      if (multiple) {
+        form.setValue(name, updated.map((u) => onUpload ? u.url : { id: u.id, name: u.name, size: u.size }), { shouldValidate: true });
+      } else {
+        form.setValue(name, null, { shouldValidate: true });
+      }
+      return updated;
+    });
+  };
+
+  return (
+    <FormField
+      control={form.control}
+      name={name}
+      render={() => (
+        <FormItem>
+          {labelName && (
+            <label className="font-semibold leading-6 text-[14px] tracking-[0.02em]">
+              {labelName}
+              {!optional && <span className="text-destructive">&nbsp;*</span>}
+            </label>
+          )}
+          {!viewOnly && (
+            <div className="border-2 border-dashed rounded-lg p-6 text-center hover:border-primary/50 transition-colors cursor-pointer"
+              onClick={() => fileInputRef.current?.click()}>
+              <Upload className="h-8 w-8 mx-auto text-muted-foreground" />
+              <p className="mt-2 text-sm text-muted-foreground">
+                {uploading ? 'Uploading...' : `Click to upload${multiple ? ' (multiple)' : ''}`}
+              </p>
+              <p className="text-xs text-muted-foreground">Max {maxSizeMB}MB per file</p>
+              <input ref={fileInputRef} type="file" accept={accept} multiple={multiple} className="hidden"
+                onChange={(e) => handleFiles(e.target.files)} />
+            </div>
+          )}
+          {previews.length > 0 && (
+            <div className="space-y-2">
+              {previews.map((p) => (
+                <div key={p.id} className="flex items-center justify-between p-2 border rounded">
+                  <div className="flex items-center gap-2">
+                    <File className="h-4 w-4 text-muted-foreground" />
+                    <span className="text-sm truncate max-w-[200px]">{p.name}</span>
+                  </div>
+                  <div className="flex items-center gap-1">
+                    {p.isUploaded && <Eye className="h-4 w-4 text-muted-foreground cursor-pointer" />}
+                    {!viewOnly && (
+                      <button type="button" onClick={() => handleRemove(p.id)}>
+                        <X className="h-4 w-4 text-destructive" />
+                      </button>
+                    )}
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+};

package/templates/ui/shadcn/src/components/common/fields/assets/components/limit-field.component.tsx

@@ -0,0 +1,73 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+'use client';
+
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import { useEffect, useState } from 'react';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip.component';
+import { SingleSelectField } from './single-select-field.component';
+
+interface LimitFieldProps {
+  setLimit: (limit: string) => void;
+  options?: string[];
+  totalItems?: number;
+  setCurrentPage?: (data: number) => void;
+  placeholder?: string;
+}
+
+/**
+ * LimitField — Dropdown for selecting items per page.
+ * Syncs with URL query param `pageSize`. Resets to page 1 on change.
+ */
+export const LimitField = ({
+  setLimit,
+  options,
+  totalItems = 100,
+  setCurrentPage,
+  placeholder = 'Entries per page',
+}: LimitFieldProps) => {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const router = useRouter();
+
+  const defaultOptions = ['10', '20', '30', '40', '50', '100'];
+  const baseOptions = options ?? defaultOptions;
+
+  // Only show options up to the total items count
+  const lastIndex = baseOptions.findIndex((opt) => Number(opt) >= totalItems);
+  const OptionsList = lastIndex === -1 ? baseOptions : baseOptions.slice(0, lastIndex + 1);
+
+  const currentLimit = searchParams.get('pageSize') || '10';
+
+  const handleLimitChange = (newLimit: string) => {
+    const params = new URLSearchParams(searchParams);
+    params.set('pageSize', newLimit);
+    params.set('page', '1'); // reset to first page
+    router.push(`${pathname}?${params.toString()}`);
+
+    setLimit(newLimit);
+    setCurrentPage?.(1);
+  };
+
+  useEffect(() => {
+    setLimit(currentLimit);
+  }, [currentLimit, setLimit]);
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <div>
+          <SingleSelectField
+            name="limit"
+            placeholder={placeholder}
+            options={OptionsList}
+            onValueChange={handleLimitChange}
+            defaultValue={currentLimit}
+          />
+        </div>
+      </TooltipTrigger>
+      <TooltipContent className="bg-muted-foreground text-primary-foreground">
+        <p className="text-[10px]">Number of entries per page</p>
+      </TooltipContent>
+    </Tooltip>
+  );
+};

package/templates/ui/shadcn/src/components/common/fields/assets/components/multi-check-field.component.tsx

@@ -0,0 +1,46 @@
+import { FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form.component';
+import { Checkbox } from '@/components/ui/checkbox.component';
+
+export const MultiCheckField = ({
+  form, name, labelName, options = [],
+}: {
+  form: any; name: string; labelName?: string; options?: { label: string; value: string }[];
+}) => {
+  if (!form) return null;
+
+  return (
+    <FormField
+      control={form.control}
+      name={name}
+      render={() => (
+        <FormItem>
+          {labelName && <label className="font-semibold leading-6 text-[14px] tracking-[0.02em]">{labelName}</label>}
+          {options.map((opt) => (
+            <FormField
+              key={opt.value}
+              control={form.control}
+              name={name}
+              render={({ field }) => (
+                <div className="flex items-center space-x-2">
+                  <FormControl>
+                    <Checkbox
+                      checked={field.value?.includes(opt.value)}
+                      onCheckedChange={(checked) => {
+                        const current = field.value || [];
+                        field.onChange(
+                          checked ? [...current, opt.value] : current.filter((v: string) => v !== opt.value)
+                        );
+                      }}
+                    />
+                  </FormControl>
+                  <FormLabel className="font-normal">{opt.label}</FormLabel>
+                </div>
+              )}
+            />
+          ))}
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+};

package/templates/ui/shadcn/src/components/common/fields/assets/components/number-field.component.tsx

@@ -0,0 +1,124 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+'use client';
+
+import { FormControl, FormField, FormItem, FormMessage } from '@/components/ui/form.component';
+import { Input } from '@/components/ui/input.component';
+import { LabelAndPlaceholderTextFormat } from '@/lib/utils.util';
+import type { InputInterface } from '../interface/input-props.type';
+
+/**
+ * Number — A robust numeric input field with:
+ * - Integer or float mode
+ * - Scroll prevention (blurs on wheel)
+ * - Key filtering (blocks non-numeric chars)
+ * - Minimum value of 0
+ * - Edge case handling for empty/NaN values
+ * - Dual-mode: with or without react-hook-form
+ */
+export const Number = ({
+  form, name, labelName, placeholder, required = false, disabled = false,
+  viewOnly = false, disableLabelFormatting = false, numberType = 'integer', customMessage,
+}: InputInterface['Number']) => {
+  const placeholderText = disableLabelFormatting
+    ? placeholder || labelName
+    : LabelAndPlaceholderTextFormat(placeholder || labelName || '');
+
+  const LabelEl = () =>
+    labelName ? (
+      <label className="font-semibold leading-6 text-[14px] tracking-[0.02em]">
+        {disableLabelFormatting ? labelName : LabelAndPlaceholderTextFormat(labelName)}
+        {required && <span className="text-destructive">&nbsp;*</span>}
+      </label>
+    ) : null;
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    // Allow: backspace, delete, tab, escape, enter, arrows
+    const allowedKeys = [
+      'Backspace', 'Delete', 'Tab', 'Escape', 'Enter',
+      'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End',
+    ];
+    if (allowedKeys.includes(e.key)) return;
+    // Allow Ctrl/Cmd shortcuts
+    if (e.ctrlKey || e.metaKey) return;
+
+    // For integers: only digits
+    if (numberType === 'integer') {
+      if (!/^\d$/.test(e.key)) { e.preventDefault(); }
+      return;
+    }
+
+    // For floats: digits and single decimal point
+    if (numberType === 'float') {
+      const currentValue = (e.target as HTMLInputElement).value;
+      if (e.key === '.' && !currentValue.includes('.')) return;
+      if (!/^\d$/.test(e.key)) { e.preventDefault(); }
+    }
+  };
+
+  const handleChange = (value: string, onChange: (val: any) => void) => {
+    if (value === '') {
+      onChange('');
+      return;
+    }
+
+    const parsed = numberType === 'float' ? parseFloat(value) : parseInt(value, 10);
+    if (!isNaN(parsed) && parsed >= 0) {
+      onChange(parsed);
+    } else {
+      onChange('');
+    }
+  };
+
+  if (form) {
+    return (
+      <FormField
+        control={form.control}
+        name={name || 'number'}
+        render={({ field }) => {
+          const error = form.formState.errors?.[name || ''];
+          return (
+            <FormItem>
+              <LabelEl />
+              {viewOnly ? (
+                <div className="py-2 px-3 text-sm text-foreground bg-background rounded-md border border-border min-h-10">
+                  {field.value ?? ''}
+                </div>
+              ) : (
+                <>
+                  <FormControl>
+                    <Input
+                      type="number"
+                      step={numberType === 'float' ? 'any' : '0'}
+                      min={0}
+                      placeholder={placeholderText}
+                      disabled={disabled}
+                      value={field.value ?? ''}
+                      onWheel={(e) => (e.target as HTMLInputElement).blur()}
+                      onKeyDown={handleKeyDown}
+                      onChange={(e) => handleChange(e.target.value, field.onChange)}
+                      className="[&::-webkit-outer-spin-button]:appearance-none [&::-webkit-inner-spin-button]:appearance-none [appearance:textfield]"
+                    />
+                  </FormControl>
+                  <FormMessage>{error ? String(error?.message || '') : customMessage || ''}</FormMessage>
+                </>
+              )}
+            </FormItem>
+          );
+        }}
+      />
+    );
+  }
+
+  return (
+    <>
+      <LabelEl />
+      <Input
+        type="number"
+        step={numberType === 'float' ? 'any' : '0'}
+        placeholder={placeholderText}
+        onWheel={(e) => (e.target as HTMLInputElement).blur()}
+        onKeyDown={handleKeyDown}
+      />
+    </>
+  );
+};

package/templates/ui/shadcn/src/components/common/fields/assets/components/otp-field.component.tsx

@@ -0,0 +1,61 @@
+import { FormControl, FormField, FormItem, FormMessage } from '@/components/ui/form.component';
+import { InputOTP, InputOTPGroup, InputOTPSlot } from '@/components/ui/input-otp.component';
+import { LabelAndPlaceholderTextFormat } from '@/lib/utils.util';
+
+export const OTP = ({
+  form, name, labelName, required = false, disableLabelFormatting = false,
+  maxLength = 6, customMessage,
+}: {
+  form?: any; name?: string; labelName?: string; required?: boolean;
+  disableLabelFormatting?: boolean; maxLength?: number; customMessage?: React.ReactNode;
+}) => {
+  if (!form) {
+    return (
+      <div>
+        {labelName && (
+          <label className="font-semibold leading-6 text-[14px] tracking-[0.02em]">
+            {disableLabelFormatting ? labelName : LabelAndPlaceholderTextFormat(labelName)}
+            {required && <span className="text-destructive">&nbsp;*</span>}
+          </label>
+        )}
+        <InputOTP maxLength={maxLength}>
+          <InputOTPGroup>
+            {Array.from({ length: maxLength }).map((_, i) => (
+              <InputOTPSlot key={i} index={i} />
+            ))}
+          </InputOTPGroup>
+        </InputOTP>
+      </div>
+    );
+  }
+
+  return (
+    <FormField
+      control={form.control}
+      name={name || 'otp'}
+      render={({ field }) => {
+        const error = form.formState.errors?.[name || ''];
+        return (
+          <FormItem>
+            {labelName && (
+              <label className="font-semibold leading-6 text-[14px] tracking-[0.02em]">
+                {disableLabelFormatting ? labelName : LabelAndPlaceholderTextFormat(labelName)}
+                {required && <span className="text-destructive">&nbsp;*</span>}
+              </label>
+            )}
+            <FormControl>
+              <InputOTP maxLength={maxLength} value={field.value} onChange={field.onChange}>
+                <InputOTPGroup>
+                  {Array.from({ length: maxLength }).map((_, i) => (
+                    <InputOTPSlot key={i} index={i} />
+                  ))}
+                </InputOTPGroup>
+              </InputOTP>
+            </FormControl>
+            <FormMessage>{error ? String(error?.message || '') : customMessage || ''}</FormMessage>
+          </FormItem>
+        );
+      }}
+    />
+  );
+};

package/templates/ui/shadcn/src/components/common/fields/assets/components/password-field.component.tsx

@@ -0,0 +1,110 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+'use client';
+
+import { useState } from 'react';
+import { FormControl, FormField, FormItem, FormMessage } from '@/components/ui/form.component';
+import { Input } from '@/components/ui/input.component';
+import { LabelAndPlaceholderTextFormat, passwordRules } from '@/lib/utils.util';
+import { Eye, EyeOff } from 'lucide-react';
+import type { InputInterface } from '../interface/input-props.type';
+
+/**
+ * Password — Reusable password input with:
+ * - Show/hide toggle
+ * - Optional strength validation rules (mode="validate")
+ * - Dual-mode: with or without react-hook-form
+ */
+export const Password = ({
+  form, name, labelName, placeholder, required = false, disabled = false,
+  disableLabelFormatting = false, mode = 'normal', customMessage,
+}: InputInterface['Password']) => {
+  const [showPassword, setShowPassword] = useState(false);
+  const [passwordValue, setPasswordValue] = useState('');
+
+  const placeholderText = disableLabelFormatting
+    ? placeholder || labelName
+    : LabelAndPlaceholderTextFormat(placeholder || labelName || '');
+
+  const LabelEl = () =>
+    labelName ? (
+      <label className="font-semibold leading-6 text-[14px] tracking-[0.02em]">
+        {disableLabelFormatting ? labelName : LabelAndPlaceholderTextFormat(labelName)}
+        {required && <span className="text-destructive">&nbsp;*</span>}
+      </label>
+    ) : null;
+
+  const renderStrengthRules = () => {
+    if (mode !== 'validate' || !passwordValue) return null;
+    if (passwordRules.every((rule) => rule.test(passwordValue))) return null;
+
+    return (
+      <ul className="mt-2 space-y-1 text-sm">
+        {passwordRules.map((rule, index) => {
+          const passed = rule.test(passwordValue);
+          return (
+            <li
+              key={index}
+              className={`flex items-center gap-2 ${passed ? 'text-green-600' : 'text-muted-foreground'}`}
+            >
+              <span className={`w-2 h-2 rounded-full inline-block ${passed ? 'bg-green-500' : 'bg-muted-foreground/30'}`} />
+              {rule.label}
+            </li>
+          );
+        })}
+      </ul>
+    );
+  };
+
+  const renderInput = (fieldProps?: Record<string, any>) => (
+    <div className="w-full relative">
+      <Input
+        type={showPassword ? 'text' : 'password'}
+        placeholder={placeholderText}
+        disabled={disabled}
+        className="pr-10"
+        {...fieldProps}
+        onChange={(e) => {
+          fieldProps?.onChange?.(e);
+          setPasswordValue(e.target.value);
+        }}
+      />
+      <button
+        type="button"
+        onClick={() => setShowPassword(!showPassword)}
+        className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground transition-colors"
+        tabIndex={-1}
+      >
+        {showPassword ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
+      </button>
+    </div>
+  );
+
+  if (form) {
+    return (
+      <FormField
+        control={form.control}
+        name={name || 'password'}
+        render={({ field }) => {
+          const error = form.formState.errors?.[name || ''];
+          return (
+            <FormItem>
+              <LabelEl />
+              <FormControl>
+                {renderInput({ ...field, value: passwordValue || field.value || '' })}
+              </FormControl>
+              {renderStrengthRules()}
+              <FormMessage>{error ? String(error?.message || '') : customMessage || ''}</FormMessage>
+            </FormItem>
+          );
+        }}
+      />
+    );
+  }
+
+  return (
+    <>
+      <LabelEl />
+      {renderInput()}
+    </>
+  );
+};