xXx

Hexid M1n1 5h3ll MobiLe

home/emberdemos/corehr_app/current/docs/trackers/_[ Writable ]

File:/home/emberdemos/corehr_app/current/docs/trackers/PHASE_01.5.md

# CoreHR: Phase 1.5 Tracker

## **Phase 1.5: Branding & Theming Engine**

**Overall Goal:** Enhance the application's settings to allow for full white-labeling and branding customization, including logo uploads and a dynamic theming engine.

**Approach:** Backend-first for file handling, then Frontend integration.
**UI/Tech Stack:** Laravel, `spatie/laravel-medialibrary`, Vue.js, TypeScript, CSS Variables.

**Status:** ✅ **Completed**

---

### Milestone 1.5.1: Logo & Favicon Management

**Goal:** Implement a robust system for uploading, storing, and displaying company logos and favicons.

| Task ID | Task Description | Backend/Frontend | TDD Focus (Key Tests) | Status | Notes/Blockers |
| :--- | :--- | :--- | :--- | :--- | :--- |
| P1.5.1.1 | **Backend:** Install and configure `spatie/laravel-medialibrary`. | Backend | - Test migrations run. - Test `storage:link` works. | ✅ Done | Initial attempt to publish assets failed due to stale cache; resolved by running `config:clear`. |
| P1.5.1.2 | **[RE-ARCHITECTED]** **Backend:** Create a dedicated `Branding` model to handle media. | Backend | - Test `Branding` model can have media associated. | ✅ Done | Initial attempt to implement `HasMedia` on the `Settings` class caused dependency conflicts. Decoupled media handling into its own Eloquent model for a cleaner, more stable architecture. |
| P1.5.1.3 | **Backend:** Update `SettingsController` to handle file uploads for the `Branding` model. | Backend | - An admin can upload a logo and favicon. - Validation prevents non-image uploads. - Old logos are replaced automatically. | ✅ Done | Controller logic updated to interact with both the `GeneralSettings` object and the new `Branding` model. |
| P1.5.1.4 | **[ENHANCED]** **Backend:** Share branding URLs (`logo_url`, `sidebar_icon_url`, `favicon_url`) and `company_name` globally via `HandleInertiaRequests` middleware. | Backend | - Test that the Inertia response contains the correct media URLs and company name on every page. | ✅ Done | Enhanced to include default asset URLs if no custom media is uploaded. Moved `company_name` to this global prop for sidebar use. |
| P1.5.1.5 | **Frontend:** Update `Settings/Index.vue` form with refined, reusable `ImageInput` component. | Frontend | N/A (UI Implementation) | ✅ Done | Created a new `ImageInput.vue` component to handle file selection and previews. Added instructions and specific preview sizes. |
| P1.5.1.6 | **Frontend:** Update `AppSidebar.vue` and `AuthenticatedLayout.vue` to dynamically display the uploaded branding. | Frontend | N/A (UI Implementation) | ✅ Done | Implemented a `useBranding` composable to cleanly access the new global props. The sidebar now shows the icon and dynamic name. The layout sets the favicon. |

---

### Milestone 1.5.2: Dynamic Theming Engine

**Goal:** Use the stored `primary_color` to dynamically generate and apply a full color theme to the application.

| Task ID | Task Description | Backend/Frontend | TDD Focus (Key Tests) | Status | Notes/Blockers |
| :--- | :--- | :--- | :--- | :--- | :--- |
| P1.5.2.1 | **Frontend:** Create a `useThemeEngine` composable. | Frontend | - Test that a hex color is correctly converted to HSL. | ✅ Done | The composable reads the `primary_color` from the globally shared `branding` prop. |
| P1.5.2.2 | **Frontend:** Implement logic within the composable to generate a palette of HSL values from the base primary color. | Frontend | - Test that it generates correct `--primary` and `--primary-foreground` HSL strings. | ✅ Done | Logic is self-contained in a `hexToHslString` utility function within the composable. |
| P1.5.2.3 | **Frontend:** Implement logic to inject the generated palette as CSS variables into the document's `:root`. | Frontend | N/A (DOM manipulation) | ✅ Done | Logic was added to an `applyTheme` function and is triggered by `onMounted` and `watch` hooks. |
| P1.5.2.4 | **Frontend:** Call `useThemeEngine` from the main `AuthenticatedLayout.vue`. | Frontend | - Test that changing the color in settings updates the CSS variables on page load. | ✅ Done | Also required updating `tailwind.config.js` and `app.css` to fully support CSS variable-based theming. |

---

### **[ADDED] Out-of-Scope Refinements & Features**

**Goal:** Address critical architectural gaps and UI/UX issues identified during development.

| Task ID | Task Description | Backend/Frontend | TDD Focus (Key Tests) | Status | Notes/Blockers |
| :--- | :--- | :--- | :--- | :--- | :--- |
| P1.5.R.1 | **[ADDED]** **Backend & Frontend:** Implement a complete, granular RBAC system. | Both | - Test Super Admin gate. - Test `can:` middleware on routes. - Test Policies on controllers. | ✅ Done | This was a major, necessary addition. Involved creating a comprehensive `PermissionSeeder`, an `AuthServiceProvider` gate, refactoring all routes to use `can:` middleware, and implementing Policies for controllers. |
| P1.5.R.2 | **[ADDED]** **Backend & Frontend:** Implement a dynamic, custom Role Management UI (Permission Matrix). | Both | - Test creating/renaming/deleting roles. - Test syncing permissions. | ✅ Done | Created a full CRUD interface for Roles, allowing Super Admins to create new roles and assign permissions from a powerful grid interface. |
| P1.5.R.3 | **[ADDED]** **Backend:** Implement persistent, draggable ordering for Role columns. | Backend | - Test that the new `display_order` is saved correctly on drag-and-drop. - Test that the order is maintained on refresh. | ✅ Done | Added a `display_order` column to the `roles` table and created a dedicated controller method to save the new order. |
| P1.5.R.4 | **[ADDED]** **Frontend:** Implement "Select All" functionality in the Permission Matrix. | Frontend | N/A (UI Implementation) | ✅ Done | Added checkboxes to select all permissions for a role, and to select all permissions in a group for a specific role, significantly improving usability. |
| P1.5.R.5 | **[REPLACED]** **Frontend & Backend:** Refactor all Phase 1 index pages to use a reusable TanStack Table component. | Both | N/A (UI/Component Refactor) | ✅ Done | Replaced basic tables with a powerful `DataTable.vue` component, adding client-side sorting, filtering, column visibility, and integrated pagination. Removed server-side pagination from controllers. |
| P1.5.R.6 | **[ADDED]** **Frontend:** Implement multi-row selection with checkboxes in the DataTable component. | Frontend | N/A (UI Implementation) | ✅ Done | Added a 'select' column to all data tables to enable bulk actions. |
| P1.5.R.7 | **[ADDED]** **Backend & Frontend:** Implement bulk actions (Archive/Delete) for selected rows. | Both | N/A (UI Implementation) | ✅ Done | Added context-aware buttons that appear when rows are selected, supported by new backend routes, controller methods, and authorization policies. |
| P1.5.R.8 | **[ADDED]** **Architecture:** Refactor simple CRUD from dedicated pages to a dialog-based workflow. | Both | N/A (UI Implementation) | ✅ Done | Replaced `Create.vue` and `Edit.vue` pages for Users, Departments, and Designations with a single, reusable Form partial rendered in a dialog on the index page, improving UX and reducing code duplication. |
| P1.5.R.9 | **[ADDED]** **Frontend:** Upgrade form partials to use `shadcn-vue` Form components and Laravel Precognition. | Frontend | N/A (UI Implementation) | ✅ Done | Refactored form partials (e.g., `DepartmentForm.vue`) to use `<FormField>`, `<FormItem>`, and `<FormMessage>` for better structure, accessibility, and live validation feedback. |

Your Access Expired	Date. in : 15-12-2025
Regist : 09-12-2024	Expired : 01-12-2027