feat(media-folder-pro): add virtual folder system for WordPress media library

Custom WordPress plugin that replaces the default flat media library with a structured folder view. Features: hierarchical folders via custom taxonomy, sidebar folder tree, drag & drop, modal integration with Elementor/builders, bulk assign, upload auto-assign, toast notifications. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 14:08:49 +01:00
parent 4ad3303b18
commit 5014b9108f
19 changed files with 3692 additions and 0 deletions
--- a/.paul/phases/03-media-modal/03-01-PLAN.md
+++ b/.paul/phases/03-media-modal/03-01-PLAN.md
@@ -0,0 +1,211 @@
+---
+phase: 03-media-modal
+plan: 01
+type: execute
+wave: 1
+depends_on: ["02-01"]
+files_modified:
+  - wp-content/plugins/media-folder-pro/assets/js/modal-integration.js
+  - wp-content/plugins/media-folder-pro/assets/css/admin.css
+  - wp-content/plugins/media-folder-pro/media-folder-pro.php
+  - wp-content/plugins/media-folder-pro/includes/class-ajax-handler.php
+autonomous: true
+---
+
+<objective>
+## Goal
+Zintegrowac drzewko folderow z modalem WP media (wp.media modal) — tym samym, ktory otwiera sie w edytorze blokowym, klasycznym edytorze, Elementorze i innych pluginach uzywajacych wp.media. Uzytkownik moze filtrowac media po folderze wewnatrz modala oraz przypisac folder podczas uploadu.
+
+## Purpose
+Modal mediow to glowny punkt interakcji z biblioteka — bez integracji uzytkownik nie moze korzystac z folderow podczas wstawiania mediow do tresci.
+
+## Output
+- Dropdown/sidebar z folderami wewnatrz modala media
+- Filtrowanie mediow w modalu po wybranym folderze
+- Mozliwosc wyboru folderu docelowego przy uploadzie nowych plikow
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+
+## Prior Work
+@.paul/phases/02-media-library-grid/02-01-SUMMARY.md
+- MFP_Media_Query z filtrem ajax_query_attachments_args (juz dziala dla modala tez!)
+- mfp_assign_media endpoint gotowy
+- media-filter.js z wzorcem library.props.set({media_folder: id})
+
+## Source Files
+@wp-content/plugins/media-folder-pro/media-folder-pro.php
+@wp-content/plugins/media-folder-pro/assets/js/media-filter.js
+@wp-content/plugins/media-folder-pro/includes/class-media-query.php
+@wp-content/plugins/media-folder-pro/includes/class-ajax-handler.php
+@wp-content/plugins/media-folder-pro/assets/css/admin.css
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Dropdown folderow widoczny w modalu media
+```gherkin
+Given plugin aktywny, istnieja foldery
+When uzytkownik otwiera modal media (np. "Dodaj media" w edytorze)
+Then w pasku narzedzi modala widoczny jest dropdown z lista folderow
+And dropdown zawiera opcje "Wszystkie media" + lista folderow hierarchicznie
+```
+
+## AC-2: Filtrowanie mediow w modalu po folderze
+```gherkin
+Given modal media otwarty, istnieja foldery z mediami
+When uzytkownik wybiera folder z dropdown
+Then grid mediow w modalu pokazuje tylko media z wybranego folderu
+And wybranie "Wszystkie media" przywraca pelna liste
+```
+
+## AC-3: Przypisanie folderu przy uploadzie
+```gherkin
+Given modal media otwarty, wybrany folder "Zdjecia produktow"
+When uzytkownik uploaduje nowy plik przez zakladke "Wyslij pliki"
+Then nowo uploadowany plik zostaje automatycznie przypisany do aktywnego folderu
+And plik pojawia sie w filtrowanym widoku tego folderu
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Modal folder dropdown + filtering</name>
+  <files>wp-content/plugins/media-folder-pro/assets/js/modal-integration.js, wp-content/plugins/media-folder-pro/assets/css/admin.css, wp-content/plugins/media-folder-pro/media-folder-pro.php</files>
+  <action>
+    1. Utworzyc assets/js/modal-integration.js:
+       - Hook na wp.media.view.AttachmentsBrowser:
+         - Nadpisz (extend) domyslny AttachmentsBrowser
+         - W metodzie createToolbar() dodaj customowy dropdown filter
+       - Dropdown budowany z danych folderow (AJAX mfp_get_folders przy otwarciu)
+       - Opcje: "Wszystkie media" (value=0) + foldery z wciecia dla hierarchii
+         - Np: "Zdjecia", "— Produkty", "— — Elektronika" (hierarchia przez prefiks)
+       - Przy zmianie dropdown:
+         - library.props.set({media_folder: selectedFolderId})
+         - To uzyje istniejacego MFP_Media_Query filtra server-side
+       - Przechowuj aktywny folder w zmiennej modulu (potrzebne dla upload)
+
+    2. Hook na wp.media.view.UploaderInline (upload tab):
+       - Po uplywie uploadu (wp.Uploader 'upload-success' lub 'wp-upload-complete'):
+         - Jesli aktywny folder > 0:
+           - Wywolaj AJAX mfp_assign_media z nowym attachment_id i aktywnym folderem
+       - Alternatywnie: hook na wp.media.model.Attachment po dodaniu do kolekcji
+
+    3. Podejscie do hookowania WP media views:
+       - Uzyj wp.media.view.AttachmentsBrowser.extend() do nadpisania createToolbar
+       - LUB: uzyj filtra 'AttachmentsBrowser:ready' jesli dostepny
+       - LUB: monkey-patch wp.media.view.AttachmentsBrowser.prototype.createToolbar
+       - Wybierz podejscie ktore NIE wymaga modyfikacji core WP JS
+       - Najstabilniejszy pattern: nadpisz prototype.createToolbar, wywolaj original,
+         potem dodaj swoj element do this.toolbar
+
+    4. W admin.css dodac style dla:
+       - .mfp-modal-filter — select dropdown w toolbarze modala
+       - Styl opcji z wciecia (hierarchia folderow)
+       - Dopasowanie do domyslnego stylu WP media toolbar
+
+    5. W media-folder-pro.php:
+       - Enqueue modal-integration.js globalnie w admin (nie tylko upload.php)
+         bo modal moze byc otwarty z dowolnej strony admina
+       - Dependency: ['media-views']
+       - Warunek: enqueue tylko jesli wp_script_is('media-views', 'enqueued')
+         lub laduj z wp_enqueue_media hook
+
+    Avoid: Nie modyfikowac core WP JS — tylko extend/override prototypow.
+    Avoid: Nie ladowac pelnego folder-tree.js w modalu — uzyj lekkiego dropdown.
+    Avoid: Nie uzywac jQuery UI — czysty select element lub custom dropdown.
+  </action>
+  <verify>
+    - Otwarcie modala media w edytorze pokazuje dropdown folderow
+    - Wybranie folderu filtruje media w modalu
+    - Upload pliku z aktywnym folderem przypisuje go do folderu
+    - Modal dziala normalnie bez folderow (brak regresji)
+    - Dropdown laduje hierarchie poprawnie (wciety subfoldery)
+  </verify>
+  <done>AC-1 + AC-2 + AC-3 satisfied: modal z dropdown, filtrowanie, upload do folderu</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Auto-assign uploaded media + refresh counters</name>
+  <files>wp-content/plugins/media-folder-pro/includes/class-ajax-handler.php, wp-content/plugins/media-folder-pro/assets/js/modal-integration.js</files>
+  <action>
+    1. W class-ajax-handler.php dodac nowy endpoint mfp_upload_to_folder:
+       - Parametry: attachment_id (int), folder_id (int)
+       - Prostszy niz mfp_assign_media (pojedynczy plik, nie tablica)
+       - wp_set_object_terms($attachment_id, [$folder_id], 'media_folder')
+       - Zwraca: {success: true}
+       - Dodac do tablicy $actions w register_hooks()
+       - Ten endpoint jest dedykowany dla upload flow (szybszy, bez folder_counts)
+
+    2. W modal-integration.js:
+       - Po AJAX uplywie uploadu nowego pliku:
+         - Nasluchuj na wp.Uploader events lub Attachment collection events
+         - Pattern: wp.media.model.Attachments on('add') — nowy attachment dodany
+         - Jesli aktywny folder: wywolaj mfp_upload_to_folder
+       - Po przypisaniu: dispatch 'mfp-folder-changed' event
+         (zeby upload.php folder tree tez sie odswieszyl jesli otwarty)
+
+    3. Synchronizacja z upload.php:
+       - Jesli modal otwarty z upload.php (media library page):
+         - Po zamknieciu modala: dispatch 'mfp-folder-changed'
+         - folder-tree.js nasluchuje i wywoluje refreshTree()
+       - Dodac listener w folder-tree.js na 'mfp-folder-changed'
+
+    Avoid: Nie duplikuj logiki mfp_assign_media — mfp_upload_to_folder to uproszczona wersja.
+    Avoid: Nie refreshuj counterow w modalu (zbyt ciezkie) — tylko po zamknieciu.
+  </action>
+  <verify>
+    - Upload pliku z aktywnym folderem przypisuje automatycznie
+    - Po zamknieciu modala countery folderow na upload.php sa aktualne
+    - Upload bez aktywnego folderu nie przypisuje do zadnego folderu
+    - Brak duplikatow przypisania (jeden upload = jedna operacja)
+  </verify>
+  <done>AC-3 reinforced: upload flow roboczy z auto-assign i sync counterow</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- wp-content/plugins/elementor-pro/* (nie modyfikujemy Elementora)
+- wp-content/plugins/media-folder-pro/includes/class-taxonomy.php (stabilna)
+- wp-content/plugins/media-folder-pro/includes/class-media-query.php (stabilna, juz filtruje modal)
+- Zadne pliki core WordPress
+
+## SCOPE LIMITS
+- Brak drag & drop w modalu (tylko dropdown filter)
+- Brak tworzenia folderow z modala (tylko wybor istniejacych)
+- Brak bulk operations (Phase 4)
+- Elementor-specific hooks NIE sa potrzebne — Elementor uzywa standardowego wp.media
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] Dropdown folderow widoczny w modalu media
+- [ ] Filtrowanie dziala: wybor folderu → tylko media z folderu
+- [ ] "Wszystkie media" przywraca pelna liste
+- [ ] Upload z aktywnym folderem → auto-assign do folderu
+- [ ] Upload bez folderu → brak przypisania (normalne zachowanie)
+- [ ] Po zamknieciu modala → countery na upload.php odswiezone
+- [ ] Modal otwierany z roznych stron (post edit, page edit) dziala
+- [ ] Brak regresji: modal bez folderow dziala normalnie
+- [ ] Brak JS errors w konsoli
+</verification>
+
+<success_criteria>
+- Wszystkie taski ukonczone
+- Wszystkie verification checks przeszly
+- Modal media w pelni zintegrowany z folderami
+- Brak bledow PHP i JS
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/03-media-modal/03-01-SUMMARY.md`
+</output>