pejay-ui 1.4.2 → 1.5.0

package/templates/panels/vendor-example/by-using-modal/vendor-modal-form.tsx

@@ -0,0 +1,112 @@
+import { useCallback, useState } from "react";
+import { ModalCard } from "../../components/modal/modal-card";
+import { useFormDirty } from "../../hooks/useFormDirty";
+import { requestOverlayCloseWithConfirm } from "../../core/overlay-close";
+import type { Vendor } from "./vendor-types";
+import {
+  getDefaultVendorFormValues,
+  vendorToFormValues,
+  type VendorFormValues,
+} from "./vendor-types";
+
+export type VendorFormMode = "create" | "update";
+
+export type VendorModalFormProps = {
+  close: () => void;
+  mode?: VendorFormMode;
+  vendor?: Vendor;
+};
+
+export function VendorModalForm({
+  close,
+  mode = "create",
+  vendor,
+}: VendorModalFormProps) {
+  const isUpdate = mode === "update";
+
+  const [values, setValues] = useState<VendorFormValues>(() => ({
+    ...getDefaultVendorFormValues(),
+    ...(vendor ? vendorToFormValues(vendor) : {}),
+  }));
+
+  const setField = useCallback(
+    <K extends keyof VendorFormValues>(key: K, value: VendorFormValues[K]) => {
+      setValues((prev) => ({ ...prev, [key]: value }));
+    },
+    [],
+  );
+
+  const isDirty = useFormDirty(values);
+
+  const handleSave = () => {
+    if (!values.vendorName.trim()) {
+      alert("Vendor name is required");
+      return;
+    }
+    console.log("Saving vendor:", values);
+    close();
+  };
+
+  return (
+    <ModalCard
+      title={isUpdate ? "Edit Vendor" : "Add Vendor"}
+      description={isUpdate ? "Update the vendor's details below." : "Fill in the new vendor's details."}
+      close={close}
+      onSubmit={handleSave}
+      isDirty={isDirty}
+      size="md"
+      footer={
+        <div className="flex justify-end gap-3">
+          <button
+            type="button"
+            onClick={requestOverlayCloseWithConfirm}
+            className="px-4 py-2 border border-slate-200 rounded text-sm hover:bg-slate-50 transition-colors cursor-pointer"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={handleSave}
+            className="px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded text-sm transition-colors cursor-pointer"
+          >
+            Save
+          </button>
+        </div>
+      }
+    >
+      <div className="space-y-4">
+        <div className="flex flex-col gap-1.5">
+          <label className="text-xs font-semibold text-slate-500">
+            Vendor Name <span className="text-red-500">*</span>
+          </label>
+          <input
+            type="text"
+            value={values.vendorName}
+            onChange={(e) => setField("vendorName", e.target.value)}
+            className="w-full px-3 py-2 border border-slate-200 rounded text-sm focus:outline-none focus:ring-1 focus:ring-blue-500"
+          />
+        </div>
+
+        <div className="flex flex-col gap-1.5">
+          <label className="text-xs font-semibold text-slate-500">Email</label>
+          <input
+            type="email"
+            value={values.vendorEmail}
+            onChange={(e) => setField("vendorEmail", e.target.value)}
+            className="w-full px-3 py-2 border border-slate-200 rounded text-sm focus:outline-none focus:ring-1 focus:ring-blue-500"
+          />
+        </div>
+
+        <div className="flex flex-col gap-1.5">
+          <label className="text-xs font-semibold text-slate-500">Phone</label>
+          <input
+            type="tel"
+            value={values.vendorPhone}
+            onChange={(e) => setField("vendorPhone", e.target.value)}
+            className="w-full px-3 py-2 border border-slate-200 rounded text-sm focus:outline-none focus:ring-1 focus:ring-blue-500"
+          />
+        </div>
+      </div>
+    </ModalCard>
+  );
+}

package/templates/panels/vendor-example/by-using-modal/vendor-types.ts

@@ -0,0 +1,29 @@
+export type Vendor = {
+  id: string;
+  name: string;
+  email: string;
+  phone: string;
+  status: "active" | "inactive";
+};
+
+export type VendorFormValues = {
+  vendorName: string;
+  vendorEmail: string;
+  vendorPhone: string;
+};
+
+export function getDefaultVendorFormValues(): VendorFormValues {
+  return {
+    vendorName: "",
+    vendorEmail: "",
+    vendorPhone: "",
+  };
+}
+
+export function vendorToFormValues(vendor: Vendor): VendorFormValues {
+  return {
+    vendorName: vendor.name,
+    vendorEmail: vendor.email,
+    vendorPhone: vendor.phone,
+  };
+}

package/templates/panels/vendor-example/by-using-sidepanel/VendorsPage.tsx

@@ -0,0 +1,47 @@
+import { useVendorFormPanel } from "./useVendorFormPanel";
+import type { Vendor } from "./vendor-types";
+
+export default function VendorsPage() {
+  const openVendorForm = useVendorFormPanel();
+
+  const handleCreate = () => {
+    openVendorForm("create"); // no data — empty form
+  };
+
+  const handleEdit = (vendor: Vendor) => {
+    openVendorForm("update", vendor); // passes row data into form
+  };
+
+  return (
+    <div className="p-6 max-w-xl mx-auto space-y-4">
+      <h1 className="text-xl font-bold text-slate-800">Vendors Directory (Demo)</h1>
+      <p className="text-sm text-slate-500">
+        This is a demo page showing how to trigger the side panel form using the domain hook.
+      </p>
+
+      <div className="flex gap-4">
+        <button
+          onClick={handleCreate}
+          className="px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded text-sm transition-colors"
+        >
+          Add Vendor
+        </button>
+
+        <button
+          onClick={() =>
+            handleEdit({
+              id: "V-001",
+              name: "Acme Supplies",
+              email: "acme@mail.com",
+              phone: "555-0100",
+              status: "active",
+            })
+          }
+          className="px-4 py-2 border border-slate-200 rounded text-sm hover:bg-slate-50 transition-colors"
+        >
+          Edit Acme Supplies
+        </button>
+      </div>
+    </div>
+  );
+}

package/templates/panels/vendor-example/by-using-sidepanel/useVendorFormPanel.tsx

@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import { useFormPanel } from "../../hooks/useFormPanel";
+import { VendorForm, type VendorFormMode } from "./vendor-form";
+import type { Vendor } from "./vendor-types";
+
+export function useVendorFormPanel() {
+  const openForm = useFormPanel();
+
+  return useCallback(
+    (mode: VendorFormMode = "create", vendor?: Vendor) => {
+      openForm(VendorForm, { mode, vendor });
+    },
+    [openForm],
+  );
+}

package/templates/panels/vendor-example/by-using-sidepanel/vendor-form.tsx

@@ -0,0 +1,108 @@
+import { useCallback, useState } from "react";
+import { SidePanelCard } from "../../components/side-panel/side-panel-card";
+import { useFormDirty } from "../../hooks/useFormDirty";
+import { requestOverlayCloseWithConfirm } from "../../core/overlay-close";
+import type { Vendor } from "./vendor-types";
+import {
+  getDefaultVendorFormValues,
+  vendorToFormValues,
+  type VendorFormValues,
+} from "./vendor-types";
+
+export type VendorFormMode = "create" | "update";
+
+export type VendorFormProps = {
+  close: () => void;
+  mode?: VendorFormMode;
+  vendor?: Vendor;
+};
+
+export function VendorForm({ close, mode = "create", vendor }: VendorFormProps) {
+  const isUpdate = mode === "update";
+
+  const [values, setValues] = useState<VendorFormValues>(() => ({
+    ...getDefaultVendorFormValues(),
+    ...(vendor ? vendorToFormValues(vendor) : {}),
+  }));
+
+  const setField = useCallback(
+    <K extends keyof VendorFormValues>(key: K, value: VendorFormValues[K]) => {
+      setValues((prev) => ({ ...prev, [key]: value }));
+    },
+    [],
+  );
+
+  const isDirty = useFormDirty(values);
+
+  const handleSave = () => {
+    if (!values.vendorName.trim()) {
+      alert("Vendor name is required");
+      return;
+    }
+
+    console.log("Saving vendor:", values);
+    close();
+  };
+
+  return (
+    <SidePanelCard
+      title={isUpdate ? "Edit Vendor" : "Add Vendor"}
+      close={close}
+      onSubmit={handleSave}
+      isDirty={isDirty}
+      size="md"
+      footer={
+        <div className="flex justify-end gap-3">
+          <button
+            type="button"
+            onClick={requestOverlayCloseWithConfirm}
+            className="px-4 py-2 border border-slate-200 rounded text-sm hover:bg-slate-50 transition-colors"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={handleSave}
+            className="px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded text-sm transition-colors"
+          >
+            Save
+          </button>
+        </div>
+      }
+    >
+      <div className="space-y-4 py-4">
+        <div className="flex flex-col gap-1.5">
+          <label className="text-xs font-semibold text-slate-500">
+            Vendor Name <span className="text-red-500">*</span>
+          </label>
+          <input
+            type="text"
+            value={values.vendorName}
+            onChange={(e) => setField("vendorName", e.target.value)}
+            className="w-full px-3 py-2 border border-slate-200 rounded text-sm focus:outline-none focus:ring-1 focus:ring-blue-500"
+          />
+        </div>
+
+        <div className="flex flex-col gap-1.5">
+          <label className="text-xs font-semibold text-slate-500">Email</label>
+          <input
+            type="email"
+            value={values.vendorEmail}
+            onChange={(e) => setField("vendorEmail", e.target.value)}
+            className="w-full px-3 py-2 border border-slate-200 rounded text-sm focus:outline-none focus:ring-1 focus:ring-blue-500"
+          />
+        </div>
+
+        <div className="flex flex-col gap-1.5">
+          <label className="text-xs font-semibold text-slate-500">Phone</label>
+          <input
+            type="tel"
+            value={values.vendorPhone}
+            onChange={(e) => setField("vendorPhone", e.target.value)}
+            className="w-full px-3 py-2 border border-slate-200 rounded text-sm focus:outline-none focus:ring-1 focus:ring-blue-500"
+          />
+        </div>
+      </div>
+    </SidePanelCard>
+  );
+}

package/templates/panels/vendor-example/by-using-sidepanel/vendor-types.ts

@@ -0,0 +1,29 @@
+export type Vendor = {
+  id: string;
+  name: string;
+  email: string;
+  phone: string;
+  status: "active" | "inactive";
+};
+
+export type VendorFormValues = {
+  vendorName: string;
+  vendorEmail: string;
+  vendorPhone: string;
+};
+
+export function getDefaultVendorFormValues(): VendorFormValues {
+  return {
+    vendorName: "",
+    vendorEmail: "",
+    vendorPhone: "",
+  };
+}
+
+export function vendorToFormValues(vendor: Vendor): VendorFormValues {
+  return {
+    vendorName: vendor.name,
+    vendorEmail: vendor.email,
+    vendorPhone: vendor.phone,
+  };
+}

package/templates/select-dropdown/README.md

@@ -0,0 +1,62 @@
+# Select Dropdown Components
+
+A set of highly accessible single and multi-select dropdown fields with built-in search filtering, custom option templates, keyboard support, and async loading spinners.
+
+---
+
+## 1. Single Select Dropdown (`SelectInput`)
+
+```tsx
+import { SelectInput } from "@/pejay-ui/components/select-dropdown";
+
+const options = [
+  { label: "Option 1", value: "1" },
+  { label: "Option 2", value: "2" }
+];
+
+<SelectInput
+  label="Select Project"
+  options={options}
+  value={value}
+  onChange={setValue}
+  searchable
+  placeholder="Choose a project..."
+/>
+```
+
+---
+
+## 2. Multi-Select Dropdown (`MultiSelectInput`)
+
+Supports selecting multiple items, rendering selected items as dismissible badges inside the input field.
+
+```tsx
+import { MultiSelectInput } from "@/pejay-ui/components/select-dropdown";
+
+<MultiSelectInput
+  label="Select Tags"
+  options={options}
+  value={values}
+  onChange={setValues}
+  searchable
+  maxSelected={5}
+/>
+```
+
+---
+
+## 3. Component API Props
+
+### Shared Dropdown Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `label` | `string` | — | Label text shown above the select field. |
+| `options` | `Array<{ label: string; value: string; disabled?: boolean }>` | — | The option items list. |
+| `placeholder` | `string` | `"Select..."` | Helper placeholder shown when empty. |
+| `searchable` | `boolean` | `false` | Enables filter search input inside the dropdown. |
+| `loading` | `boolean` | `false` | Shows a spinner overlay inside the list box. |
+| `disabled` | `boolean` | `false` | Disables toggle dropdown interactions. |
+| `error` | `string` | — | Highlights the input border in red with a text alert. |
+| `renderOption` | `(option: Option) => ReactNode` | — | Optional custom renderer callback to style list options. |
+| `renderValue` | `(selected: Option \| Option[]) => ReactNode` | — | Optional custom renderer callback to style selected values inside the header. |

package/templates/select-dropdown/multiselect-input.tsx

@@ -9,8 +9,8 @@ import {
   FloatingPortal,
 } from "@floating-ui/react";
 import { ChevronDown, Check, X, Search, Loader2 } from "lucide-react";
-import { cn } from "@/utils/cn";
-import { Tooltip } from "../button/tooltip";
+import { cn } from "@/pejay-ui/utils/cn";
+import { Tooltip } from "@/pejay-ui/components/overlays";
 import { type SelectOption } from "./select-input";
 
 function getNextSelectableIndex(

package/templates/select-dropdown/select-input.tsx

@@ -9,8 +9,8 @@ import {
   FloatingPortal,
 } from "@floating-ui/react";
 import { ChevronDown, Check, Search, X, Loader2 } from "lucide-react";
-import { cn } from "@/utils/cn";
-import { Tooltip } from "../button/tooltip";
+import { cn } from "@/pejay-ui/utils/cn";
+import { Tooltip } from "@/pejay-ui/components/overlays";
 
 export interface SelectOption {
   id: string;

package/templates/skeleton/README.md

@@ -0,0 +1,53 @@
+# Skeleton Shimmer Loader Component
+
+A fluid skeleton component with built-in shimmery transitions to represent load state structures.
+
+---
+
+## Installation
+
+```bash
+npx pejay-ui add skeleton
+```
+
+---
+
+## Usage
+
+```tsx
+import { Skeleton } from "@/pejay-ui/components/skeleton";
+
+// 1. Circle skeleton placeholder (e.g. Profile Avatar)
+<Skeleton variant="circle" width={48} height={48} />
+
+// 2. Text line skeleton (default width 75%)
+<Skeleton variant="text" />
+
+// 3. Rectangular block (e.g. Card Preview container)
+<Skeleton variant="rect" width="100%" height={200} />
+```
+
+---
+
+## Component API Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| **`variant`** | `"text" \| "circle" \| "rect"` | `"rect"` | Mapped preset shape. |
+| **`width`** | `string \| number` | — | Direct width style (e.g. `'100%'`, `'48px'`, or `48` for px value). |
+| **`height`** | `string \| number` | — | Direct height style (e.g. `'16px'`, or `16` for px value). |
+| **`className`** | `string` | — | Custom Tailwind class overrides. |
+
+---
+
+## Edge Cases & Best Practices
+
+1. **Accessibility (Screen Readers):**
+   * *Edge Case:* Screen readers will try to read empty skeleton elements or interpret their background animations as text contents.
+   * *Solution:* The Skeleton component includes `aria-hidden="true"` by default to ensure screen readers skip loading skeletons, maintaining screen reader accessibility clean.
+2. **Cumulative Layout Shift (CLS):**
+   * *Edge Case:* If the loaded content has different sizes or margins than the placeholder skeleton, elements on the screen will shift abruptly when loading finishes.
+   * *Solution:* Always match the `width` and `height` properties of your skeletons exactly to the sizes of the components they represent.
+3. **Responsive Fluid Widths:**
+   * *Edge Case:* Hardcoded pixel widths might overflow container boundaries on mobile devices.
+   * *Solution:* Pass responsive class names (e.g. `className="w-full md:w-48"`) instead of fixed `width` properties where layout widths need to adapt dynamically.

package/templates/skeleton/index.ts

@@ -0,0 +1,2 @@
+export * from "./skeleton";
+export * from "./types";

package/templates/skeleton/skeleton.css

@@ -0,0 +1,36 @@
+/* ─────────────────────────────────────────────────────────────
+   SKELETON SHIMMER KEYFRAMES
+   ───────────────────────────────────────────────────────────── */
+
+@keyframes skeleton-shimmer {
+  0% {
+    background-position: -200% 0;
+  }
+  100% {
+    background-position: 200% 0;
+  }
+}
+
+.skeleton-shimmer-bg {
+  background: linear-gradient(
+    90deg,
+    rgba(0, 0, 0, 0.05) 25%,
+    rgba(0, 0, 0, 0.10) 37%,
+    rgba(0, 0, 0, 0.05) 63%
+  );
+  background-size: 200% 100%;
+  animation: skeleton-shimmer 1.5s infinite linear;
+}
+
+/* Dark mode override */
+.dark .skeleton-shimmer-bg,
+@media (prefers-color-scheme: dark) {
+  .skeleton-shimmer-bg {
+    background: linear-gradient(
+      90deg,
+      rgba(255, 255, 255, 0.05) 25%,
+      rgba(255, 255, 255, 0.10) 37%,
+      rgba(255, 255, 255, 0.05) 63%
+    );
+  }
+}

package/templates/skeleton/skeleton.tsx

@@ -0,0 +1,40 @@
+// @ts-ignore
+import "./skeleton.css";
+import type { SkeletonProps } from "./types";
+import { cn } from "@/pejay-ui/utils/cn";
+
+export function Skeleton({
+  variant = "rect",
+  width,
+  height,
+  className,
+  style,
+  ...props
+}: SkeletonProps) {
+  // Shape configurations based on variant
+  const variantClass =
+    variant === "circle"
+      ? "rounded-full shrink-0"
+      : variant === "text"
+      ? "rounded h-[10px] w-3/4"
+      : "rounded-xl";
+
+  const resolvedStyle = {
+    width: typeof width === "number" ? `${width}px` : width,
+    height: typeof height === "number" ? `${height}px` : height,
+    ...style,
+  };
+
+  return (
+    <div
+      aria-hidden="true"
+      className={cn(
+        "skeleton-shimmer-bg select-none pointer-events-none border border-zinc-900/10",
+        variantClass,
+        className
+      )}
+      style={resolvedStyle}
+      {...props}
+    />
+  );
+}

package/templates/skeleton/types.ts

@@ -0,0 +1,12 @@
+import React from "react";
+
+export type SkeletonVariant = "text" | "circle" | "rect";
+
+export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Visual preset shape. Default: "rect" */
+  variant?: SkeletonVariant;
+  /** Direct width string (e.g. '100%', '48px', or 48) */
+  width?: string | number;
+  /** Direct height string (e.g. '16px', or 16) */
+  height?: string | number;
+}

package/templates/spinner/README.md

@@ -0,0 +1,51 @@
+# Spinner Loading Component
+
+A versatile suite of 9 distinct SVG and HTML loader animation styles with size scaling presets.
+
+---
+
+## Installation
+
+```bash
+npx pejay-ui add spinner
+```
+
+---
+
+## Usage
+
+All variants dynamically inherit their color from their text color context using `currentColor` classes (so placing `<Spinner />` inside a primary button will automatically color it white/blue).
+
+```tsx
+import { Spinner } from "@/pejay-ui/components/spinner";
+
+// Classic loading ring (Default)
+<Spinner variant="ring" size="md" />
+
+// Three pulsing dots
+<Spinner variant="dots" size="sm" />
+
+// Dual circular ripple wave
+<Spinner variant="ripple" size="lg" className="text-violet-600" />
+```
+
+---
+
+## Component API Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| **`variant`** | `"ring" \| "dots" \| "pulse" \| "bars" \| "orbit" \| "ripple" \| "dots-ring" \| "dots-step" \| "text-dots"` | `"ring"` | The layout structure and animation keyframe preset style. |
+| **`size`** | `"sm" \| "md" \| "lg"` | `"md"` | Standard scaling presets: `sm` (16px), `md` (24px), `lg` (36px). |
+| **`className`** | `string` | — | Additional CSS classes for color inheritance or custom styling. |
+
+---
+
+## Edge Cases & Best Practices
+
+1. **Color Visibility:**
+   * *Edge Case:* Spinners inherit their color via `currentColor`. If placed inside an element with no text color defined on a dark or colored backdrop, the spinner may become invisible.
+   * *Solution:* Explicitly apply a text color class to the spinner or its parent container (e.g. `text-white` or `className="text-sky-500"`).
+2. **Layout Sizing & Shift:**
+   * *Edge Case:* Swapping layout text directly with a spinner can trigger layout changes if sizes are not fixed.
+   * *Solution:* Align spinners inside fixed-height flex containers (like the `h-9 inline-flex` button) to guarantee smooth, jitter-free loading transitions.

package/templates/spinner/index.ts

@@ -0,0 +1 @@
+export * from "./spinner";