L-Ami-Fiduciaire/_bmad-output/implementation-artifacts/0-3-rename-folders-to-declarations-in-frontend.md

Story 0.3: Rename Folders to Declarations in Frontend

Status: done

Story

As a developer, I want all frontend Vue/TypeScript code to use "declaration" terminology instead of "folder", so that the UI codebase is consistent with the backend and domain language.

Acceptance Criteria

1. Given the backend rename from Story 0.2 is complete, When the frontend rename is complete, Then resources/js/pages/folders/ directory is renamed to resources/js/pages/declarations/
2. And all Vue page components (Index, Show, Create, Edit) reference "declaration" in component names and content
3. And resources/js/components/FolderForm.vue is renamed to DeclarationForm.vue with updated internal references
4. And resources/js/components/folders/MessageBubble.vue is moved to resources/js/components/declarations/MessageBubble.vue
5. And resources/js/components/clients/FolderCalendar.vue is renamed to DeclarationCalendar.vue
6. And all inline TypeScript type definitions type Folder = { ... } are renamed to type Declaration = { ... } across all component files
7. And all Inertia render paths in PHP controllers are updated from 'folders/...' to 'declarations/...'
8. And all Inertia prop names passed from PHP controllers are updated ('folders' → 'declarations', 'folder' → 'declaration', 'folderTypeLabels' → 'declarationTypeLabels', etc.)
9. And all Wayfinder route references are updated from folder routes to declaration routes (regenerated via php artisan wayfinder:generate)
10. And all user-facing labels and text display "Declaration" / "Declarations" (French: "Déclaration" / "Déclarations")
11. And the client portal pages (client/Upload.vue, client/Confirm.vue, client/Refuse.vue) reference "declaration" instead of "folder"
12. And navigation components (AppSidebar.vue, AppHeader.vue) use "declarations" terminology
13. And NotificationDropdown.vue references "declaration" instead of "folder"
14. And Dashboard.vue uses "declaration" prop names and variables (assignedDeclarations, declarationsUrl)
15. And clients/Show.vue and workspaces/Show.vue use "declaration" references
16. And the application compiles without TypeScript errors (npm run build)
17. And all pages render correctly with no broken links or references
18. And all existing Pest tests pass (composer test)

Tasks / Subtasks

• Task 1: Update Inertia Render Paths in PHP Controllers (AC: #7, #8)

  • 1.1: DeclarationController.php — change Inertia::render('folders/Index', ...) → 'declarations/Index'; change 'folders/Create' → 'declarations/Create'; change 'folders/Show' → 'declarations/Show'; change 'folders/Edit' → 'declarations/Edit'
  • 1.2: DeclarationController.php — rename all prop keys: 'folders' → 'declarations', 'folder' → 'declaration', 'folderTypeLabels' → 'declarationTypeLabels', 'folderStatusLabels' → 'declarationStatusLabels', 'folderPriorityLabels' → 'declarationPriorityLabels'
  • 1.3: DashboardController.php — rename prop keys: 'assignedFolders' → 'assignedDeclarations', 'foldersUrl' → 'declarationsUrl'
  • 1.4: Client/UploadController.php, Client/ConfirmController.php, Client/RefuseController.php — rename any remaining 'folder' prop keys to 'declaration'

• Task 2: Rename Vue Page Directory (AC: #1, #2)

  • 2.1: git mv resources/js/pages/folders/ resources/js/pages/declarations/
  • 2.2: Update resources/js/pages/declarations/Index.vue — rename all folder/Folder variable names, prop names, types to declaration/Declaration
  • 2.3: Update resources/js/pages/declarations/Show.vue — rename all folder references to declaration (this is the largest page at 696 lines, be thorough)
  • 2.4: Update resources/js/pages/declarations/Create.vue — rename all folder references to declaration
  • 2.5: Update resources/js/pages/declarations/Edit.vue — rename all folder references to declaration

• Task 3: Rename Vue Components (AC: #3, #4, #5)

  • 3.1: git mv resources/js/components/FolderForm.vue resources/js/components/DeclarationForm.vue — rename internal types, props, variable names, emit events
  • 3.2: git mv resources/js/components/folders/ resources/js/components/declarations/ — rename directory
  • 3.3: Update resources/js/components/declarations/MessageBubble.vue — rename any folder references to declaration
  • 3.4: git mv resources/js/components/clients/FolderCalendar.vue resources/js/components/clients/DeclarationCalendar.vue — rename internal references

• Task 4: Update Referencing Pages (AC: #11, #14, #15)

  • 4.1: Update resources/js/pages/Dashboard.vue — rename assignedFolders → assignedDeclarations, foldersUrl → declarationsUrl, all folder type/variable references, labels (e.g., "Dossiers" → "Déclarations"), import paths
  • 4.2: Update resources/js/pages/clients/Show.vue — rename folder references, import paths for FolderForm/FolderCalendar components
  • 4.3: Update resources/js/pages/workspaces/Show.vue — rename folder count references
  • 4.4: Update resources/js/pages/client/Upload.vue — rename folder references to declaration in props, variables, user-facing text
  • 4.5: Update resources/js/pages/client/Confirm.vue — rename folder references
  • 4.6: Update resources/js/pages/client/Refuse.vue — rename folder references

• Task 5: Update Navigation Components (AC: #12, #13)

  • 5.1: Update resources/js/components/AppSidebar.vue — rename "Dossiers"/"Folders" nav label to "Déclarations"/"Declarations", update route imports
  • 5.2: Update resources/js/components/AppHeader.vue — no folder references found, no changes needed
  • 5.3: Update resources/js/components/NotificationDropdown.vue — rename folder references in notification rendering

• Task 6: Regenerate Wayfinder Routes (AC: #9)

  • 6.1: Run docker compose exec laravel.test php artisan wayfinder:generate — this will regenerate resources/js/routes/ based on renamed controllers/routes
  • 6.2: Verify resources/js/routes/declarations/ directory is created (replaces folders/)
  • 6.3: Delete old resources/js/routes/folders/ directory if Wayfinder doesn't clean it up automatically
  • 6.4: Update resources/js/routes/index.ts if it still imports from folders/ (Wayfinder should handle this)
  • 6.5: Update all Vue files that import from @/routes/folders/ to import from @/routes/declarations/

• Task 7: Update User-Facing Text and Labels (AC: #10)

  • 7.1: Search all .vue files for "Dossier", "dossier", "Folder", "folder" in user-facing text (not variable names)
  • 7.2: Replace with "Déclaration" / "déclaration" / "Declaration" / "declaration" as appropriate
  • 7.3: Update page titles in <Head title="..." /> components
  • 7.4: Update breadcrumb labels
  • 7.5: Update empty state messages, button labels, confirmation dialogs
  • 7.6: Update any tooltip text or aria labels

• Task 8: TypeScript Type Renames (AC: #6)

  • 8.1: Search all .vue and .ts files for type Folder inline type definitions
  • 8.2: Rename to type Declaration with updated property names where applicable
  • 8.3: Rename all typed variables: folder: Folder → declaration: Declaration, folders: Folder[] → declarations: Declaration[]
  • 8.4: Update defineProps<{ ... }>() type definitions in all affected components

• Task 9: Build Verification and Testing (AC: #16, #17, #18)

  • 9.1: Run npm run build — verify zero TypeScript compilation errors
  • 9.2: Run npm run lint — 60 pre-existing errors, zero introduced by this story
  • 9.3: Run npm run format — Prettier formatting applied
  • 9.4: Run composer test — 78 tests passed (222 assertions)
  • 9.5: Run composer lint — 137 PHP files passed

Dev Notes

Critical Architecture Constraints

• Docker Compose: Everything runs under Docker — use docker compose exec laravel.test prefix for artisan/composer commands, docker compose exec laravel.test npm for npm commands
• Inertia.js 2.0: Render paths are case-sensitive and map directly to Vue file paths under resources/js/pages/. When we rename folders/ → declarations/, the render path MUST change from 'folders/Index' to 'declarations/Index'
• Laravel Wayfinder 0.1.9: Auto-generates TypeScript route helpers from PHP routes. After Story 0.2 renamed routes from folders.* to declarations.*, Wayfinder will generate new route files under resources/js/routes/declarations/. The old resources/js/routes/folders/ directory must be deleted
• No centralized Folder types: The codebase uses inline type Folder = { ... } definitions within individual Vue components — there is no shared type file in resources/js/types/. Rename each inline type individually
• shadcn-vue components: NEVER modify files in resources/js/components/ui/ — these are auto-generated
• URL props pattern: All URLs come from PHP controllers via Inertia props — never hardcode routes in Vue. The route helper references (route('declarations.show', ...)) are in PHP only
• TypeScript strict mode: isolatedModules: true — use import type { ... } for type-only imports
• No frontend tests: There are no JavaScript/Vue tests. Verification is via TypeScript compilation (npm run build) and manual rendering

Rename Order of Operations

Order matters to avoid broken imports during the rename process:

1. PHP controller prop names + render paths first (backend changes, no frontend dependency)
2. Vue page directory rename (git mv, then update internal content)
3. Vue component renames (FolderForm, folders/MessageBubble, clients/FolderCalendar)
4. Referencing pages (Dashboard, clients/Show, workspaces/Show, client portal pages)
5. Navigation components (AppSidebar, AppHeader, NotificationDropdown)
6. Wayfinder route regeneration (depends on backend routes being correct)
7. User-facing text (final sweep for any remaining "folder"/"dossier" text)
8. Type renames (can be done alongside steps 2-5, listed separately for verification)
9. Build + test verification (last step, catches any missed references)

File Rename Mapping (Complete)

Old Path	New Path
resources/js/pages/folders/	resources/js/pages/declarations/
resources/js/pages/folders/Index.vue	resources/js/pages/declarations/Index.vue
resources/js/pages/folders/Show.vue	resources/js/pages/declarations/Show.vue
resources/js/pages/folders/Create.vue	resources/js/pages/declarations/Create.vue
resources/js/pages/folders/Edit.vue	resources/js/pages/declarations/Edit.vue
resources/js/components/FolderForm.vue	resources/js/components/DeclarationForm.vue
resources/js/components/folders/	resources/js/components/declarations/
resources/js/components/folders/MessageBubble.vue	resources/js/components/declarations/MessageBubble.vue
resources/js/components/clients/FolderCalendar.vue	resources/js/components/clients/DeclarationCalendar.vue

Variable and Prop Rename Patterns

PHP Controller Prop Keys (Inertia props):

Old Prop Key	New Prop Key	Controller(s)
'folders'	'declarations'	DeclarationController@index
'folder'	'declaration'	DeclarationController@show, @edit
'folderTypeLabels'	'declarationTypeLabels'	DeclarationController@create, @edit
'folderStatusLabels'	'declarationStatusLabels'	DeclarationController@create, @edit
'folderPriorityLabels'	'declarationPriorityLabels'	DeclarationController@create, @edit
'assignedFolders'	'assignedDeclarations'	DashboardController
'foldersUrl'	'declarationsUrl'	DashboardController

Vue/TypeScript Variables:

Old Pattern	New Pattern
type Folder = { ... }	type Declaration = { ... }
folders: Folder[]	declarations: Declaration[]
folder: Folder	declaration: Declaration
const folder = ...	const declaration = ...
props.folders	props.declarations
props.folder	props.declaration
props.folderTypeLabels	props.declarationTypeLabels
props.folderStatusLabels	props.declarationStatusLabels
props.folderPriorityLabels	props.declarationPriorityLabels
props.assignedFolders	props.assignedDeclarations
props.foldersUrl	props.declarationsUrl
'createFolderUrl'	'createDeclarationUrl'

Import Paths:

Old Import	New Import
import FolderForm from '@/components/FolderForm.vue'	import DeclarationForm from '@/components/DeclarationForm.vue'
import MessageBubble from '@/components/folders/MessageBubble.vue'	import MessageBubble from '@/components/declarations/MessageBubble.vue'
import FolderCalendar from '@/components/clients/FolderCalendar.vue'	import DeclarationCalendar from '@/components/clients/DeclarationCalendar.vue'
from '@/routes/folders'	from '@/routes/declarations'

User-Facing Text:

Old Text (FR)	New Text (FR)
Dossier / Dossiers	Déclaration / Déclarations
Nouveau dossier	Nouvelle déclaration
Créer un dossier	Créer une déclaration
Modifier le dossier	Modifier la déclaration
Supprimer le dossier	Supprimer la déclaration

Inertia Render Path Changes (PHP)

These changes are in DeclarationController.php:

// BEFORE (Story 0.2 state)
return Inertia::render('folders/Index', ['folders' => $declarations, ...]);
return Inertia::render('folders/Create', ['folderTypeLabels' => ...]);
return Inertia::render('folders/Show', ['folder' => [...], ...]);
return Inertia::render('folders/Edit', ['folder' => [...], 'folderTypeLabels' => ...]);

// AFTER (Story 0.3)
return Inertia::render('declarations/Index', ['declarations' => $declarations, ...]);
return Inertia::render('declarations/Create', ['declarationTypeLabels' => ...]);
return Inertia::render('declarations/Show', ['declaration' => [...], ...]);
return Inertia::render('declarations/Edit', ['declaration' => [...], 'declarationTypeLabels' => ...]);

Wayfinder Route Regeneration

After Story 0.2 renamed PHP routes from folders.* to declarations.*, Wayfinder needs regeneration:

1. Run: docker compose exec laravel.test php artisan wayfinder:generate
2. This generates new resources/js/routes/declarations/index.ts (and nested messages/, media/, mentions/)
3. The old resources/js/routes/folders/ directory will NOT be auto-deleted — must be manually removed
4. The @see comments in generated files will now reference DeclarationController, DeclarationMediaController, etc.
5. All Vue files importing from @/routes/folders must update to @/routes/declarations

Previous Story Intelligence (Story 0.2)

Key learnings that apply to this story:

• git mv for renames: Use git mv to preserve file history
• Scope discipline: Story 0.2 noted cosmetic changes (EOF newlines, import reordering) as undisciplined scope — avoid making changes outside story scope
• Frontend props intentionally left: Story 0.2 completion notes explicitly state: "Frontend prop names (createFolderUrl, assignedFolders, 'folder', 'folders') intentionally kept unchanged — will be renamed in Story 0.3" and "Inertia render paths ('folders/Index', 'folders/Show', etc.) intentionally kept unchanged — frontend Vue files not yet renamed"
• Docker commands: All artisan/npm commands via docker compose exec laravel.test
• Testing: Use composer test which clears config, runs Pint lint check, then php artisan test
• PHP 8.4: Already configured in compose.yaml

Warning: Build Will Fail Until Both PHP + Vue Sides Are Updated

The Inertia render paths and prop names must match between PHP controllers and Vue components. During the rename process:

• If you rename PHP render paths first (e.g., 'declarations/Index') but haven't moved the Vue file yet, the page will 500
• If you rename Vue files first but PHP still renders to 'folders/Index', the page will 500
• Recommended approach: Do both sides per-page (e.g., update DeclarationController@index render path + move/update Index.vue together) OR accept temporary breakage and do all changes in sequence

Files Requiring Changes (Complete List)

PHP Controllers (prop keys + render paths):

• app/Http/Controllers/DeclarationController.php (4 render paths + 8+ prop keys)
• app/Http/Controllers/DashboardController.php (2 prop keys)
• app/Http/Controllers/Client/UploadController.php (check for folder props)
• app/Http/Controllers/Client/ConfirmController.php (check for folder props)
• app/Http/Controllers/Client/RefuseController.php (check for folder props)

Vue Pages (rename directory + update content):

• resources/js/pages/folders/Index.vue → declarations/Index.vue
• resources/js/pages/folders/Show.vue → declarations/Show.vue (696 lines — largest file)
• resources/js/pages/folders/Create.vue → declarations/Create.vue
• resources/js/pages/folders/Edit.vue → declarations/Edit.vue

Vue Components (rename + update content):

• resources/js/components/FolderForm.vue → DeclarationForm.vue (309 lines)
• resources/js/components/folders/MessageBubble.vue → declarations/MessageBubble.vue
• resources/js/components/clients/FolderCalendar.vue → DeclarationCalendar.vue

Vue Pages (update references only):

• resources/js/pages/Dashboard.vue (393 lines)
• resources/js/pages/clients/Show.vue (513 lines)
• resources/js/pages/workspaces/Show.vue (204 lines)
• resources/js/pages/client/Upload.vue (157 lines)
• resources/js/pages/client/Confirm.vue (75 lines)
• resources/js/pages/client/Refuse.vue (74 lines)

Vue Components (update references only):

• resources/js/components/AppSidebar.vue (105 lines)
• resources/js/components/AppHeader.vue (283 lines)
• resources/js/components/NotificationDropdown.vue (146 lines)

Wayfinder Routes (regenerate + cleanup):

• resources/js/routes/folders/ → delete after regeneration
• resources/js/routes/declarations/ → auto-generated
• resources/js/routes/index.ts → auto-updated

Testing Standards

• Use Pest syntax (test() closures), never PHPUnit class-based tests
• RefreshDatabase is auto-applied via Pest.php — don't add manually
• Run tests: composer test (clears config, runs Pint, runs tests)
• No frontend JS tests exist — verification via npm run build (TypeScript compilation)
• After rename, run npm run lint and npm run format for frontend code quality
• After rename, run composer lint for PHP code quality (controller changes)

Project Structure Notes

• All file renames should use git mv to preserve history
• Vue page directories are lowercase by convention: declarations/ not Declarations/
• Component files are PascalCase: DeclarationForm.vue, MessageBubble.vue
• Inertia render paths use lowercase subdirectory: 'declarations/Index', not 'Declarations/Index'

References

• [Source: _bmad-output/planning-artifacts/epics.md#Story 0.3]
• [Source: _bmad-output/planning-artifacts/architecture.md#Pre-Phase Migration]
• [Source: _bmad-output/planning-artifacts/architecture.md#Frontend Architecture]
• [Source: _bmad-output/project-context.md#Technology Stack]
• [Source: _bmad-output/project-context.md#Framework-Specific Rules]
• [Source: _bmad-output/implementation-artifacts/0-2-rename-folders-to-declarations-in-backend.md]
• [Source: app/Http/Controllers/DeclarationController.php (lines 91, 106, 210, 264)]
• [Source: app/Http/Controllers/DashboardController.php (lines 119, 122)]
• [Source: resources/js/pages/folders/ (4 Vue page files)]
• [Source: resources/js/components/FolderForm.vue]
• [Source: resources/js/components/folders/MessageBubble.vue]
• [Source: resources/js/components/clients/FolderCalendar.vue]
• [Source: resources/js/routes/folders/ (4 Wayfinder route files)]

Dev Agent Record

Agent Model Used

Claude Opus 4.6 (claude-opus-4-6)

Debug Log References

None — no debugging required.

Completion Notes List

• All 9 tasks completed successfully across ~25+ files
• PHP controllers: 4 render paths + all prop keys renamed in DeclarationController, DashboardController, ClientController, WorkspaceController, and 3 client portal controllers
• Vue pages: folders/ directory renamed to declarations/, all 4 page components fully updated
• Vue components: FolderForm → DeclarationForm, folders/MessageBubble → declarations/MessageBubble, clients/FolderCalendar → DeclarationCalendar
• Referencing pages: Dashboard, clients/Show, workspaces/Show, client/Upload, client/Confirm, client/Refuse all updated
• Navigation: AppSidebar updated (icon changed to FileStack, label to "Déclarations", href to /declarations), NotificationDropdown updated
• AppHeader.vue: No folder references found, no changes needed
• Wayfinder routes regenerated — new declarations/ routes created, old folders/ directory deleted
• Welcome.vue: user-facing text updated ("dossiers fiscaux" → "déclarations fiscales")
• All inline TypeScript types renamed from Folder to Declaration across all affected components
• npm run build: zero TypeScript errors
• npm run lint: 60 pre-existing errors (vue/no-mutating-props, unused imports) — none introduced by this story
• npm run format: completed successfully
• composer test: 78 tests passed (222 assertions)
• composer lint: 137 PHP files passed
• All file renames done via git mv to preserve history

Change Log

Change	Files	Reason
Inertia render paths folders/* → declarations/*	DeclarationController.php	AC #7
Inertia prop keys renamed (folder→declaration, folders→declarations, etc.)	DeclarationController, DashboardController, ClientController, WorkspaceController, UploadController, ConfirmController, RefuseController	AC #8
Vue page directory renamed	resources/js/pages/folders/ → declarations/	AC #1
Vue page content updated	Index.vue, Show.vue, Create.vue, Edit.vue	AC #2, #6
FolderForm → DeclarationForm	resources/js/components/DeclarationForm.vue	AC #3
folders/MessageBubble → declarations/MessageBubble	resources/js/components/declarations/MessageBubble.vue	AC #4
FolderCalendar → DeclarationCalendar	resources/js/components/clients/DeclarationCalendar.vue	AC #5
Dashboard updated	resources/js/pages/Dashboard.vue	AC #14
clients/Show updated	resources/js/pages/clients/Show.vue	AC #15
workspaces/Show updated	resources/js/pages/workspaces/Show.vue	AC #15
Client portal pages updated	Upload.vue, Confirm.vue, Refuse.vue	AC #11
AppSidebar updated	resources/js/components/AppSidebar.vue	AC #12
NotificationDropdown updated	resources/js/components/NotificationDropdown.vue	AC #13
Wayfinder routes regenerated	resources/js/routes/declarations/	AC #9
User-facing text updated	All affected .vue files, Welcome.vue	AC #10
[Review] Fixed missed "dossiers" → "déclarations"	ClientForm.vue:242	AC #10
[Review] Reverted 25 cosmetic-only files (Prettier noise)	Various .vue, app.css	Scope cleanup

File List

PHP Controllers (modified):

• app/Http/Controllers/DeclarationController.php
• app/Http/Controllers/DashboardController.php
• app/Http/Controllers/ClientController.php
• app/Http/Controllers/WorkspaceController.php
• app/Http/Controllers/Client/UploadController.php
• app/Http/Controllers/Client/ConfirmController.php
• app/Http/Controllers/Client/RefuseController.php

Vue Pages (renamed + modified):

• resources/js/pages/declarations/Index.vue (was folders/Index.vue)
• resources/js/pages/declarations/Show.vue (was folders/Show.vue)
• resources/js/pages/declarations/Create.vue (was folders/Create.vue)
• resources/js/pages/declarations/Edit.vue (was folders/Edit.vue)

Vue Pages (modified only):

• resources/js/pages/Dashboard.vue
• resources/js/pages/Welcome.vue
• resources/js/pages/clients/Show.vue
• resources/js/pages/workspaces/Show.vue
• resources/js/pages/client/Upload.vue
• resources/js/pages/client/Confirm.vue
• resources/js/pages/client/Refuse.vue

Vue Components (renamed + modified):

• resources/js/components/DeclarationForm.vue (was FolderForm.vue)
• resources/js/components/declarations/MessageBubble.vue (was folders/MessageBubble.vue)
• resources/js/components/clients/DeclarationCalendar.vue (was clients/FolderCalendar.vue)

Vue Components (modified only):

• resources/js/components/AppSidebar.vue
• resources/js/components/NotificationDropdown.vue
• resources/js/components/ClientForm.vue

Wayfinder Routes (regenerated):

• resources/js/routes/declarations/ (new, replaces folders/)
• resources/js/routes/index.ts (auto-updated)