@appcorp/fusion-storybook 0.1.4

package/README.md

@@ -0,0 +1,147 @@
+# Fusion Storybook
+
+A component library built with a modern tech stack for maximum reusability across multiple projects.
+
+## Tech Stack
+
+- **[Next.js 16](https://nextjs.org/)** - React framework with App Router
+- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript
+- **[Tailwind CSS v4](https://tailwindcss.com/)** - Utility-first CSS framework
+- **[ShadcnUI](https://ui.shadcn.com/)** - Accessible component library built on Radix UI
+- **[Storybook 10](https://storybook.js.org/)** - Component development and documentation
+- **[ESLint](https://eslint.org/)** - Code linting with Next.js rules
+- **[Prettier](https://prettier.io/)** - Code formatting with Tailwind class sorting
+- **[Husky](https://typicode.github.io/husky/)** - Git hooks for quality enforcement
+- **[lint-staged](https://github.com/okonet/lint-staged)** - Run linters on staged files
+- **[commitlint](https://commitlint.js.org/)** - Enforce conventional commit messages
+- **[Jest](https://jestjs.io/)** - Unit and integration testing
+- **[Playwright](https://playwright.dev/)** - End-to-end browser testing
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- npm 10+
+
+### Installation
+
+```bash
+npm install
+```
+
+### Development
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view the app.
+
+### Storybook
+
+```bash
+npm run storybook
+```
+
+Open [http://localhost:6006](http://localhost:6006) to view the Storybook.
+
+## Scripts
+
+| Script                    | Description                      |
+| ------------------------- | -------------------------------- |
+| `npm run dev`             | Start Next.js development server |
+| `npm run build`           | Build for production             |
+| `npm run start`           | Start production server          |
+| `npm run lint`            | Run ESLint                       |
+| `npm run lint:fix`        | Run ESLint with auto-fix         |
+| `npm run format`          | Format all files with Prettier   |
+| `npm run format:check`    | Check formatting without writing |
+| `npm run storybook`       | Start Storybook dev server       |
+| `npm run build-storybook` | Build Storybook for production   |
+| `npm run test`            | Run Jest unit tests              |
+| `npm run test:watch`      | Run Jest in watch mode           |
+| `npm run test:ci`         | Run Jest with coverage (CI mode) |
+| `npm run test:e2e`        | Run Playwright e2e tests         |
+| `npm run test:e2e:ui`     | Run Playwright with UI           |
+| `npm run test:e2e:report` | Open Playwright HTML report      |
+
+## Git Workflow
+
+This project enforces code quality via Husky git hooks:
+
+### Pre-commit
+
+- Runs `lint-staged` which lints and formats only staged files
+
+### Commit Message
+
+- Enforces [Conventional Commits](https://www.conventionalcommits.org/) format via commitlint
+- Examples:
+  - `feat: add new button component`
+  - `fix: resolve responsive layout issue`
+  - `docs: update README`
+  - `test: add unit tests for button`
+
+### Pre-push
+
+- Runs the full Jest test suite before pushing
+
+## Project Structure
+
+```
+fusion-storybook/
+├── src/
+│   ├── app/              # Next.js App Router
+│   │   ├── globals.css   # Global styles with ShadcnUI CSS variables
+│   │   ├── layout.tsx    # Root layout
+│   │   └── page.tsx      # Home page
+│   ├── components/
+│   │   └── ui/           # ShadcnUI components
+│   │       └── button.tsx
+│   ├── lib/
+│   │   └── utils.ts      # Utility functions (cn helper)
+│   ├── hooks/            # Custom React hooks
+│   ├── stories/          # Storybook stories
+│   └── __tests__/        # Jest unit tests
+├── tests/
+│   └── e2e/              # Playwright e2e tests
+├── .husky/               # Husky git hooks
+├── .storybook/           # Storybook configuration
+├── .vscode/              # VS Code settings
+├── components.json       # ShadcnUI configuration
+├── jest.config.ts        # Jest configuration
+├── jest.setup.ts         # Jest setup (testing-library/jest-dom)
+├── playwright.config.ts  # Playwright configuration
+├── commitlint.config.ts  # Commitlint configuration
+└── .prettierrc           # Prettier configuration
+```
+
+## Adding ShadcnUI Components
+
+Once the `shadcn` CLI can reach the registry, use:
+
+```bash
+npx shadcn@latest add button
+npx shadcn@latest add dialog
+npx shadcn@latest add dropdown-menu
+```
+
+## VS Code Integration
+
+Install recommended extensions for the best development experience:
+
+- **Prettier** - Code formatting
+- **ESLint** - Code linting
+- **Tailwind CSS IntelliSense** - Tailwind class hints
+- **Storybook** - Storybook integration
+- **Playwright** - Test runner integration
+
+Format on save is enabled by default via `.vscode/settings.json`.
+
+## Code Quality
+
+- **ESLint** enforces Next.js and TypeScript best practices
+- **Prettier** with `prettier-plugin-tailwindcss` auto-sorts Tailwind classes
+- **lint-staged** runs linters only on staged files (fast!)
+- **commitlint** ensures consistent commit message format

package/base-modules/admission/cache.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Admission Module Cache Utilities
+ *
+ * Provides localStorage-based caching for admissions using generic cache system.
+ */
+import { StudentProfileBE } from "../../type";
+export declare const getCachedAdmissionsSync: () => import("@react-pakistan/util-functions").ListResponse<StudentProfileBE>;
+export declare const getCachedAdmissions: ({ params, }: {
+    params: Record<string, unknown>;
+}) => Promise<import("@react-pakistan/util-functions").ListResponse<StudentProfileBE>>;
+export declare const getCachedAdmissionById: (admissionId: string) => StudentProfileBE | null;
+export declare const invalidateAdmissionsCache: () => void;
+export declare const preloadAdmissions: () => Promise<import("@react-pakistan/util-functions").ListResponse<StudentProfileBE>>;
+export declare const isAdmissionsCacheStale: () => boolean;

package/base-modules/admission/cache.js

@@ -0,0 +1,31 @@
+/**
+ * Admission Module Cache Utilities
+ *
+ * Provides localStorage-based caching for admissions using generic cache system.
+ */
+import { LS_KEYS } from "../../constants";
+import { ADMISSION_API_ROUTES } from "./constants";
+import { getCachedData, getCachedDataSync, getCachedItemById, invalidateCache, isCacheStale, preloadCache, } from "@react-pakistan/util-functions";
+// ============================================================================
+// CACHE CONFIGURATION
+// ============================================================================
+const ADMISSION_CACHE_CONFIG = {
+    apiUrl: ADMISSION_API_ROUTES.UNIT,
+    cacheKey: LS_KEYS.ADMISSIONS,
+};
+// ============================================================================
+// ADMISSION-SPECIFIC CACHE FUNCTIONS
+// ============================================================================
+export const getCachedAdmissionsSync = () => getCachedDataSync(LS_KEYS.ADMISSIONS);
+export const getCachedAdmissions = ({ params, }) => getCachedData({
+    config: ADMISSION_CACHE_CONFIG,
+    params,
+    headers: {
+        "Content-Type": "application/json",
+        "x-api-token": process.env.NEXT_PUBLIC_API_KEY,
+    },
+});
+export const getCachedAdmissionById = (admissionId) => getCachedItemById(LS_KEYS.ADMISSIONS, admissionId);
+export const invalidateAdmissionsCache = () => invalidateCache(LS_KEYS.ADMISSIONS);
+export const preloadAdmissions = () => preloadCache(ADMISSION_CACHE_CONFIG);
+export const isAdmissionsCacheStale = () => isCacheStale(LS_KEYS.ADMISSIONS);

package/base-modules/admission/constants.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Admission Constants
+ *
+ * Organization:
+ * - Page Configuration
+ * - API Routes
+ * - Table Configuration
+ * - Status Options
+ */
+import { ADMISSION_STATUS } from "../../type";
+export declare const pageLimit: number;
+export declare const ADMISSION_API_ROUTES: Record<string, string>;
+export declare const ADMISSION_STATUS_OPTIONS: {
+    label: string;
+    value: ADMISSION_STATUS;
+}[];
+export declare const ADMISSION_STATUS_OPTIONS_CONST: readonly [{
+    readonly label: "Pending";
+    readonly value: ADMISSION_STATUS.PENDING;
+}, {
+    readonly label: "Approved";
+    readonly value: ADMISSION_STATUS.APPROVED;
+}, {
+    readonly label: "Rejected";
+    readonly value: ADMISSION_STATUS.REJECTED;
+}, {
+    readonly label: "Enrolled";
+    readonly value: ADMISSION_STATUS.ENROLLED;
+}, {
+    readonly label: "Cancelled";
+    readonly value: ADMISSION_STATUS.CANCELLED;
+}];

package/base-modules/admission/constants.js

@@ -0,0 +1,37 @@
+/**
+ * Admission Constants
+ *
+ * Organization:
+ * - Page Configuration
+ * - API Routes
+ * - Table Configuration
+ * - Status Options
+ */
+import { ADMISSION_STATUS } from "../../type";
+// ============================================================================
+// PAGE CONFIGURATION
+// ============================================================================
+export const pageLimit = Number(process.env.NEXT_PUBLIC_PAGE_LIMIT) || 10;
+// ============================================================================
+// API ROUTES
+// ============================================================================
+export const ADMISSION_API_ROUTES = {
+    UNIT: "/api/v1/admission",
+};
+// ============================================================================
+// STATUS OPTIONS
+// ============================================================================
+export const ADMISSION_STATUS_OPTIONS = [
+    { label: "Pending", value: ADMISSION_STATUS.PENDING },
+    { label: "Approved", value: ADMISSION_STATUS.APPROVED },
+    { label: "Rejected", value: ADMISSION_STATUS.REJECTED },
+    { label: "Enrolled", value: ADMISSION_STATUS.ENROLLED },
+    { label: "Cancelled", value: ADMISSION_STATUS.CANCELLED },
+];
+export const ADMISSION_STATUS_OPTIONS_CONST = [
+    { label: "Pending", value: ADMISSION_STATUS.PENDING },
+    { label: "Approved", value: ADMISSION_STATUS.APPROVED },
+    { label: "Rejected", value: ADMISSION_STATUS.REJECTED },
+    { label: "Enrolled", value: ADMISSION_STATUS.ENROLLED },
+    { label: "Cancelled", value: ADMISSION_STATUS.CANCELLED },
+];

package/base-modules/admission/context.d.ts

@@ -0,0 +1,369 @@
+import { AdmissionAIBE, AdmissionBE } from "../../type";
+import { type RowAction, type TableRow } from "@appcorp/shadcn/components/enhanced-table";
+export declare const ADMISSION_DRAWER: {
+    readonly FILTER_DRAWER: string;
+    readonly FORM_DRAWER: string;
+    readonly MORE_ACTIONS_DRAWER: string;
+    readonly VIEW_DRAWER: string;
+};
+export declare const ADMISSION_ACTION_TYPES: {
+    readonly RESET_FORM: "RESET_FORM";
+    readonly SET_CURRENT_PAGE: "SET_CURRENT_PAGE";
+    readonly SET_PAGE_LIMIT: "SET_PAGE_LIMIT";
+    readonly SET_SEARCH_QUERY: "SET_SEARCH_QUERY";
+    readonly SET_DRAWER: "SET_DRAWER";
+    readonly SET_ITEMS: "SET_ITEMS";
+    readonly SET_FORM_DATA: "SET_FORM_DATA";
+    readonly SET_DISABLE_SAVE_BUTTON: "SET_DISABLE_SAVE_BUTTON";
+    readonly SET_INPUT_FIELD: "SET_INPUT_FIELD";
+    readonly SET_ERRORS: "SET_ERRORS";
+    readonly SET_FILTERS: "SET_FILTERS";
+}, admissionModuleConfig: import("@react-pakistan/util-functions/factory/generic-module-factory").ModuleConfig<{
+    items: AdmissionBE[];
+    count: number;
+    currentPage: number;
+    pageLimit: number;
+    searchQuery: string;
+    disableSaveButton: boolean;
+    drawer: string | null;
+    errors: Record<string, string>;
+    id: string;
+    bForm: string;
+    discountCode: string;
+    dob: string;
+    emergencyContact: string;
+    firstName: string;
+    gender: string;
+    hafiz: boolean;
+    lastName: string;
+    orphan: boolean;
+    registrationCode: string;
+    fatherCnic: string;
+    fatherFirstName: string;
+    fatherLastName: string;
+    fatherMobile: string;
+    fatherOccupation: string;
+    fatherOrganization: string;
+    motherCnic: string;
+    motherFirstName: string;
+    motherLastName: string;
+    motherMobile: string;
+    address: string;
+    city: string;
+    country: string;
+    postalCode: string;
+    state: string;
+    classForAdmission: string;
+    previousSchool: string;
+    siblings: string;
+    admissionNotes: string;
+    notes: string;
+    enabled: boolean;
+    status: string;
+    admissionStatus: string;
+    schoolId: string;
+    familyId: string | null;
+    aiAnalysis: AdmissionAIBE | null;
+    analyzeLoading: boolean;
+    analyzeError: string | null;
+    filterEnabled: boolean | undefined;
+    filterAdmissionStatus: string | undefined;
+    filterStartDate: string | undefined;
+    filterEndDate: string | undefined;
+}>, initialAdmissionState: {
+    items: AdmissionBE[];
+    count: number;
+    currentPage: number;
+    pageLimit: number;
+    searchQuery: string;
+    disableSaveButton: boolean;
+    drawer: string | null;
+    errors: Record<string, string>;
+    id: string;
+    bForm: string;
+    discountCode: string;
+    dob: string;
+    emergencyContact: string;
+    firstName: string;
+    gender: string;
+    hafiz: boolean;
+    lastName: string;
+    orphan: boolean;
+    registrationCode: string;
+    fatherCnic: string;
+    fatherFirstName: string;
+    fatherLastName: string;
+    fatherMobile: string;
+    fatherOccupation: string;
+    fatherOrganization: string;
+    motherCnic: string;
+    motherFirstName: string;
+    motherLastName: string;
+    motherMobile: string;
+    address: string;
+    city: string;
+    country: string;
+    postalCode: string;
+    state: string;
+    classForAdmission: string;
+    previousSchool: string;
+    siblings: string;
+    admissionNotes: string;
+    notes: string;
+    enabled: boolean;
+    status: string;
+    admissionStatus: string;
+    schoolId: string;
+    familyId: string | null;
+    aiAnalysis: AdmissionAIBE | null;
+    analyzeLoading: boolean;
+    analyzeError: string | null;
+    filterEnabled: boolean | undefined;
+    filterAdmissionStatus: string | undefined;
+    filterStartDate: string | undefined;
+    filterEndDate: string | undefined;
+}, AdmissionProvider: import("react").FC<{
+    children: React.ReactNode;
+}>, admissionReducer: (state: {
+    items: AdmissionBE[];
+    count: number;
+    currentPage: number;
+    pageLimit: number;
+    searchQuery: string;
+    disableSaveButton: boolean;
+    drawer: string | null;
+    errors: Record<string, string>;
+    id: string;
+    bForm: string;
+    discountCode: string;
+    dob: string;
+    emergencyContact: string;
+    firstName: string;
+    gender: string;
+    hafiz: boolean;
+    lastName: string;
+    orphan: boolean;
+    registrationCode: string;
+    fatherCnic: string;
+    fatherFirstName: string;
+    fatherLastName: string;
+    fatherMobile: string;
+    fatherOccupation: string;
+    fatherOrganization: string;
+    motherCnic: string;
+    motherFirstName: string;
+    motherLastName: string;
+    motherMobile: string;
+    address: string;
+    city: string;
+    country: string;
+    postalCode: string;
+    state: string;
+    classForAdmission: string;
+    previousSchool: string;
+    siblings: string;
+    admissionNotes: string;
+    notes: string;
+    enabled: boolean;
+    status: string;
+    admissionStatus: string;
+    schoolId: string;
+    familyId: string | null;
+    aiAnalysis: AdmissionAIBE | null;
+    analyzeLoading: boolean;
+    analyzeError: string | null;
+    filterEnabled: boolean | undefined;
+    filterAdmissionStatus: string | undefined;
+    filterStartDate: string | undefined;
+    filterEndDate: string | undefined;
+}, action: any) => {
+    items: AdmissionBE[];
+    count: number;
+    currentPage: number;
+    pageLimit: number;
+    searchQuery: string;
+    disableSaveButton: boolean;
+    drawer: string | null;
+    errors: Record<string, string>;
+    id: string;
+    bForm: string;
+    discountCode: string;
+    dob: string;
+    emergencyContact: string;
+    firstName: string;
+    gender: string;
+    hafiz: boolean;
+    lastName: string;
+    orphan: boolean;
+    registrationCode: string;
+    fatherCnic: string;
+    fatherFirstName: string;
+    fatherLastName: string;
+    fatherMobile: string;
+    fatherOccupation: string;
+    fatherOrganization: string;
+    motherCnic: string;
+    motherFirstName: string;
+    motherLastName: string;
+    motherMobile: string;
+    address: string;
+    city: string;
+    country: string;
+    postalCode: string;
+    state: string;
+    classForAdmission: string;
+    previousSchool: string;
+    siblings: string;
+    admissionNotes: string;
+    notes: string;
+    enabled: boolean;
+    status: string;
+    admissionStatus: string;
+    schoolId: string;
+    familyId: string | null;
+    aiAnalysis: AdmissionAIBE | null;
+    analyzeLoading: boolean;
+    analyzeError: string | null;
+    filterEnabled: boolean | undefined;
+    filterAdmissionStatus: string | undefined;
+    filterStartDate: string | undefined;
+    filterEndDate: string | undefined;
+}, useAdmissionContext: () => import("@react-pakistan/util-functions/factory/generic-module-factory").GenericModuleContext<{
+    items: AdmissionBE[];
+    count: number;
+    currentPage: number;
+    pageLimit: number;
+    searchQuery: string;
+    disableSaveButton: boolean;
+    drawer: string | null;
+    errors: Record<string, string>;
+    id: string;
+    bForm: string;
+    discountCode: string;
+    dob: string;
+    emergencyContact: string;
+    firstName: string;
+    gender: string;
+    hafiz: boolean;
+    lastName: string;
+    orphan: boolean;
+    registrationCode: string;
+    fatherCnic: string;
+    fatherFirstName: string;
+    fatherLastName: string;
+    fatherMobile: string;
+    fatherOccupation: string;
+    fatherOrganization: string;
+    motherCnic: string;
+    motherFirstName: string;
+    motherLastName: string;
+    motherMobile: string;
+    address: string;
+    city: string;
+    country: string;
+    postalCode: string;
+    state: string;
+    classForAdmission: string;
+    previousSchool: string;
+    siblings: string;
+    admissionNotes: string;
+    notes: string;
+    enabled: boolean;
+    status: string;
+    admissionStatus: string;
+    schoolId: string;
+    familyId: string | null;
+    aiAnalysis: AdmissionAIBE | null;
+    analyzeLoading: boolean;
+    analyzeError: string | null;
+    filterEnabled: boolean | undefined;
+    filterAdmissionStatus: string | undefined;
+    filterStartDate: string | undefined;
+    filterEndDate: string | undefined;
+}>;
+export declare const useAdmissionModule: () => {
+    applyFilters: () => void;
+    byIdLoading: boolean;
+    clearFilters: () => void;
+    deleteLoading: boolean;
+    handleAddStudent: (row?: unknown) => Promise<void>;
+    handleAnalyze: (row?: unknown) => Promise<void>;
+    handleChange: (field: string, value: string | number | boolean | undefined | null) => void;
+    handleCloseDrawer: () => void;
+    handleCreate: () => void;
+    handleDelete: (row?: TableRow) => void;
+    handleEdit: (row?: TableRow) => void;
+    handleFilters: () => void;
+    handlePageChange: (page: number) => void;
+    handlePageLimitChange: (limit: number) => void;
+    handlePrint: (row?: TableRow) => Promise<void>;
+    handleSearch: (query: string) => void;
+    handleSetEndDate: (endDate: string) => void;
+    handleSetStartDate: (startDate: string) => void;
+    handleSubmit: () => void;
+    handleView: (row?: TableRow) => void;
+    headerActions: {
+        enabled: boolean;
+        handleOnClick: () => void;
+        label: string;
+        order: number;
+        icon: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    }[];
+    listLoading: boolean;
+    rowActions: RowAction[];
+    updateLoading: boolean;
+    state: {
+        items: AdmissionBE[];
+        count: number;
+        currentPage: number;
+        pageLimit: number;
+        searchQuery: string;
+        disableSaveButton: boolean;
+        drawer: string | null;
+        errors: Record<string, string>;
+        id: string;
+        bForm: string;
+        discountCode: string;
+        dob: string;
+        emergencyContact: string;
+        firstName: string;
+        gender: string;
+        hafiz: boolean;
+        lastName: string;
+        orphan: boolean;
+        registrationCode: string;
+        fatherCnic: string;
+        fatherFirstName: string;
+        fatherLastName: string;
+        fatherMobile: string;
+        fatherOccupation: string;
+        fatherOrganization: string;
+        motherCnic: string;
+        motherFirstName: string;
+        motherLastName: string;
+        motherMobile: string;
+        address: string;
+        city: string;
+        country: string;
+        postalCode: string;
+        state: string;
+        classForAdmission: string;
+        previousSchool: string;
+        siblings: string;
+        admissionNotes: string;
+        notes: string;
+        enabled: boolean;
+        status: string;
+        admissionStatus: string;
+        schoolId: string;
+        familyId: string | null;
+        aiAnalysis: AdmissionAIBE | null;
+        analyzeLoading: boolean;
+        analyzeError: string | null;
+        filterEnabled: boolean | undefined;
+        filterAdmissionStatus: string | undefined;
+        filterStartDate: string | undefined;
+        filterEndDate: string | undefined;
+    };
+    dispatch: React.Dispatch<any>;
+};