refactor: streamline docblocks for improved clarity and consistency

Author: ManukMinasyan

app-modules/ImportWizard/src/Livewire/Concerns/HasColumnMapping.php

@@ -9,19 +9,10 @@
 use Livewire\Attributes\Computed;
 use Relaticle\ImportWizard\Filament\Imports\BaseImporter;
 
-/**
- * Provides column mapping functionality for the Import Wizard.
- *
- * @property array<\Filament\Actions\Imports\ImportColumn> $importerColumns
- */
+/** @property array<\Filament\Actions\Imports\ImportColumn> $importerColumns */
 trait HasColumnMapping
 {
-    /**
-     * Get importer columns for the selected entity type.
-     * This is a computed property to avoid storing complex objects in Livewire state.
-     *
-     * @return array<ImportColumn>
-     */
+    /** @return array<ImportColumn> */
     #[Computed]
     public function importerColumns(): array
     {
@@ -33,9 +24,6 @@ public function importerColumns(): array
         return $importerClass::getColumns();
     }
 
-    /**
-     * Auto-map CSV columns to importer columns based on guesses.
-     */
     protected function autoMapColumns(): void
     {
         if ($this->csvHeaders === [] || $this->importerColumns === []) {
@@ -56,31 +44,21 @@ protected function autoMapColumns(): void
             ->toArray();
     }
 
-    /**
-     * Get the importer class for the selected entity type.
-     *
-     * @return class-string<BaseImporter>|null
-     */
+    /** @return class-string<BaseImporter>|null */
     protected function getImporterClass(): ?string
     {
         $entities = $this->getEntities();
 
         return $entities[$this->entityType]['importer'] ?? null;
     }
 
-    /**
-     * Check if all required columns are mapped.
-     */
     public function hasAllRequiredMappings(): bool
     {
         return collect($this->importerColumns)
             ->filter(fn (ImportColumn $column): bool => $column->isMappingRequired())
             ->every(fn (ImportColumn $column): bool => ($this->columnMap[$column->getName()] ?? '') !== '');
     }
 
-    /**
-     * Map a CSV column to a field, or unmap if fieldName is empty.
-     */
     public function mapCsvColumnToField(string $csvColumn, string $fieldName): void
     {
         // First, find and clear any existing mapping for this CSV column
@@ -96,19 +74,13 @@ public function mapCsvColumnToField(string $csvColumn, string $fieldName): void
         }
     }
 
-    /**
-     * Unmap a column.
-     */
     public function unmapColumn(string $fieldName): void
     {
         if (isset($this->columnMap[$fieldName])) {
             $this->columnMap[$fieldName] = '';
         }
     }
 
-    /**
-     * Get the label for a field name.
-     */
     public function getFieldLabel(string $fieldName): string
     {
         $column = collect($this->importerColumns)
@@ -117,9 +89,6 @@ public function getFieldLabel(string $fieldName): string
         return $column?->getLabel() ?? Str::title(str_replace('_', ' ', $fieldName));
     }
 
-    /**
-     * Check if any unique identifier column is mapped.
-     */
     protected function hasUniqueIdentifierMapped(): bool
     {
         $importerClass = $this->getImporterClass();
@@ -144,9 +113,6 @@ protected function hasUniqueIdentifierMapped(): bool
         return false;
     }
 
-    /**
-     * Get the user-friendly message for missing unique identifiers.
-     */
     protected function getMissingUniqueIdentifiersMessage(): string
     {
         $importerClass = $this->getImporterClass();

app-modules/ImportWizard/src/Livewire/Concerns/HasCsvParsing.php

@@ -11,14 +11,8 @@
 use Livewire\Features\SupportFileUploads\TemporaryUploadedFile;
 use Relaticle\ImportWizard\Services\CsvReaderFactory;
 
-/**
- * Provides CSV file parsing functionality for the Import Wizard.
- */
 trait HasCsvParsing
 {
-    /**
-     * Parse the uploaded file and extract headers and row count.
-     */
     protected function parseUploadedFile(): void
     {
         if ($this->uploadedFile === null) {
@@ -68,9 +62,6 @@ protected function parseUploadedFile(): void
         }
     }
 
-    /**
-     * Persist the uploaded CSV file to storage in a session folder.
-     */
     protected function persistFile(TemporaryUploadedFile $file): ?string
     {
         try {
@@ -96,9 +87,6 @@ protected function persistFile(TemporaryUploadedFile $file): ?string
         }
     }
 
-    /**
-     * Clean up temporary session folder and cache keys.
-     */
     protected function cleanupTempFile(): void
     {
         if ($this->sessionId === null) {
@@ -115,11 +103,7 @@ protected function cleanupTempFile(): void
         Cache::forget("import:{$this->sessionId}:team");
     }
 
-    /**
-     * Get preview values for a specific CSV column.
-     *
-     * @return array<int, string>
-     */
+    /** @return array<int, string> */
     public function getColumnPreviewValues(string $csvColumn, int $limit = 5): array
     {
         if ($this->persistedFilePath === null) {

app-modules/ImportWizard/src/Livewire/Concerns/HasImportPreview.php

@@ -15,25 +15,11 @@
 use Relaticle\ImportWizard\Services\ImportRecordResolver;
 use Relaticle\ImportWizard\Services\PreviewChunkService;
 
-/**
- * Provides import preview functionality for the Import Wizard's Preview step.
- *
- * Uses a hybrid approach:
- * - First batch processed synchronously for instant feedback
- * - Remaining rows processed in background job
- * - Progress tracked via Cache
- *
- * @property ImportPreviewResult|null $previewResult
- */
+/** @property ImportPreviewResult|null $previewResult */
 trait HasImportPreview
 {
     private const int INITIAL_BATCH_SIZE = 50;
 
-    /**
-     * Generate a preview of what the import will do.
-     *
-     * Processes first batch synchronously, then dispatches background job for the rest.
-     */
     protected function generateImportPreview(): void
     {
         $importerClass = $this->getImporterClass();
@@ -145,11 +131,7 @@ protected function generateImportPreview(): void
         }
     }
 
-    /**
-     * Write the initial enriched CSV with header and first batch.
-     *
-     * @param  array<int, array<string, mixed>>  $rows
-     */
+    /** @param array<int, array<string, mixed>> $rows */
     private function writeInitialEnrichedCsv(string $path, array $rows, PreviewChunkService $service): void
     {
         $writer = Writer::createFromPath($path, 'w');
@@ -161,9 +143,6 @@ private function writeInitialEnrichedCsv(string $path, array $rows, PreviewChunk
         }
     }
 
-    /**
-     * Set preview progress in cache.
-     */
     private function setPreviewProgress(int $processed, int $creates, int $updates): void
     {
         Cache::put(
@@ -178,9 +157,6 @@ private function setPreviewProgress(int $processed, int $creates, int $updates):
         );
     }
 
-    /**
-     * Get the preview processing status.
-     */
     public function getPreviewStatus(): string
     {
         if ($this->sessionId === null) {
@@ -190,11 +166,7 @@ public function getPreviewStatus(): string
         return Cache::get("import:{$this->sessionId}:status", 'pending');
     }
 
-    /**
-     * Get the preview processing progress.
-     *
-     * @return array{processed: int, creates: int, updates: int, total: int}
-     */
+    /** @return array{processed: int, creates: int, updates: int, total: int} */
     public function getPreviewProgress(): array
     {
         if ($this->sessionId === null) {
@@ -214,17 +186,11 @@ public function getPreviewProgress(): array
         ]);
     }
 
-    /**
-     * Check if preview processing is complete.
-     */
     public function isPreviewReady(): bool
     {
         return $this->getPreviewStatus() === 'ready';
     }
 
-    /**
-     * Get preview result as DTO (computed from stored array data).
-     */
     #[Computed]
     public function previewResult(): ?ImportPreviewResult
     {
@@ -240,27 +206,18 @@ public function previewResult(): ?ImportPreviewResult
         return ImportPreviewResult::from($this->previewResultData);
     }
 
-    /**
-     * Check if the preview indicates any records will be imported.
-     */
     public function hasRecordsToImport(): bool
     {
         return ($this->previewResultData['totalRows'] ?? 0) > 0;
     }
 
-    /**
-     * Get the count of new records to be created.
-     */
     public function getCreateCount(): int
     {
         $progress = $this->getPreviewProgress();
 
         return $progress['creates'];
     }
 
-    /**
-     * Get the count of existing records to be updated.
-     */
     public function getUpdateCount(): int
     {
         $progress = $this->getPreviewProgress();