pejay-ui 1.4.3 → 1.5.0

package/README.md

@@ -129,15 +129,41 @@ npx pejay-ui add toast
 ```bash
 npx pejay-ui add overlays/portal
 ```
+```bash
+npx pejay-ui add overlays/tooltip
+```
 *(Supports category-wide commands: `npx pejay-ui add overlays --all` or `npx pejay-ui add overlays --select`)*
 
+### Spinners
+```bash
+npx pejay-ui add spinner
+```
+*(Includes a localized `README.md` showing all 9 spinner styles).*
+
+### Skeletons
+```bash
+npx pejay-ui add skeleton
+```
+*(Includes a localized `README.md` showing all skeleton presets).*
+
 ### Scaffolds & Templates
 ```bash
 npx pejay-ui add tanstack-query-client
+```
+```bash
 npx pejay-ui add react-router-client
+```
+```bash
 npx pejay-ui add tanstack-router-client
+```
+```bash
 npx pejay-ui add axios-client
+```
+```bash
 npx pejay-ui add redux-store-client
+```
+```bash
 npx pejay-ui add rtk-query-client
 ```
 *(Supports category-wide commands: `npx pejay-ui add scaffold --all` or `npx pejay-ui add scaffold --select`)*
+

package/bin/cli.js

@@ -38,6 +38,24 @@ const getFilesRecursively = async (dir) => {
   return results;
 };
 
+/*
+ * resolveTargetDir – single source of truth for where a component's files land.
+ *
+ * Priority:
+ *   1. category === "scaffold"  →  src/<targetDirName|key>/
+ *   2. outputDirectory present  →  <baseDir>/<outputDirectory>/
+ *   3. default                  →  <baseDir>/components/<category>/
+ */
+const resolveTargetDir = (cwd, baseDir, compKey, compData) => {
+  if (compData.category === "scaffold") {
+    return path.join(cwd, "src", compData.targetDirName || compKey);
+  }
+  if (compData.outputDirectory) {
+    return path.join(cwd, baseDir, compData.outputDirectory);
+  }
+  return path.join(cwd, baseDir, "components", compData.category);
+};
+
 const loadRegistry = async () => {
   const registryDir = path.join(packageRoot, "registry");
   if (!await fs.pathExists(registryDir)) {
@@ -224,12 +242,7 @@ program
         let isAlreadyPresent = !!config.installed?.[compToInstall];
 
         if (!isAlreadyPresent) {
-          let targetDir;
-          if (componentData.category === "scaffold") {
-            targetDir = path.join(cwd, "src", componentData.targetDirName || compToInstall);
-          } else {
-            targetDir = path.join(cwd, config.baseDir, "components", componentData.category);
-          }
+          let targetDir = resolveTargetDir(cwd, config.baseDir, compToInstall, componentData);
 
           const sourceFiles = componentData.files || (componentData.path ? [componentData.path] : []);
           for (const srcFilePath of sourceFiles) {
@@ -355,12 +368,7 @@ program
         }
 
         // 3. Process & Copy Component Files
-        let targetDir;
-        if (componentData.category === "scaffold") {
-          targetDir = path.join(cwd, "src", componentData.targetDirName || compToInstall);
-        } else {
-          targetDir = path.join(cwd, config.baseDir, "components", componentData.category);
-        }
+        let targetDir = resolveTargetDir(cwd, config.baseDir, compToInstall, componentData);
 
         // Determine list of files to copy
         const sourceFiles = componentData.files || (componentData.path ? [componentData.path] : []);
@@ -391,6 +399,17 @@ program
                 ? `${relativeToUtils}/cn` 
                 : `${relativeToUtils}/cn.js`;
               componentCode = componentCode.replace(/@\/utils\/cn/g, cnImportPath);
+              componentCode = componentCode.replace(/@\/utils/g, cnImportPath);
+
+              const relativeToBaseDir = path.relative(fileDir, path.join(cwd, config.baseDir)).replace(/\\/g, "/");
+              let pejayUiImportPath = relativeToBaseDir;
+              if (!pejayUiImportPath.startsWith(".")) {
+                pejayUiImportPath = `./${pejayUiImportPath}`;
+              }
+              if (pejayUiImportPath.endsWith("/")) {
+                pejayUiImportPath = pejayUiImportPath.slice(0, -1);
+              }
+              componentCode = componentCode.replace(/@\/pejay-ui/g, pejayUiImportPath);
 
               if (!isTsProject) {
                 const transformed = babel.transformSync(componentCode, {
@@ -421,6 +440,17 @@ program
               ? `${relativeToUtils}/cn` 
               : `${relativeToUtils}/cn.js`;
             componentCode = componentCode.replace(/@\/utils\/cn/g, cnImportPath);
+            componentCode = componentCode.replace(/@\/utils/g, cnImportPath);
+
+            const relativeToBaseDir = path.relative(fileDir, path.join(cwd, config.baseDir)).replace(/\\/g, "/");
+            let pejayUiImportPath = relativeToBaseDir;
+            if (!pejayUiImportPath.startsWith(".")) {
+              pejayUiImportPath = `./${pejayUiImportPath}`;
+            }
+            if (pejayUiImportPath.endsWith("/")) {
+              pejayUiImportPath = pejayUiImportPath.slice(0, -1);
+            }
+            componentCode = componentCode.replace(/@\/pejay-ui/g, pejayUiImportPath);
 
             if (!isTsProject) {
               const transformed = babel.transformSync(componentCode, {
@@ -440,7 +470,7 @@ program
         }
 
         // 3.5 Automatically generate/update category-level and global index.ts/index.js files
-        if (componentData.category && !["scaffold", "scaffolds", "script", "scripts"].includes(componentData.category.toLowerCase())) {
+        if (componentData.category && !componentData.skipIndex && !["scaffold", "scaffolds", "script", "scripts"].includes(componentData.category.toLowerCase())) {
           const indexExt = isTsProject ? "ts" : "js";
           const filesInDir = await fs.readdir(targetDir);
           const exportableFiles = [];
@@ -548,9 +578,9 @@ program
       }
 
       // 1.5 Update index files
-      if (componentData.category && !["scaffold", "scaffolds", "script", "scripts"].includes(componentData.category.toLowerCase())) {
+      if (componentData.category && !componentData.skipIndex && !["scaffold", "scaffolds", "script", "scripts"].includes(componentData.category.toLowerCase())) {
         const isTsProject = await fs.pathExists(path.join(cwd, "tsconfig.json"));
-        const targetDir = path.join(cwd, config.baseDir, "components", componentData.category);
+        const targetDir = resolveTargetDir(cwd, config.baseDir, component, componentData);
         const indexExt = isTsProject ? "ts" : "js";
         
         if (await fs.pathExists(targetDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pejay-ui",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "type": "module",
   "description": "A powerful React UI component CLI tool to initialize, add, and scaffold premium Tailwind CSS components, layouts, overlays, and client templates.",
   "bin": {
@@ -66,6 +66,7 @@
     "clsx": "^2.1.1",
     "dayjs": "^1.11.21",
     "lucide-react": "^1.17.0",
+    "motion": "^12.42.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "react-router-dom": "^7.16.0",

package/registry/buttons.json

@@ -2,8 +2,9 @@
   "button": {
     "name": "Button",
     "category": "button",
-    "files": ["templates/button/Button.tsx", "templates/button/tooltip.tsx"],
+    "files": ["templates/button/Button.tsx", "templates/button/README.md"],
     "utils": ["cn.ts"],
-    "peerDependencies": ["clsx", "tailwind-merge"]
+    "peerDependencies": ["clsx", "tailwind-merge"],
+    "dependencies": ["overlays/tooltip", "spinner"]
   }
 }

package/registry/dropdowns.json

@@ -2,7 +2,7 @@
   "dropdown/select-input": {
     "name": "SelectInput",
     "category": "select-dropdown",
-    "files": ["templates/select-dropdown/select-input.tsx"],
+    "files": ["templates/select-dropdown/select-input.tsx", "templates/select-dropdown/README.md"],
     "utils": ["cn.ts"],
     "peerDependencies": [
       "clsx",
@@ -10,6 +10,7 @@
       "lucide-react",
       "@floating-ui/react"
     ],
+    "dependencies": ["overlays/tooltip"],
     "supportsCategory": true
   },
   "dropdown/multiselect-input": {
@@ -23,6 +24,7 @@
       "lucide-react",
       "@floating-ui/react"
     ],
+    "dependencies": ["overlays/tooltip"],
     "supportsCategory": true
   }
 }

package/registry/forms.json

@@ -3,7 +3,8 @@
     "name": "Input",
     "category": "form",
     "files": [
-      "templates/form/input.tsx"
+      "templates/form/text-inputs/input.tsx",
+      "templates/form/text-inputs/readme.input.md"
     ],
     "utils": [
       "cn.ts"
@@ -19,7 +20,8 @@
     "name": "AmountInput",
     "category": "form",
     "files": [
-      "templates/form/amount-input.tsx"
+      "templates/form/numeric/amount-input.tsx",
+      "templates/form/numeric/readme.amount-input.md"
     ],
     "utils": [
       "cn.ts"
@@ -29,13 +31,17 @@
       "tailwind-merge",
       "lucide-react"
     ],
-    "supportsCategory": true
+    "supportsCategory": true,
+    "dependencies": [
+      "form/input"
+    ]
   },
   "form/checkbox": {
     "name": "Checkbox",
     "category": "form",
     "files": [
-      "templates/form/checkbox.tsx"
+      "templates/form/choices/checkbox.tsx",
+      "templates/form/choices/readme.checkbox.md"
     ],
     "utils": [
       "cn.ts"
@@ -51,7 +57,8 @@
     "name": "CheckboxGroup",
     "category": "form",
     "files": [
-      "templates/form/checkbox-group.tsx"
+      "templates/form/choices/checkbox-group.tsx",
+      "templates/form/choices/readme.checkbox-group.md"
     ],
     "utils": [
       "cn.ts"
@@ -69,7 +76,8 @@
     "name": "DatePicker",
     "category": "form",
     "files": [
-      "templates/form/date-picker.tsx"
+      "templates/form/pickers/date-picker.tsx",
+      "templates/form/pickers/readme.date-picker.md"
     ],
     "utils": [
       "cn.ts"
@@ -89,7 +97,8 @@
     "name": "DateRangePicker",
     "category": "form",
     "files": [
-      "templates/form/date-range-picker.tsx"
+      "templates/form/pickers/date-range-picker.tsx",
+      "templates/form/pickers/readme.date-range-picker.md"
     ],
     "utils": [
       "cn.ts"
@@ -109,7 +118,8 @@
     "name": "EmailInput",
     "category": "form",
     "files": [
-      "templates/form/email-input.tsx"
+      "templates/form/text-inputs/email-input.tsx",
+      "templates/form/text-inputs/readme.email-input.md"
     ],
     "utils": [
       "cn.ts"
@@ -125,7 +135,8 @@
     "name": "FileInput",
     "category": "form",
     "files": [
-      "templates/form/file-input.tsx"
+      "templates/form/file/file-input.tsx",
+      "templates/form/file/readme.file-input.md"
     ],
     "utils": [
       "cn.ts"
@@ -135,13 +146,17 @@
       "tailwind-merge",
       "lucide-react"
     ],
-    "supportsCategory": true
+    "supportsCategory": true,
+    "dependencies": [
+      "form/input"
+    ]
   },
   "form/number-input": {
     "name": "NumberInput",
     "category": "form",
     "files": [
-      "templates/form/number-input.tsx"
+      "templates/form/numeric/number-input.tsx",
+      "templates/form/numeric/readme.number-input.md"
     ],
     "utils": [
       "cn.ts"
@@ -151,13 +166,17 @@
       "tailwind-merge",
       "lucide-react"
     ],
-    "supportsCategory": true
+    "supportsCategory": true,
+    "dependencies": [
+      "form/input"
+    ]
   },
   "form/password-input": {
     "name": "PasswordInput",
     "category": "form",
     "files": [
-      "templates/form/password-input.tsx"
+      "templates/form/text-inputs/password-input.tsx",
+      "templates/form/text-inputs/readme.password-input.md"
     ],
     "utils": [
       "cn.ts"
@@ -173,7 +192,8 @@
     "name": "PhoneInput",
     "category": "form",
     "files": [
-      "templates/form/phone-input.tsx"
+      "templates/form/text-inputs/phone-input.tsx",
+      "templates/form/text-inputs/readme.phone-input.md"
     ],
     "utils": [
       "cn.ts"
@@ -189,7 +209,8 @@
     "name": "Radio",
     "category": "form",
     "files": [
-      "templates/form/radio.tsx"
+      "templates/form/choices/radio.tsx",
+      "templates/form/choices/readme.radio.md"
     ],
     "utils": [
       "cn.ts"
@@ -204,7 +225,8 @@
     "name": "RadioGroup",
     "category": "form",
     "files": [
-      "templates/form/radio-group.tsx"
+      "templates/form/choices/radio-group.tsx",
+      "templates/form/choices/readme.radio-group.md"
     ],
     "utils": [
       "cn.ts"
@@ -222,7 +244,8 @@
     "name": "RangeSlider",
     "category": "form",
     "files": [
-      "templates/form/range-slider.tsx"
+      "templates/form/numeric/range-slider.tsx",
+      "templates/form/numeric/readme.range-slider.md"
     ],
     "utils": [
       "cn.ts"
@@ -237,7 +260,8 @@
     "name": "Switch",
     "category": "form",
     "files": [
-      "templates/form/switch.tsx"
+      "templates/form/choices/switch.tsx",
+      "templates/form/choices/readme.switch.md"
     ],
     "utils": [
       "cn.ts"
@@ -252,7 +276,8 @@
     "name": "Textarea",
     "category": "form",
     "files": [
-      "templates/form/textarea.tsx"
+      "templates/form/text-inputs/textarea.tsx",
+      "templates/form/text-inputs/readme.textarea.md"
     ],
     "utils": [
       "cn.ts"
@@ -267,7 +292,8 @@
     "name": "TimePicker",
     "category": "form",
     "files": [
-      "templates/form/time-picker.tsx"
+      "templates/form/pickers/time-picker.tsx",
+      "templates/form/pickers/readme.time-picker.md"
     ],
     "utils": [
       "cn.ts"
@@ -287,7 +313,8 @@
     "name": "TimeRangePicker",
     "category": "form",
     "files": [
-      "templates/form/time-range-picker.tsx"
+      "templates/form/pickers/time-range-picker.tsx",
+      "templates/form/pickers/readme.time-range-picker.md"
     ],
     "utils": [
       "cn.ts"
@@ -307,7 +334,8 @@
     "name": "UrlInput",
     "category": "form",
     "files": [
-      "templates/form/url-input.tsx"
+      "templates/form/text-inputs/url-input.tsx",
+      "templates/form/text-inputs/readme.url-input.md"
     ],
     "utils": [
       "cn.ts"
@@ -319,4 +347,4 @@
     ],
     "supportsCategory": true
   }
-}
+}

package/registry/hotkeys.json

@@ -0,0 +1,12 @@
+{
+  "hotkeys": {
+    "name": "Hotkeys",
+    "category": "hotkeys",
+    "outputDirectory": "hotkeys",
+    "skipIndex": true,
+    "files": ["templates/hotkeys"],
+    "peerDependencies": [
+      "lucide-react"
+    ]
+  }
+}

package/registry/overlays.json

@@ -2,7 +2,23 @@
   "overlays/portal": {
     "name": "Portal",
     "category": "overlays",
-    "files": ["templates/overlays/portal.tsx"],
+    "files": [
+      "templates/overlays/portal/portal.tsx"
+    ],
     "supportsCategory": true
+  },
+  "overlays/tooltip": {
+    "name": "Tooltip",
+    "category": "overlays",
+    "files": [
+      "templates/overlays/tooltip/tooltip.tsx",
+      "templates/overlays/tooltip/readme.tooltip.md"
+    ],
+    "supportsCategory": true,
+    "peerDependencies": [
+      "clsx",
+      "tailwind-merge",
+      "@floating-ui/react"
+    ]
   }
-}
+}

package/registry/panels.json

@@ -0,0 +1,21 @@
+{
+  "panels": {
+    "name": "Panels",
+    "category": "panels",
+    "outputDirectory": "panels",
+    "skipIndex": true,
+    "files": ["templates/panels"],
+    "utils": ["cn.ts"],
+    "dependencies": [
+      "overlays/portal",
+      "toast",
+      "hotkeys"
+    ],
+    "peerDependencies": [
+      "clsx",
+      "tailwind-merge",
+      "lucide-react",
+      "motion"
+    ]
+  }
+}

package/registry/skeleton.json

@@ -0,0 +1,20 @@
+{
+  "skeleton": {
+    "name": "Skeleton",
+    "category": "skeleton",
+    "files": [
+      "templates/skeleton/skeleton.tsx",
+      "templates/skeleton/types.ts",
+      "templates/skeleton/skeleton.css",
+      "templates/skeleton/README.md"
+    ],
+    "utils": [
+      "cn.ts"
+    ],
+    "peerDependencies": [
+      "clsx",
+      "tailwind-merge"
+    ],
+    "supportsCategory": true
+  }
+}

package/registry/spinner.json

@@ -0,0 +1,13 @@
+{
+  "spinner": {
+    "name": "Spinner",
+    "category": "spinner",
+    "outputDirectory": "spinner",
+    "skipIndex": true,
+    "files": [
+      "templates/spinner/spinner.tsx",
+      "templates/spinner/spinner.css",
+      "templates/spinner/README.md"
+    ]
+  }
+}

package/templates/button/Button.tsx

@@ -1,7 +1,8 @@
 import React from "react";
-import { cn } from "@/utils/cn";
+import { cn } from "@/pejay-ui/utils/cn";
 
-import { Tooltip } from "./tooltip";
+import { Spinner } from "@/pejay-ui/spinner";
+import { Tooltip } from "@/pejay-ui/components/overlays";
 
 /* ─────────────────────────────────────────────
    Types
@@ -28,7 +29,8 @@ export type ButtonVariant =
   | "success-ghost"
   | "warning-ghost"
   | "black-ghost"
-  | "white-ghost";
+  | "white-ghost"
+  | "soft";
 export type RoundedStyle = "full" | "lg" | "md" | "sm" | "none";
 
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
@@ -67,6 +69,7 @@ const variantMap: Record<ButtonVariant, string> = {
   warning: "bg-amber-500   hover:bg-amber-600   active:bg-amber-700   text-white",
   black:   "bg-black       hover:bg-black/80    active:bg-black/70    text-white",
   white:   "bg-white       hover:bg-white/80    active:bg-white/70    text-black",
+  soft:    "bg-sky-500/10  hover:bg-sky-500/20  active:bg-sky-500/30  text-sky-500",
 
   /* ── Soft (coloured text, always-visible tint) ───────── */
   "primary-soft": "text-sky-500     bg-current/10 hover:bg-current/15 active:bg-current/20",
@@ -119,10 +122,8 @@ export const Button = ({
     ? stripInteractive(variantMap[variant])
     : variantMap[variant];
 
-  /* Render content: loader node / fallback text / normal children */
-  const content = isLoading
-    ? (loader ?? <span className="text-sm font-medium">Loading…</span>)
-    : children;
+  /* Render content: loader node / spinner / normal children */
+  const content = isLoading ? (loader ?? <Spinner size="sm" />) : children;
 
   return (
     <Tooltip content={tooltipContent}>

package/templates/button/README.md

@@ -0,0 +1,81 @@
+# Button & Tooltip Components
+
+A highly flexible button component with built-in loading states, visual style presets (variants), size options, prefix/suffix icon slots, and hover tooltip support.
+
+---
+
+## 1. Button Usage & API
+
+```tsx
+import { Button } from "@/pejay-ui/components/button";
+
+// Basic Button
+<Button onClick={handleClick}>Click Me</Button>
+
+// Custom Styling & Icons
+<Button variant="danger" size="lg" icon={TrashIcon} loading={isDeleting}>
+  Delete Record
+</Button>
+```
+
+### Component Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | Text or elements inside the button. |
+| `variant` | `ButtonVariant` | `"primary"` | Visual preset theme style. (See options below) |
+| `rounded` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"lg"` | Controls the button border radius. |
+| `disableHoverEffect` | `boolean` | `false` | Removes hover/active style transforms (keeps it static). |
+| `isLoading` | `boolean` | `false` | Displays a loading spinner and disables clicks. |
+| `loader` | `ReactNode` | — | Custom loading component override. |
+| `fullWidth` | `boolean` | `false` | Sets button width to `w-full` (100% parent container width). |
+| `tooltipContent` | `ReactNode \| string` | — | Display a hover tooltip panel with this content. |
+
+---
+
+## 2. Visual Variants & Color Palette Reference
+
+We categorize button variants into 3 distinct styling structures. Colors are predefined and tailored for dark/light contrast:
+
+### A. Solid Variants (Filled background, white/black text)
+* **`primary`** : Sky Blue (`bg-sky-500` $\rightarrow$ hover `bg-sky-600` $\rightarrow$ active `bg-sky-700`)
+* **`danger`** : Red (`bg-red-600` $\rightarrow$ hover `bg-red-700` $\rightarrow$ active `bg-red-800`)
+* **`success`** : Emerald (`bg-emerald-600` $\rightarrow$ hover `bg-emerald-700` $\rightarrow$ active `bg-emerald-800`)
+* **`warning`** : Amber (`bg-amber-500` $\rightarrow$ hover `bg-amber-600` $\rightarrow$ active `bg-amber-700`)
+* **`black`** : Black (`bg-black` $\rightarrow$ hover `bg-black/80` $\rightarrow$ active `bg-black/70`)
+* **`white`** : White (`bg-white`, text black $\rightarrow$ hover `bg-white/80` $\rightarrow$ active `bg-white/70`)
+
+---
+
+### B. Soft Variants (Always-visible colored tint background + matching text color)
+*Soft variants use `bg-current` opacity mappings, meaning the background tint color automatically inherits and matches the text color:*
+* **`primary-soft`** / **`soft`** : Sky Blue text + 10% opacity Sky Blue background.
+* **`danger-soft`** : Red text + 10% opacity Red background.
+* **`success-soft`** : Emerald text + 10% opacity Emerald background.
+* **`warning-soft`** : Amber text + 10% opacity Amber background.
+* **`black-soft`** : Black text + 10% opacity Black background.
+* **`white-soft`** : White text + 10% opacity White background.
+
+---
+
+### C. Ghost Variants (Transparent background $\rightarrow$ fades in soft tint on hover)
+* **`primary-ghost`** : Sky Blue text.
+* **`danger-ghost`** : Red text.
+* **`success-ghost`** : Emerald text.
+* **`warning-ghost`** : Amber text.
+* **`black-ghost`** : Black text.
+* **`white-ghost`** : White text.
+
+---
+
+## 3. Tooltip Component
+
+A standalone utility to show extra info bubbles on hover for any parent component.
+
+```tsx
+import { Tooltip } from "@/pejay-ui/components/overlays/tooltip";
+
+<Tooltip content="Upload CSV file" placement="bottom">
+  <div className="p-2 border rounded">Hover Over Me</div>
+</Tooltip>
+```

package/templates/button/index.ts

@@ -1,2 +1 @@
-export * from "./Button";
-export * from "./tooltip";
+export * from "./Button";

package/templates/form/{checkbox-group.tsx → choices/checkbox-group.tsx}

@@ -1,5 +1,5 @@
 import React from "react";
-import { cn } from "@/utils/cn";
+import { cn } from "@/pejay-ui/utils/cn";
 import { Checkbox, type CheckboxProps } from "./checkbox";
 
 /*

package/templates/form/{checkbox.tsx → choices/checkbox.tsx}

@@ -1,6 +1,6 @@
 import React, { useState } from "react";
 import { Check } from "lucide-react";
-import { cn } from "@/utils/cn";
+import { cn } from "@/pejay-ui/utils/cn";
 
 /*
  * ============================================================================

package/templates/form/{radio-group.tsx → choices/radio-group.tsx}

@@ -1,5 +1,5 @@
 import React from "react";
-import { cn } from "@/utils/cn";
+import { cn } from "@/pejay-ui/utils/cn";
 import { Radio, type RadioProps } from "./radio";
 
 /*