nexstruct 1.0.0

package/AGENTS.md

@@ -0,0 +1,122 @@
+# nexstruct — AGENTS.md
+
+CLI tool that scaffolds production-ready Next.js 15 + TypeScript frontend projects from composable templates.
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `npx nexstruct` | Run the interactive scaffolder (no install needed) |
+
+The CLI requires a TTY (interactive prompts via `@inquirer/prompts`).
+
+**No test, lint, or typecheck commands exist for this repo itself** — it has zero devDependencies. Only generated projects get those scripts.
+
+## Architecture
+
+- **Entry:** `scaffold/index.js` (ESM; `"type": "module"` in package.json)
+- **Prompts:** `scaffold/prompts.js` — asks about project name, UI libs, state mgmt, API layer, auth, forms, examples flag
+- **Generator:** `scaffold/generator.js` — copies template dirs into output, generates `package.json`/`tsconfig.json`/`Providers`/`README.md`
+- **Templates:** `templates/{nextjs-base,ui,state,api,auth,forms,shared}/` — each subdir under a category is a self-contained `fs.copy` overlay onto the base project
+
+## Key conventions
+
+- **Naming convention in templates:** `[name].[category].[ext]` — e.g. `button.component.tsx`, `counter.store.ts`, `auth.service.ts`, `users.api.ts`, `use-toggle.hook.ts`, `common.type.ts`, `utils.util.ts`. Always preserve this when adding template files.
+- **Template overlay order matters.** Later copies can overwrite earlier ones: nextjs-base → ui → state → api → auth → forms → shared.
+- **`includeExamples` removal** runs *after* all copies. If false, `src/app/page.tsx` and `src/app/examples/` are deleted.
+- **`Providers` composition** is code-generated based on the answer selections (nested provider components in `src/providers/index.tsx`), then injected into `src/app/layout.tsx`.
+- **Generated project default scripts:** `dev` (next dev), `build` (next build), `start` (next start), `lint` (next lint), `typecheck` (tsc --noEmit).
+- **No CI, no git hooks, no linter config for this repo.** Only the generated projects get eslint-config-next.
+
+## shadcn template — custom component system
+
+When the user selects `shadcn/ui`, the generated project includes a reusable component system in `src/components/`:
+
+### UI Primitives (`ui/`)
+button, badge, card, dialog, input, label, select, form, switch, checkbox, radio-group, textarea, table, tooltip, popover, scroll-area, avatar, sheet, dropdown-menu, tabs, progress, separator, input-otp.
+
+### `CustomField` (`common/fields/`)
+Compound object with **26+ field types**:
+
+| Field | Mode | Features |
+|-------|------|----------|
+| `CustomField.Text` | dual | left/right icons, array splitting |
+| `CustomField.TextArea` | dual | configurable rows |
+| `CustomField.Number` | dual | integer/float mode, scroll prevention, key filtering, min=0 |
+| `CustomField.StringNumber` | dual | numeric string input |
+| `CustomField.Password` | dual | show/hide toggle, **strength validation rules** when `mode="validate"` |
+| `CustomField.PhoneNumber` | dual | **react-phone-input-2** (country dropdown, flag, search), maskable view mode |
+| `CustomField.OTP` | dual | one-time password input |
+| `CustomField.SingleSelectField` | dual | shadcn Select with loading/empty states |
+| `CustomField.SelectField` | form-only | multi-select, search, avatars, tags, "show more" |
+| `CustomField.SwitchField` | dual | with description, border mode |
+| `CustomField.RadioField` | form-only | radio group |
+| `CustomField.CheckField` | form-only | single checkbox with label |
+| `CustomField.MultiCheckField` | form-only | multi-checkbox group |
+| `CustomField.SingleCheckField` | form-only | standalone checkbox |
+| `CustomField.SearchField` | dual | search with callback |
+| `CustomField.DatePickerField` | dual | date picker |
+| `CustomField.RangeDatePicker` | form-only | date range picker |
+| `CustomField.LimitField` | standalone | pagination limit selector with **URL sync** |
+| `CustomField.TextAreaWithFile` | form-only | textarea + file attachments |
+| `CustomField.UploadProfilePicture` | dual | avatar upload with preview, **FileReader data URL (no raw File in form state)** |
+| `CustomField.UploadVideoFile` | dual | video upload with preview |
+| `CustomField.DynamicFileUploadField` | form-only | drag-and-drop file upload, supports optional `onUpload` callback |
+| `CustomField.RichTextEditor` | form-only | rich text editing |
+| `CustomField.TinyEditor` | form-only | lightweight editor |
+
+### Common Components
+| Component | Description |
+|-----------|-------------|
+| `ActionButton` | Button with icon positions, loading spinner (`isPending`), and optional Tooltip |
+| `DialogWrapper` | Scrollable dialog with sticky header, close button, optional trigger, and footer slot |
+| `DynamicTable` | Config-driven table with loading/empty states, checkbox selection, expandable rows |
+| `Pagination` | Page navigation with ellipsis for large page counts |
+
+### Toast Notification System (`common/toast/`)
+| Function | Description |
+|----------|-------------|
+| `ToastMessageShow(type, message, options)` | Unified toast API — success, error, loading, custom |
+| `toastSuccessMessage(msg)` | Shortcut for success toasts |
+| `toastErrorMessage(msg)` | Shortcut for error toasts with API error extraction |
+| `toastLoadingMessage(msg)` | Shortcut for loading toasts |
+| `toastCustomMessage(msg)` | Shortcut for custom toasts |
+| `ToastMessageChange(msg)` | Transform known error messages into human-friendly text |
+
+The `ToastProvider` is auto-injected into the generated `Providers` composition.
+
+### Shared Utilities (`src/lib/utils.util.ts`)
+| Function | Description |
+|----------|-------------|
+| `cn()` | Merge Tailwind classes with clsx + tailwind-merge |
+| `LabelAndPlaceholderTextFormat()` | Auto-format labels to title case (preposition-aware) |
+| `formatDate()` | "June 17, 2026" |
+| `formatRelativeTime()` | "just now", "3m ago", "2h ago", "5d ago" |
+| `toMonthYear()` | "Jun 2025" |
+| `time12h()` | "2:30 PM" (with relative mode for today/yesterday) |
+| `time24h()` | "14:30" |
+| `customFormatDate()` | "YYYY-MM-DD" / "DD-MM-YYYY" / "YYYY" |
+| `fullDateTime()` | "24 August 2025, 03:30 PM" |
+| `duration()` | "2y 3m" between two dates |
+| `localDateTime()` | "20-10-2025 at 10:07 am" |
+| `localDateToISO()` | UTC midnight ISO string |
+| `truncate()` | String truncation with ellipsis |
+| `slugify()` | URL-safe slug generation |
+| `maskString()` | "Hel***ld" — show first N / last N chars |
+| `maskEmail()` | "j***@example.com" |
+| `passwordRules` | 5 rules array (length, uppercase, number, special, no sequential) |
+| `isPasswordStrong()` | Check all rules pass |
+
+### Field Patterns
+- **Dual-mode**: every `CustomField.*` component checks `if (form)` — with form it wraps in shadcn `<FormField>` for validation/errors, without it renders standalone.
+- **View-only mode**: `viewOnly` prop renders a styled read-only div instead of the input.
+- **No raw File objects in form state**: File upload components use `FileReader.readAsDataURL()` or `URL.createObjectURL()` to store string URLs. Keep actual `File` references in local state or refs for submission.
+
+### Providers Stack
+Auto-generated `src/providers/index.tsx` wraps the app with selected providers in order:
+1. `ToastProvider` — react-hot-toast with themed `<Toaster />`
+2. `ThemeProvider` — next-themes (if dark mode enabled)
+3. `MuiProvider` / `AntdProvider` — UI framework theme (if selected)
+4. `ReduxProvider` / Zustand store — state management (if selected)
+5. `TrpcProvider` — tRPC (if selected)
+6. `NextAuthProvider` / `ClerkAuthProvider` — auth (if selected)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naimur Rahman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+<div align="center">
+  <br />
+  <h1>⚒️ Nexstruct</h1>
+  <p><strong>Scaffold production-ready Next.js 15 + TypeScript projects — instantly.</strong></p>
+  <p>Choose your UI library, state management, API layer, auth, and forms — all from one interactive CLI prompt.</p>
+  <br />
+
+  <p>
+    <a href="#-quick-start">Quick Start</a> •
+    <a href="#-features">Features</a> •
+    <a href="#-usage">Usage</a> •
+    <a href="#-templates">Templates</a>
+  </p>
+  <br />
+</div>
+
+## ⚡ Quick Start
+
+```bash
+# No install needed — just run:
+npx nexstruct
+```
+
+Follow the interactive prompts to select your stack, and your project will be scaffolded in seconds.
+
+## ✨ Features
+
+- **3 UI Libraries** — shadcn/ui (Tailwind), Material UI, Ant Design — each with 15–24 custom field types
+- **3 State Management** — Redux Toolkit, Zustand, React Context
+- **3 API Layers** — Fetch, Axios, tRPC
+- **2 Auth Providers** — NextAuth.js, Clerk
+- **Form Handling** — react-hook-form with Zod validation
+- **CustomField System** — Dual-mode fields that work with or without react-hook-form
+- **Common Components** — ActionButton, DialogWrapper, DynamicTable, Pagination
+- **TypeScript Strict** — Fully typed, production-ready code
+
+## 🚀 Usage
+
+```bash
+# Scaffold a new project
+npx nexstruct
+
+# Or install globally
+npm install -g nexstruct
+nexstruct
+```
+
+The CLI will ask you about:
+
+| Prompt | Options |
+|--------|---------|
+| UI Library | shadcn/ui, Material UI, Ant Design |
+| State Management | Redux Toolkit, Zustand, React Context |
+| API Layer | Fetch, Axios, tRPC |
+| Auth | NextAuth.js, Clerk |
+| Forms | react-hook-form + Zod |
+| Include Examples | Yes / No |
+
+## 📦 What You Get
+
+A fully configured Next.js 15 project with:
+
+```
+my-app/
+├── src/
+│   ├── app/          # App Router pages & layouts
+│   ├── components/   # UI primitives + common components
+│   │   ├── ui/       # Base primitives (button, card, dialog, etc.)
+│   │   ├── common/   # ActionButton, DialogWrapper, DynamicTable, Pagination
+│   │   └── fields/   # CustomField.* (24 types for shadcn, 14 for MUI, 17 for antd)
+│   ├── providers/    # Composable provider wrappers
+│   ├── lib/          # Utilities, types, API clients
+│   └── store/        # State management (if selected)
+├── public/
+├── next.config.ts
+├── tsconfig.json
+└── package.json
+```
+
+## 🧩 Template Architecture
+
+Templates are composable overlays applied in order:
+
+```
+nextjs-base → ui → state → api → auth → forms → shared
+```
+
+Each layer adds its own files and configurations. Later layers can override earlier ones.
+
+## 🛠️ Development
+
+This repo itself is a Next.js 15 app that serves as a component lab and documentation site:
+
+```bash
+git clone https://github.com/naimur61/Nexstruct.git
+cd Nexstruct
+npm install
+npm run dev
+```
+
+## 📄 License
+
+MIT © Naimur Rahman

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "nexstruct",
+  "version": "1.0.0",
+  "description": "Scaffold production-ready Next.js 15 + TypeScript projects with your choice of UI library, state management, API layer, auth, and forms — all from one interactive CLI.",
+  "type": "module",
+  "bin": {
+    "nexstruct": "./scaffold/index.js"
+  },
+  "files": [
+    "scaffold/",
+    "templates/",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.1.0",
+    "react-phone-input-2": "^2.15.1"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.0.0",
+    "@hookform/resolvers": "^3.0.0",
+    "@radix-ui/react-avatar": "^1.0.0",
+    "@radix-ui/react-checkbox": "^1.0.0",
+    "@radix-ui/react-dialog": "^1.0.0",
+    "@radix-ui/react-dropdown-menu": "^2.0.0",
+    "@radix-ui/react-label": "^2.0.0",
+    "@radix-ui/react-popover": "^1.0.0",
+    "@radix-ui/react-progress": "^1.0.0",
+    "@radix-ui/react-radio-group": "^1.0.0",
+    "@radix-ui/react-scroll-area": "^1.0.0",
+    "@radix-ui/react-select": "^2.0.0",
+    "@radix-ui/react-separator": "^1.0.0",
+    "@radix-ui/react-slot": "^1.0.0",
+    "@radix-ui/react-switch": "^1.0.0",
+    "@radix-ui/react-tabs": "^1.0.0",
+    "@radix-ui/react-toast": "^1.0.0",
+    "@radix-ui/react-tooltip": "^1.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "autoprefixer": "^10.0.0",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-next": "^15.0.0",
+    "fuse.js": "^7.4.2",
+    "input-otp": "^1.0.0",
+    "lucide-react": "^0.400.0",
+    "next": "^15.0.0",
+    "next-themes": "^0.4.6",
+    "postcss": "^8.0.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "react-hook-form": "^7.0.0",
+    "tailwind-merge": "^2.0.0",
+    "tailwindcss": "^3.4.0",
+    "tailwindcss-animate": "^1.0.0",
+    "typescript": "^5.4.0",
+    "zod": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naimur61/Nexstruct.git"
+  },
+  "homepage": "https://github.com/naimur61/Nexstruct#readme",
+  "bugs": {
+    "url": "https://github.com/naimur61/Nexstruct/issues"
+  },
+  "keywords": [
+    "nextjs",
+    "nextjs-15",
+    "scaffold",
+    "cli",
+    "typescript",
+    "react",
+    "shadcn",
+    "mui",
+    "ant-design",
+    "frontend",
+    "template",
+    "boilerplate"
+  ],
+  "license": "MIT",
+  "author": "Naimur Rahman",
+  "engines": {
+    "node": ">=18"
+  }
+}