shortcut-next 1.0.0 → 1.2.0

package/README.md

@@ -1,26 +1,236 @@
-# Shortcut Next ⚡
+# Shortcut Next
 
-> Scaffold modern **Next.js 15+ projects** in seconds — with **MUI**, **React Hook Form**, and **TanStack Query** built-in.  
-> Optionally add **Tailwind CSS v4** with a single command.
+Stop starting from scratch. Scaffold a production-ready **Next.js 15+** project with **MUI**, **React Hook Form**, **TanStack Query**, role-based authorization, i18n, and dark mode — all wired up and ready to go.
 
 ---
 
-## 🚀 Features
+## What You Get
 
-- **Next.js 15 (App Router)** — modern project structure, ready to go.
-- **MUI (Material UI)** — theming, components, dark mode ready.
-- **React Hook Form** — forms made simple, integrated with MUI inputs.
-- **TanStack Query (React Query)** — powerful data fetching and caching.
-- **Tailwind CSS v4** (optional) — utility-first styling, zero config.
-- **TypeScript by default** — strict mode enabled.
-- **One CLI** — choose your preset: **Base** (MUI stack) or **Tailwind v4**.
+- **Next.js 15** with App Router and TypeScript (strict mode)
+- **MUI v7** — fully themed with 30+ customized components, dark mode, and RTL support
+- **React Hook Form** + Yup validation
+- **TanStack Query** for data fetching and caching
+- **CASL authorization** — role-based access control out of the box
+- **i18n** — English and Arabic with auto-detection
+- **Tailwind CSS v4** (optional preset)
+- **MSW** — mock API responses during development
 
 ---
 
-## 📦 Installation
+## Installation
 
-You don’t need to install globally. Use `npx`:
+Run this single command and follow the prompts:
 
 ```bash
 npx shortcut-next@latest
+```
 
+You'll be asked three things:
+
+1. **Project name** — the folder that will be created
+2. **Preset** — `base` (MUI stack) or `tailwind` (MUI + Tailwind v4)
+3. **Package manager** — pnpm, npm, yarn, or bun
+
+That's it. The CLI creates your project, initializes git, and installs dependencies.
+
+### Skip the Prompts (Optional)
+
+```bash
+npx shortcut-next@latest my-app --preset tailwind --pm pnpm
+```
+
+| Flag            | Options                        |
+| --------------- | ------------------------------ |
+| `--preset`      | `base` or `tailwind`           |
+| `--pm`          | `npm`, `pnpm`, `yarn`, `bun`   |
+| `--no-git`      | Skip git initialization        |
+| `--no-install`  | Skip dependency installation   |
+
+### Start Developing
+
+```bash
+cd my-app
+npm run dev
+```
+
+Other available scripts:
+
+```bash
+npm run build      # Production build
+npm run lint       # ESLint
+npm run typecheck  # TypeScript validation
+npm run format     # Prettier
+```
+
+---
+
+## Project Structure
+
+```text
+app/
+├── layout.tsx              # Root layout (fonts, providers)
+├── page.tsx                # Landing page (public)
+├── login/page.tsx          # Login / Signup page
+├── home/page.tsx           # Authenticated home page
+├── unauthorized/page.tsx   # Access denied page
+└── (dashboard)/
+    └── dashboard/page.tsx  # Dashboard with role-aware cards
+
+core/
+├── clients/apiClient.ts    # Axios instance (token refresh, auto-logout)
+├── context/AuthContext.tsx  # Auth state (login, signup, logout)
+├── context/SettingsContext.tsx  # Theme mode, direction, language
+├── theme/                  # MUI theme system (see below)
+├── configs/                # Auth endpoints, i18n, theme defaults
+└── hooks/                  # useAbility, useCan, useLanguage
+
+lib/abilities/              # CASL authorization (see below)
+providers/AppProviders.tsx   # Composes all context providers
+proxy.ts                    # Middleware (auth + route protection)
+```
+
+---
+
+## Authorization
+
+The template includes a ready-to-use role-based access system powered by [CASL](https://casl.js.org/).
+
+### Roles
+
+| Role      | What they can do                                         |
+| --------- | -------------------------------------------------------- |
+| `admin`   | Full access to everything                                |
+| `manager` | Read all, manage Users/Tickets/Reports, no Settings      |
+| `agent`   | Read Dashboard/Tickets/Reports, manage Tickets           |
+| `viewer`  | Read Dashboard and Reports only                          |
+
+Your backend JWT must include a `role` claim. The token is read from an `accessToken` cookie.
+
+### Protect a New Route
+
+Add one entry to `lib/abilities/routeMap.ts`:
+
+```ts
+export const routePermissions: RoutePermission[] = [
+  // ... existing routes
+
+  // Exact route
+  { pattern: '/dashboard/reports', action: 'read', subject: 'Reports' },
+
+  // Dynamic param
+  { pattern: '/dashboard/users/[id]', action: 'manage', subject: 'Users' },
+
+  // Wildcard (all sub-routes)
+  { pattern: '/settings/*', action: 'manage', subject: 'Settings' },
+]
+```
+
+That's it — the middleware handles enforcement automatically.
+
+### Check Permissions in Components
+
+```tsx
+import { useAbility, useCan } from '@/core/hooks/useAbility'
+
+// Option 1: Full ability object
+const ability = useAbility()
+if (ability.can('read', 'Users')) {
+  // show users link
+}
+
+// Option 2: Simple boolean
+const canManageSettings = useCan('manage', 'Settings')
+```
+
+### Add a New Role
+
+Edit `lib/abilities/roles.ts`:
+
+```ts
+export const roleAbilities: Record<UserRole, (can: Can, cannot: Cannot) => void> = {
+  // ... existing roles
+
+  support: (can) => {
+    can('read', ['Dashboard', 'Tickets'])
+    can('manage', 'Tickets')
+  },
+}
+```
+
+Then add `'support'` to the `UserRole` type in `lib/abilities/types.ts`.
+
+---
+
+## MUI Theme Customization
+
+The theme lives in `core/theme/` and is fully modular.
+
+### Change the Default Theme
+
+Edit `core/configs/themeConfig.ts`:
+
+```ts
+const themeConfig = {
+  mode: 'dark',           // 'light' or 'dark'
+  direction: 'ltr',       // 'ltr' or 'rtl'
+  responsiveFontSizes: true,
+  disableRipple: true,
+  borderRadius: 10,
+}
+```
+
+### Customize a Component
+
+Each MUI component has its own override file in `core/theme/overrides/`. For example, to change button styles, edit `core/theme/overrides/button.ts`:
+
+```ts
+const Button = (settings: Settings) => ({
+  MuiButton: {
+    styleOverrides: {
+      root: ({ theme }) => ({
+        borderRadius: 8,
+        textTransform: 'none',
+        fontWeight: 600,
+      }),
+      contained: ({ theme }) => ({
+        boxShadow: theme.shadows[3],
+      }),
+    },
+  },
+})
+```
+
+### Components with Overrides
+
+Accordion, Alerts, Autocomplete, Avatars, Backdrop, Breadcrumbs, Button, ButtonGroup, Card, Chip, DataGrid, Dialog, Divider, FAB, IconButton, Input, Link, List, Menu, Pagination, Paper, Popover, Progress, Rating, Select, Snackbar, Switches, Table, Tabs, TextField, Timeline, ToggleButton, Tooltip, Typography.
+
+### Change the Color Palette
+
+Edit `core/theme/palette/index.ts`:
+
+```ts
+primary: {
+  light: '#8B9BFF',
+  main: '#5B74FF',   // your brand color
+  dark: '#3B54DF',
+},
+secondary: {
+  main: '#00D0FF',
+},
+```
+
+---
+
+## Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+NEXT_PUBLIC_URL=https://your-backend-url.com
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shortcut-next",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Scaffold Next.js apps with MUI base or Tailwind v4 preset.",
   "main": "index.js",
   "bin": {

package/templates/base/.eslintrc.json

@@ -1,3 +1,76 @@
 {
-    "extends": ["next", "prettier"]
-  }
+  "extends": [
+    "next/core-web-vitals",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "rules": {
+    "react/display-name": "off",
+    "@next/next/no-img-element": "off",
+    "react/no-unescaped-entities": "off",
+    "import/no-anonymous-default-export": "off",
+    "@typescript-eslint/no-unused-vars": "error",
+    "@typescript-eslint/ban-ts-comment": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-non-null-assertion": "off",
+    // add new line above comment
+    "lines-around-comment": [
+      "error",
+      {
+        "beforeLineComment": true,
+        "beforeBlockComment": true,
+        "allowBlockStart": true,
+        "allowClassStart": true,
+        "allowObjectStart": true,
+        "allowArrayStart": true
+      }
+    ],
+    // add new line above return
+    "newline-before-return": "error",
+    // add new line below import
+    "import/newline-after-import": [
+      "error",
+      {
+        "count": 1
+      }
+    ],
+    "@typescript-eslint/ban-types": [
+      "error",
+      {
+        "extendDefaults": true,
+        "types": {
+          "{}": false
+        }
+      }
+    ]
+  },
+  "plugins": [
+    "import"
+  ],
+  "settings": {
+    "import/parsers": {
+      "@typescript-eslint/parser": [
+        ".ts",
+        ".tsx"
+      ]
+    },
+    "import/resolver": {
+      "typescript": {
+        "alwaysTryTypes": true,
+        "project": [
+          "./tsconfig.json"
+        ]
+      }
+    }
+  },
+  "overrides": [
+    {
+      "files": [
+        "src/iconify-bundle/*"
+      ],
+      "rules": {
+        "@typescript-eslint/no-var-requires": "off"
+      }
+    }
+  ]
+}

package/templates/base/.prettierignore

@@ -0,0 +1,8 @@
+node_modules
+.next
+out
+build
+dist
+coverage
+*.lock
+package-lock.json

package/templates/base/app/(dashboard)/layout.tsx

@@ -1,97 +1,23 @@
-import { cookies } from 'next/headers'
-import { redirect } from 'next/navigation'
-import { decodeJwt } from 'jose'
-import type { UserRole } from '@/lib/abilities'
-
-/**
- * JWT payload structure
- */
-interface JWTPayload {
-  sub: string
-  email?: string
-  role?: string
-  name?: string
-  exp?: number
-}
-
-/**
- * Session data extracted from JWT
- */
-interface Session {
-  userId: string
-  role: UserRole
-  name?: string
-  email?: string
-}
-
-/**
- * Extract session from cookies (server-side)
- *
- * This is the defense-in-depth check that runs in addition to middleware.
- * It ensures no protected content is ever rendered without a valid session.
- */
-async function getServerSession(): Promise<Session | null> {
-  const cookieStore = await cookies()
-  const token = cookieStore.get('accessToken')?.value
-
-  if (!token) {
-    return null
-  }
+import SidebarLayout from '@/core/layouts/SidebarLayout'
+import navigation from '@/navigation/sidebarRoutes'
+import { fetchDynamicRoutes } from '@/navigation/dynamicRoutes'
+import themeConfig from '@/core/configs/themeConfig'
 
+export default async function DashboardLayout({ children }: { children: React.ReactNode }) {
+  let dynamicNavItems: Awaited<ReturnType<typeof fetchDynamicRoutes>> = []
   try {
-    const payload = decodeJwt(token) as JWTPayload
-
-    // Check expiration
-    if (payload.exp && payload.exp * 1000 < Date.now()) {
-      return null
-    }
-
-    const validRoles: UserRole[] = ['admin', 'manager', 'agent', 'viewer']
-    const role = validRoles.includes(payload.role as UserRole)
-      ? (payload.role as UserRole)
-      : 'viewer'
-
-    return {
-      userId: payload.sub,
-      role,
-      name: payload.name,
-      email: payload.email,
-    }
-  } catch {
-    return null
-  }
-}
-
-/**
- * Dashboard Layout
- *
- * This is a Server Component that provides defense-in-depth for all dashboard routes.
- * Even if middleware is bypassed, this layout ensures no protected content renders
- * without a valid session.
- *
- * The layout wraps all routes in the (dashboard) route group.
- */
-export default async function DashboardLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  const session = await getServerSession()
-
-  // Defense-in-depth: redirect if no session
-  // This should rarely trigger since middleware handles it first
-  if (!session) {
-    redirect('/login?returnUrl=/dashboard')
+    dynamicNavItems = await fetchDynamicRoutes()
+  } catch (error) {
+    console.error('Failed to fetch dynamic nav routes:', error)
   }
 
   return (
-    <div className="dashboard-layout">
-      {/*
-        Add dashboard navigation/sidebar here
-        Navigation items can be filtered based on session.role
-        using the useAbility hook in client components
-      */}
-      <main className="dashboard-content">{children}</main>
+    <div className='dashboard-layout'>
+      <main className='dashboard-content'>
+        <SidebarLayout navItems={navigation()} dynamicNavItems={dynamicNavItems} appName={themeConfig.templateName}>
+          {children}
+        </SidebarLayout>
+      </main>
     </div>
   )
 }

package/templates/base/app/home/page.tsx

@@ -2,8 +2,8 @@
 
 import { Container, Typography, Paper, Box, Chip, Button } from '@mui/material'
 import { LogOut } from 'lucide-react'
-import { useAuth } from '@/@core/context/AuthContext'
-import { useCan } from '@/@core/hooks/useAbility'
+import { useAuth } from '@/core/context/AuthContext'
+import { useCan } from '@/core/hooks/useAbility'
 
 // Role-specific home components
 function AdminHome() {

package/templates/base/app/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">
+  <path fill-rule="evenodd" clip-rule="evenodd" fill="#5B74FF" d="M 530.5,258.5 C 531.5,258.5 532.5,258.5 533.5,258.5C 553.598,259.825 573.598,259.825 593.5,258.5C 596.5,258.5 599.5,258.5 602.5,258.5C 605.273,259.657 608.273,260.324 611.5,260.5C 616.302,262.127 620.468,264.794 624,268.5C 630.942,279.405 638.109,290.071 645.5,300.5C 655.003,316.844 665.003,332.844 675.5,348.5C 675.427,350.027 676.094,351.027 677.5,351.5C 683.754,363.016 690.754,374.016 698.5,384.5C 703.155,392.472 707.822,400.472 712.5,408.5C 712.427,410.027 713.094,411.027 714.5,411.5C 719.474,419.087 717.807,424.921 709.5,429C 662.833,429.667 616.167,429.667 569.5,429C 567.975,427.991 566.308,427.491 564.5,427.5C 560.603,425.114 557.103,422.114 554,418.5C 549.364,410.056 544.198,402.056 538.5,394.5C 537,390.827 535,387.494 532.5,384.5C 530.281,379.291 527.281,374.624 523.5,370.5C 515.491,356.377 507.158,343.043 498.5,330.5C 496.316,326.119 493.65,322.119 490.5,318.5C 490.011,317.005 489.345,315.671 488.5,314.5C 487.649,312.118 486.316,310.118 484.5,308.5C 484.672,307.508 484.338,306.842 483.5,306.5C 483.5,305.833 483.167,305.5 482.5,305.5C 476.33,297.555 468.33,295.055 458.5,298C 456.273,298.941 454.273,300.108 452.5,301.5C 451.833,301.5 451.5,301.833 451.5,302.5C 445.554,308.427 444.054,315.427 447,323.5C 459.358,344.235 472.191,364.569 485.5,384.5C 498.336,406.178 511.669,427.511 525.5,448.5C 527.194,455.947 524.527,461.113 517.5,464C 468.167,464.667 418.833,464.667 369.5,464C 363.047,462.611 357.713,459.444 353.5,454.5C 343.82,439.797 334.153,425.13 324.5,410.5C 323.66,408.147 322.326,406.147 320.5,404.5C 315.997,396.156 310.997,388.156 305.5,380.5C 305.5,379.5 305.5,378.5 305.5,377.5C 305.5,374.167 305.5,370.833 305.5,367.5C 307.269,362.052 310.603,357.719 315.5,354.5C 319.566,351.437 322.899,347.771 325.5,343.5C 326.5,342.167 327.5,340.833 328.5,339.5C 331.5,337.167 334.167,334.5 336.5,331.5C 339.5,329.167 342.167,326.5 344.5,323.5C 356.112,311.553 367.778,299.553 379.5,287.5C 382.5,286.5 384.5,284.5 385.5,281.5C 389.167,277.5 392.833,273.5 396.5,269.5C 400.516,265.492 405.182,262.492 410.5,260.5C 450.805,259.802 490.805,259.135 530.5,258.5 Z"/>
+  <path fill-rule="evenodd" clip-rule="evenodd" fill="#5B74FF" d="M 657.5,475.5 C 664.789,477.595 670.956,481.595 676,487.5C 692,511.5 708,535.5 724,559.5C 725.874,563.52 725.874,567.52 724,571.5C 721.283,574.71 718.783,578.044 716.5,581.5C 691.195,608.474 665.861,635.474 640.5,662.5C 634.73,668.771 628.73,674.938 622.5,681C 618.547,683.81 614.213,685.81 609.5,687C 546.833,687.667 484.167,687.667 421.5,687C 419.277,686.434 417.277,685.6 415.5,684.5C 415.027,683.094 414.027,682.427 412.5,682.5C 411.833,682.5 411.167,682.5 410.5,682.5C 405.379,677.722 401.046,672.388 397.5,666.5C 396.331,663.489 394.664,660.822 392.5,658.5C 386.069,647.96 379.402,637.627 372.5,627.5C 371.241,623.975 369.241,620.975 366.5,618.5C 355.912,600.316 344.579,582.649 332.5,565.5C 332.068,564.29 331.401,563.29 330.5,562.5C 327.996,557.485 324.996,552.819 321.5,548.5C 321.672,547.508 321.338,546.842 320.5,546.5C 319.525,544.205 318.192,542.205 316.5,540.5C 313.555,534.896 310.221,529.562 306.5,524.5C 304.65,520.355 304.15,516.021 305,511.5C 306.728,508.047 309.562,506.214 313.5,506C 361.156,506.344 408.49,506.344 455.5,506C 465.15,507.51 472.483,512.343 477.5,520.5C 490.587,541.677 503.92,562.677 517.5,583.5C 522.42,593.014 528.086,602.014 534.5,610.5C 539.119,620.228 545.119,629.061 552.5,637C 559.208,640.671 566.208,641.338 573.5,639C 576.106,638.238 578.106,636.708 579.5,634.5C 580.167,634.5 580.5,634.167 580.5,633.5C 584.921,628.719 586.421,623.053 585,616.5C 582.908,611.303 580.074,606.636 576.5,602.5C 572.33,594.82 567.663,587.487 562.5,580.5C 562.573,578.973 561.906,577.973 560.5,577.5C 559.66,575.147 558.326,573.147 556.5,571.5C 553.664,565.822 550.331,560.489 546.5,555.5C 533.273,533.389 519.773,511.389 506,489.5C 504.566,482.794 507.066,478.294 513.5,476C 561.499,475.5 609.499,475.333 657.5,475.5 Z"/>
+</svg>

package/templates/base/app/layout.tsx

@@ -1,5 +1,6 @@
 import type { Metadata } from 'next'
-import { Poppins, Cairo } from 'next/font/google'
+import { Poppins } from 'next/font/google'
+import localFont from 'next/font/local'
 import './globals.css'
 import AppProviders from '@/providers/AppProviders'
 
@@ -9,10 +10,19 @@ const poppins = Poppins({
   weight: ['300', '400', '500', '600', '700']
 })
 
-const cairo = Cairo({
-  subsets: ['arabic'],
-  variable: '--font-cairo',
-  weight: ['300', '400', '500', '600', '700']
+const montserratArabic = localFont({
+  src: [
+    { path: '../public/fonts/Montserrat-Arabic-Thin.ttf', weight: '100' },
+    { path: '../public/fonts/Montserrat-Arabic-ExtraLight.ttf', weight: '200' },
+    { path: '../public/fonts/Montserrat-Arabic-Light.ttf', weight: '300' },
+    { path: '../public/fonts/Montserrat-Arabic-Regular.ttf', weight: '400' },
+    { path: '../public/fonts/Montserrat-Arabic-Medium.ttf', weight: '500' },
+    { path: '../public/fonts/Montserrat-Arabic-SemiBold.ttf', weight: '600' },
+    { path: '../public/fonts/Montserrat-Arabic-Bold.ttf', weight: '700' },
+    { path: '../public/fonts/Montserrat-Arabic-ExtraBold.ttf', weight: '800' },
+    { path: '../public/fonts/Montserrat-Arabic-Black.ttf', weight: '900' }
+  ],
+  variable: '--font-montserrat-arabic'
 })
 export const metadata: Metadata = {
   title: 'Shortcut Nextjs Template',
@@ -26,7 +36,7 @@ export default async function RootLayout({
 }>) {
   return (
     <html lang='en' dir='ltr'>
-      <body className={`${poppins.variable} ${cairo.variable} antialiased`}>
+      <body className={`${poppins.variable} ${montserratArabic.variable} antialiased`}>
         <AppProviders>{children}</AppProviders>
       </body>
     </html>