saz-standards 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# @saz/standards
+
+> Enterprise React/Next.js coding standards by **Salman Ali Zahid**.
+
+One command sets up your entire project with enterprise-grade folder structure, components, configs, and coding rules.
+
+---
+
+## Quick Start
+
+```bash
+npx @saz/standards init
+```
+
+It will ask you:
+
+```
+Framework?
+  1 = React
+  2 = Next.js
+
+Language?
+  1 = JavaScript
+  2 = TypeScript
+```
+
+Then it copies everything into your project automatically.
+
+---
+
+## What Gets Copied
+
+- Full enterprise folder structure (4 variants)
+- All coding standards markdown files
+- ESLint, Tailwind, and TypeScript base configs
+
+---
+
+## Use the Configs
+
+### ESLint
+
+```js
+// .eslintrc.js
+module.exports = {
+  extends: ["./node_modules/@saz/standards/configs/eslint.js"]
+}
+```
+
+### Tailwind
+
+```js
+// tailwind.config.js
+const sazBase = require("@saz/standards/configs/tailwind");
+module.exports = { presets: [sazBase] }
+```
+
+### TypeScript
+
+```json
+// tsconfig.json
+{
+  "extends": "@saz/standards/configs/tsconfig.json"
+}
+```
+
+---
+
+## What Is Included
+
+### Standards Files
+
+| File | Description |
+| --- | --- |
+| CODING_STANDARDS.md | Enums, naming, exports, imports |
+| DESIGN_SYSTEM.md | Tailwind tokens, typography, dark mode |
+| COMPONENT_PATTERNS.md | Button, Input, Select, Modal, Table |
+| FORM_SYSTEM.md | useForm, Joi, Zod, validation |
+| DATA_FETCHING.md | Axios, thunks, abort controller |
+| STATE_MANAGEMENT.md | Redux Toolkit slices |
+| PERFORMANCE.md | Memoization, virtualization, splits |
+| SECURITY_AND_ACCESSIBILITY.md | ARIA, landmarks, CSP, env rules |
+
+### Project Variants
+
+| Variant | Stack |
+| --- | --- |
+| react-js | React + JavaScript + Vite |
+| react-ts | React + TypeScript + Vite |
+| nextjs-js | Next.js App Router + JavaScript |
+| nextjs-ts | Next.js App Router + TypeScript |
+
+---
+
+## Standards Rating
+
+This system is rated **10/10** covering:
+
+- Component patterns
+- Form validation (Joi + Zod)
+- Redux Toolkit state management
+- Axios service layer with HTTP-only cookie auth
+- Accessibility (ARIA, focus-visible, landmarks)
+- Dark mode strategy
+- List virtualization
+- Cross-browser compatibility
+- Security rules
+- Performance (Core Web Vitals)
+
+---
+
+## Author
+
+**Salman Ali Zahid**
+
+- GitHub: [MuhammadSalman0151](https://github.com/MuhammadSalman0151)
+- Package: [@saz/standards](https://www.npmjs.com/package/@saz/standards)
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const ask = (question) =>
+  new Promise((resolve) => rl.question(question, resolve));
+
+async function main() {
+  console.log("");
+  console.log("========================================");
+  console.log("   Welcome to @saz/standards");
+  console.log("   Enterprise React/Next.js Standards");
+  console.log("   by Salman Ali Zahid");
+  console.log("========================================");
+  console.log("");
+
+  const framework = await ask(
+    "Framework?\n  1 = React\n  2 = Next.js\nYour choice: ",
+  );
+  const language = await ask(
+    "\nLanguage?\n  1 = JavaScript\n  2 = TypeScript\nYour choice: ",
+  );
+
+  let variant = "";
+
+  if (framework === "1" && language === "1") variant = "react-js";
+  else if (framework === "1" && language === "2") variant = "react-ts";
+  else if (framework === "2" && language === "1") variant = "nextjs-js";
+  else if (framework === "2" && language === "2") variant = "nextjs-ts";
+  else {
+    console.log("\nInvalid choice. Please run again and enter 1 or 2.");
+    rl.close();
+    return;
+  }
+
+  const dest = process.cwd();
+
+  // Copy template files
+  const templateSrc = path.join(__dirname, "../templates", variant);
+  if (fs.existsSync(templateSrc)) {
+    fs.cpSync(templateSrc, dest, { recursive: true });
+  }
+
+  // Copy standards markdown files
+  const standardsSrc = path.join(__dirname, "../standards");
+  const standardsDest = path.join(dest, "standards");
+  if (fs.existsSync(standardsSrc)) {
+    fs.cpSync(standardsSrc, standardsDest, { recursive: true });
+  }
+
+  console.log("");
+  console.log("========================================");
+  console.log("  Done! Your project is ready.");
+  console.log("  Variant: " + variant);
+  console.log("  Standards copied to: /standards");
+  console.log("========================================");
+  console.log("");
+
+  rl.close();
+}
+
+main();

package/configs/eslint.js

@@ -0,0 +1,45 @@
+module.exports = {
+  env: {
+    browser: true,
+    es2021: true,
+    node: true,
+  },
+  extends: [
+    "eslint:recommended",
+    "plugin:react/recommended",
+    "plugin:react-hooks/recommended",
+  ],
+  parserOptions: {
+    ecmaVersion: "latest",
+    sourceType: "module",
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+  settings: {
+    react: {
+      version: "detect",
+    },
+  },
+  rules: {
+    // Variables
+    "no-unused-vars": "error",
+    "no-var": "error",
+    "prefer-const": "error",
+
+    // Code quality
+    "no-console": "warn",
+    "no-debugger": "error",
+    eqeqeq: ["error", "always"],
+    "no-duplicate-imports": "error",
+    "no-empty": "error",
+    "no-shadow": "error",
+
+    // React
+    "react/react-in-jsx-scope": "off",
+    "react/prop-types": "off",
+    "react/self-closing-comp": "warn",
+    "react-hooks/rules-of-hooks": "error",
+    "react-hooks/exhaustive-deps": "warn",
+  },
+};

package/configs/tailwind.js

@@ -0,0 +1,34 @@
+module.exports = {
+  content: ["./src/**/*.{js,jsx,ts,tsx}"],
+  darkMode: "class",
+  theme: {
+    extend: {
+      colors: {
+        "base-primary": "#3b82f6",
+        "base-primary-hover": "#2563eb",
+        "base-danger": "#ef4444",
+        "base-danger-hover": "#dc2626",
+        "base-success": "#22c55e",
+        "base-warning": "#f59e0b",
+        "base-info": "#3b82f6",
+        "base-surface": "#ffffff",
+        "base-surface-hover": "#f9fafb",
+        "base-border": "#e5e7eb",
+        "base-input": "#111827",
+        "base-placeholder": "#9ca3af",
+        "base-muted": "#6b7280",
+        "base-heading": "#111827",
+        "base-label": "#374151",
+      },
+      borderRadius: {
+        "base-radius-md": "0.375rem",
+        "base-radius-lg": "0.5rem",
+      },
+      boxShadow: {
+        "base-shadow-md": "0 4px 6px -1px rgb(0 0 0 / 0.1)",
+        "base-shadow-lg": "0 10px 15px -3px rgb(0 0 0 / 0.1)",
+      },
+    },
+  },
+  plugins: [],
+};

package/configs/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules"]
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "saz-standards",
+  "version": "1.0.0",
+  "description": "Enterprise React/Next.js coding standards — ESLint, Tailwind, TypeScript configs + CLI by Salman Ali Zahid",
+  "main": "index.js",
+  "bin": {
+    "saz": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "configs",
+    "templates",
+    "standards"
+  ],
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  },
+  "keywords": [
+    "react",
+    "nextjs",
+    "eslint",
+    "tailwind",
+    "typescript",
+    "coding-standards",
+    "enterprise",
+    "boilerplate",
+    "starter"
+  ],
+  "author": "Salman Ali Zahid",
+  "license": "MIT",
+  "type": "commonjs"
+}

package/standards/CODING_STANDARDS.md

@@ -0,0 +1,272 @@
+# Coding Standards
+
+> Universal coding rules applied to every project variant.
+
+---
+
+## Enum Rules
+
+- All enum keys must be `SCREAMING_SNAKE_CASE` (uppercase with underscores)
+- All enum values must be uppercase strings — never lowercase, never mixed case
+- Enums must be defined in `shared/constants/` or inside the module's `types/` folder when scoped to a single module
+- Never use numeric enums — always use string enums for readability and serialization safety
+- Never use inline object literals as a substitute for enums when the value set is fixed
+- In TypeScript projects, always use `const enum` or a plain `enum` with explicit string values — never rely on auto-incremented numeric values
+- Enum names must be PascalCase (e.g., `UserRole`, `OrderStatus`, `PaymentMethod`)
+- All enum members must be used — do not declare unused enum values
+- Never mutate or reassign enum values at runtime
+
+### TypeScript Example
+
+```ts
+enum UserRole {
+  SUPER_ADMIN = "SUPER_ADMIN",
+  ADMIN = "ADMIN",
+  MANAGER = "MANAGER",
+  STAFF = "STAFF",
+  GUEST = "GUEST",
+}
+
+enum OrderStatus {
+  PENDING = "PENDING",
+  CONFIRMED = "CONFIRMED",
+  IN_PROGRESS = "IN_PROGRESS",
+  COMPLETED = "COMPLETED",
+  CANCELLED = "CANCELLED",
+}
+```
+
+### JavaScript Example
+
+```js
+const UserRole = Object.freeze({
+  SUPER_ADMIN: "SUPER_ADMIN",
+  ADMIN: "ADMIN",
+  MANAGER: "MANAGER",
+  STAFF: "STAFF",
+  GUEST: "GUEST",
+});
+
+const OrderStatus = Object.freeze({
+  PENDING: "PENDING",
+  CONFIRMED: "CONFIRMED",
+  IN_PROGRESS: "IN_PROGRESS",
+  COMPLETED: "COMPLETED",
+  CANCELLED: "CANCELLED",
+});
+```
+
+---
+
+## ESLint and Code Quality Rules
+
+- No unused variables, imports, or functions
+- No `console` statements in production code
+- No `debugger` statements
+- Avoid shadowed variables
+- Prefer `const` over `let` when values do not change
+- Avoid `var` entirely
+- Use strict equality (`===` and `!==`)
+- No empty functions or empty blocks
+- No duplicate code
+- Keep functions small and focused
+- Use early returns for clarity
+- Avoid side effects in render logic
+- No mutation of props or external state
+- Follow consistent formatting and naming conventions
+- Ensure all dependencies are correctly specified in React hook dependency arrays
+- Do not disable ESLint rules unless absolutely necessary
+
+---
+
+## File Naming Rules
+
+| Type | Convention | Example |
+| --- | --- | --- |
+| Components | PascalCase | `UserCard.tsx` |
+| Hooks | useCamelCase | `useForm.ts` |
+| Utilities | camelCase | `formatDate.ts` |
+| Types (TS) | PascalCase | `User.types.ts` |
+| Enums | PascalCase name, SCREAMING_SNAKE_CASE keys/values | `UserRole` |
+
+---
+
+## Export Rules
+
+- Components: `default export` allowed
+- Utilities, hooks, and constants: named exports preferred
+- Enums: named exports only
+
+---
+
+## Barrel Export Rules
+
+Apply barrel exports in any component folder containing more than 3 files.
+
+```js
+// components/buttons/index.js
+export { default as CloseButton } from "./CloseButton";
+export { default as FormSubmitButton } from "./FormSubmitButton";
+export { default as IconButton } from "./IconButton";
+```
+
+---
+
+## Import Pattern
+
+Use relative imports only. Use root index exports when importing multiple components from the same folder.
+
+```js
+import { CloseButton, FormSubmitButton } from "../../../components/buttons";
+import { Inputfield, SelectFromObject } from "../../../components/form";
+import { cn } from "../../utils/cn";
+```
+
+Next.js imports when needed:
+
+```js
+import Image from "next/image";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import dynamic from "next/dynamic";
+import { Metadata } from "next";
+```
+
+---
+
+## General Component Rules
+
+- Default export function component
+- Props destructured in parameters with safe default values
+- No PropTypes
+- No `React.FC`
+- No class components
+- No unnecessary fragments or wrappers
+- No inline styles
+- Explicit conditional rendering only: `condition ? <Component /> : null`
+
+---
+
+## Runtime and Prop Safety Rules
+
+- Validate critical data before use
+- Check for `null` or `undefined` before property access
+- Use optional chaining for nested values: `data?.map(...)`
+- Provide safe default values for all optional props
+- Ensure values are arrays before mapping
+- Provide fallback UI when arrays are empty
+- Do not assume API response structure — handle missing or malformed data gracefully
+
+---
+
+## List Rendering Rules
+
+- Always use optional chaining before map: `data?.map(...)`
+- Key must be dynamic and stable when available: `key={item._id || item.id || item.value}`
+- Use index as key only when required by UI conditions or when no stable key exists: `key={index}`
+- Do not use random values as keys
+- Do not omit keys
+
+---
+
+## UI State Rules
+
+- Always handle the loading state when async data is used
+- Provide fallback UI for empty data
+- Display error state when operations fail
+- Do not render undefined data
+
+---
+
+## Event Handler Types (TypeScript)
+
+```ts
+React.ChangeEvent<HTMLInputElement>
+React.FormEvent<HTMLFormElement>
+React.MouseEvent<HTMLButtonElement>
+```
+
+---
+
+## TypeScript Rules
+
+> Applied only when TypeScript is selected (Q4 = B).
+
+- Strict typing required
+- Do NOT use `any`
+- Do NOT use `unknown` as a shortcut
+- Use proper interfaces or types for all props, state, API responses, and Redux data
+- Prefer explicit types over inference when unclear
+- Use union types when appropriate
+- Use generics when needed
+- All component props must be typed
+- Event handlers must use correct React types
+- Nullable values must be typed explicitly
+- Avoid the non-null assertion operator (`!`) unless the value is guaranteed to be non-null
+
+---
+
+## Environment Rules
+
+- Access environment variables safely
+- Do NOT hardcode secrets or sensitive URLs
+- In Next.js, prefix only public variables with `NEXT_PUBLIC_`
+- In Vite, prefix only public variables with `VITE_`
+- Never expose server-only secrets to the client bundle
+- Every project must include a `.env.example` file at the root listing all required variable names with placeholder values — never commit `.env` or `.env.local`
+
+```sh
+# .env.example
+VITE_API_BASE_URL=https://api.example.com       # React/Vite
+NEXT_PUBLIC_API_BASE_URL=https://api.example.com # Next.js
+```
+
+- `.env` and `.env.local` must be listed in `.gitignore`
+- New developers must copy `.env.example` to `.env` (Vite) or `.env.local` (Next.js) and fill in real values
+
+---
+
+## Styling Constraints
+
+- Tailwind only
+- Use project design tokens
+- No CSS modules
+- No styled-components
+- No inline styles
+
+---
+
+## cn() Utility
+
+All projects must include a `cn` utility at `src/utils/cn.ts` (TypeScript) or `src/utils/cn.js` (JavaScript). This is the canonical implementation — do not alter it:
+
+**TypeScript (`src/utils/cn.ts`):**
+
+```ts
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+```
+
+**JavaScript (`src/utils/cn.js`):**
+
+```js
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+```
+
+Usage pattern (from `DESIGN_SYSTEM.md`):
+
+```tsx
+className={cn("base classes", condition && "conditional class", className)}
+```
+
+- Always import `cn` from `../utils/cn` (relative path)
+- Never replicate this logic inline — always import from the utility file