=== KooKoa Folders – Media Library Folders & File Organizer ===
Contributors: adamolussana
Tags: folders, media folders, media library, file manager, media
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.4.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Organize the WordPress Media Library with unlimited media folders, subfolders, Smart Folders, and a lightweight file manager.

== Description ==

KooKoa Folders adds a folder sidebar to the WordPress Media Library. You can create folders, nest them into subfolders, and move files around with drag and drop. It also ships with unlimited smart folders that auto-populate from rules you define — file type, size, date, dimensions, tags, and more — so the library stays tidy as it grows.

👉 [**TRY THE LIVE DEMO**](https://demo.kookoa.com/live) ☝️ — Instant access, no account needed

Folders are virtual. They are stored as a private WordPress taxonomy and attached to your media items, so your files on disk are never moved and existing image URLs keep working. If you deactivate the plugin your Media Library keeps running as if nothing happened.

[vimeo https://vimeo.com/1188380254]

= 🗂️ Organization =

* Unlimited folders and subfolders in the Media Library
* Drag and drop attachments between folders
* Auto-assign new uploads to the folder you are currently in
* Item count per folder
* Folder filter on the Media Library list view

= ⚡ Smart Folders =

* Unlimited smart (rule-based) folders, auto-populated as your Media Library grows
* Combine multiple rules per folder with AND logic — file type, size, dimensions, date, author, status, search, tags, and more
* Live counts cached per folder, refreshed automatically when items change
* Pin, lock, color and icon support — same UX as regular folders

= 🌈 Cosmetics =

* Custom folder colors
* Custom folder icons with emoji picker
* Pin folders to the top of the tree
* Lock folders to prevent accidental rename, color, icon or delete

= 🔍 Navigation =

* Resizable, sticky folder sidebar
* Search and sort the folder tree
* Breadcrumb bar and subfolder cards
* Smart Startup Folder — open the Media Library on the last folder you used, or on a fixed folder of your choice
* Keyboard shortcuts for common actions
* Mobile responsive layout

= 🔄 Bulk operations =

* Bulk Organize mode — select multiple attachments and move them into a folder in one click
* Download a folder (and all its subfolders) as a single ZIP archive
* Download just the selected items as a ZIP, straight from the Bulk Organize toolbar
* Upload a folder structure from your computer and have the subfolders recreated automatically
* Export and import the folder structure as JSON, with Merge or Replace modes

= 📊 Insights =

* Hover tooltip on media items showing filename, size and dimensions
* Optional EXIF fields in the hover tooltip — camera, aperture, shutter, ISO, focal length

= 🛡️ Access control =

* Role-based access — pick which WordPress roles can use the folder sidebar

= 🔒 Privacy =

* Self-hosted font, no Google Fonts call
* No external scripts, no trackers, no analytics
* No frontend assets are loaded for regular visitors; builder/editor integrations load only when an authorized editor opens a supported visual builder

= ✅ Works with =

The folder sidebar is available inside:

* The WordPress Media Library list and grid views
* The block editor (Gutenberg) media modal
* The Classic Editor media modal
* Divi 4 and 5 media modals
* Elementor media modal
* WooCommerce product gallery media modal

= 🔁 Migrate from other folder plugins =

Already using another folder plugin? Switch in one click. KooKoa Folders detects existing folder structures directly from your database and rebuilds the full tree inside the KooKoa sidebar — with file assignments intact, no JSON export, no rebuilding from scratch.

Supported sources:

* **FileBird** (Ninja Team)
* **Folders** (Premio)
* **Real Media Library** (devowl.io)

A subtle hint inside the Media Library surfaces the importer when one of these plugins is detected, so you find it without going hunting through Settings. After a successful import, the source plugin can be deactivated with one button — your KooKoa folder structure keeps living independently.

= 🚀🚀🚀 Pro add-on = 

👉 [**TRY THE LIVE DEMO**](https://demo.kookoa.com/live) ☝️

🚀 Folders for Posts & Pages
🚀 Folders for Custom Post Types
🚀 AI Image Generator (text-to-image)
🚀 AI Image Editor (text-guided edits)
🚀 WebP / AVIF Converter
🚀 Replace Media (same name or rename)
🚀 Watermark Images (logo or text)
🚀 Clean Unused Media
🚀 Find Duplicate Media (byte-exact + perceptual hash)
🚀 Image Editor (crop, rotate, filters, resize)
🚀 Media Stats Dashboard
🚀 Priority Email Support

= 💻 Use cases =

A few real-world setups where KooKoa Folders earns its keep:

* **Bloggers and content writers** — keep every blog image, post screenshot, hero photo, video clip and audio file inside dedicated media folders. Drag and drop assets between folders, filter the media library by folder, and find the right image for tomorrow's article in seconds instead of scrolling past 2,000 thumbnails.
* **WordPress photographers and photo studios** — split your media library by shoot type (portraits, weddings, real estate, landscapes, nature, family), by client, by year, or by location. Pin your active project to the top, lock the archive against accidental edits, and let smart folders auto-collect images by date, file size or alt text.
* **WooCommerce shop owners and e-commerce managers** — organize product images into folders that mirror your catalog (apparel, footwear, accessories, electronics). Drag and drop new product photos straight from upload into the right SKU folder, and use smart folders to auto-group every PNG, JPEG or WebP above a certain size for quality audits.
* **Web designers, web developers and freelance agencies** — separate site assets per project, per page section or per client (logos, mockups, illustrations, icon sets, screenshots). Folder colors and custom icons turn the media library into a navigable workspace even when you sit on thousands of files.
* **Online publishers, magazines and editors** — file every image per issue, per article, per author or per topic. Smart folders auto-collect everything uploaded this week, this month, or by a specific contributor — no manual sorting needed.
* **Real estate, hospitality and listings sites** — one folder per property or per location, subfolders per room, view or photoshoot. Bulk upload an entire shoot, drag the keepers into the listing folder, and skip the rest. Color-code your busiest property folders so the right one stands out at a glance.
* **Course creators and membership sites** — split lesson screenshots, video thumbnails and downloadable PDFs into folders per course, per module or per lesson. Find the right cover image without scrolling past fifty unrelated lessons.
* **Marketing agencies, design studios and creative teams** — one WordPress Media Library, many clients. A folder per brand keeps work tidy, role-based access keeps clients out of each other's assets, and the export/import tool ships a folder tree to a new project in a single JSON file.

== Installation ==

1. In your WordPress admin, go to **Plugins → Add New**.
2. Search for **KooKoa Folders**.
3. Click **Install Now**, then **Activate**.
4. Open the **Media Library** — the folder sidebar will appear on the left.
5. Click **+ Folder** in the sidebar header to create your first folder, then drag items into it.

To configure the plugin, go to **KooKoa Folders** in the WordPress admin menu. You can set the default sidebar width, change the color palette and icon set, enable keyboard shortcuts, adjust the context menu, pick which roles can use the plugin, and more.

**Manual installation**

1. Download the plugin zip.
2. Go to **Plugins → Add New → Upload Plugin** and upload the zip.
3. Activate the plugin.

== Frequently Asked Questions ==

= Does KooKoa Folders move files on disk? =

No. Folders are virtual. They are stored as a private WordPress taxonomy and attached to media items. Your files on the server keep their original paths, so existing image URLs in your content never break.

= Will deleting a folder delete my files? =

No. Deleting a folder only removes the folder itself. The media items inside it become uncategorized and stay in the Media Library.

= What happens if I deactivate the plugin? =

Your folders stay in the database. When you reactivate the plugin, everything is back where it was. If instead you use **Delete** from the Plugins screen, all plugin data (folders, colors, icons, pin and lock state, settings) is removed cleanly.

= Does the plugin load anything from the internet? =

No. The font used by the plugin interface is bundled inside the plugin and served from your own site — no Google Fonts CDN, no external scripts, no analytics.

= Does it affect my site frontend or performance? =

The plugin loads on the Media Library, on its own settings page, and inside the media modal — including when an authorized editor opens a supported visual builder such as Divi or Elementor. Regular visitors get nothing extra: no CSS, no JavaScript, no database queries.

= How many smart folders can I create? =

As many as you need. KooKoa Folders ships with unlimited smart folders. Each folder combines multiple rules with AND logic and auto-populates as new items match.

== Screenshots ==
1. Media library folders
2. Folder actions and dialogs
3. Smart Folder rule builder
4. General Settings
5. Context Menu Settings
6. Colors & Icons Settings
7. Export & Import Settings
8. Mobile view

== Changelog ==

= 1.4.1 =
* Fix: in the Divi 5 builder, the folder media modal now shows the drag preview while dragging an image onto a folder, displays the action confirmation messages (move, copy/paste, etc.), and opens directly on the Media Library tab instead of Upload Files.
* Fix: attachments hidden by the PRO Cleanup trash no longer reappear in Smart Folder results or in the folder ZIP download — they now stay hidden everywhere, matching what the Media Library grid already showed.

= 1.4.0 =
* Performance: the folder sidebar loads faster on large media libraries. The "Uncategorized" counter and the per-folder item counts no longer load every attachment ID into memory on each sidebar refresh, and the per-folder counts now run as a single batched query instead of one query per folder.
* Performance: migrating from another folder plugin (FileBird, Folders by Premio, Real Media Library) is faster on large libraries — folder counts are recalculated once when the import finishes instead of after every individual file assignment.
* Hardening: the folder reorder action now validates every sibling folder ID against its taxonomy before saving the order, so a crafted request cannot write folder metadata onto unrelated terms.
* Hardening: uninstalling the plugin now also removes the temporary ZIP-download workspace (uploads/kookoawpf-tmp/), so deleting KooKoa Folders leaves nothing behind.

= 1.3.0 =
* New: WooCommerce "Category" and "Tag" rules for Smart Folders — auto-group products by their product category or product tag, alongside the existing Stock status rule. Visible only on the product custom post type when WooCommerce is active.
* Improvement: minor admin UI refinements.

= 1.2.0 =
* Fix: smart folders are now preserved across JSON export and import. The export used to ship structure + metadata but skip the rule payload entirely, so re-importing a backup or running a "Replace all" silently demoted every smart folder in the tree to a plain folder, wiping its automation rules. The export now serialises the `is_dynamic` flag and the rules alongside the rest of the tree, and the import re-applies both on the new terms.
* New: keyboard shortcut Alt + B toggles Bulk Organize mode from anywhere it's available (Media Library grid + list, Posts, Pages and any folder-enabled custom post type). Press it again — or press Esc with the bulk toolbar open — to exit. Both shortcuts now appear in the Keyboard Shortcuts dialog (Alt + K) under "Bulk Organize" and "Close Modal / Exit Bulk Mode".
* Improvement: minor admin UI refinements.

= 1.1.2 =
* Compatibility: tested with WordPress 7.0 (released May 2026). The retro-dark sidebar, modals and bulk-organize toolbar now neutralize the WP 7.0 Modern admin theme overrides that were inflating our buttons to 40px, breaking dashicon rendering, and pulling icons out of alignment.
* Fix: Smart Startup Folder "Last opened folder" mode now reliably restores the last visited folder on page load. A latent regression in the Settings save path was persisting an empty post-types list, which then blocked the AJAX that records navigation. Both the save serializer and the AJAX validator have been hardened.
* Improvement: minor admin UI refinements.

= 1.1.1 =
* New: WooCommerce "Stock status" rule for Smart Folders — auto-group products by In stock, Out of stock, or On backorder. Visible only on the product custom post type when WooCommerce is active.
* Hardening: uninstall now sweeps every plugin-owned option and user meta key, including the post-1.0 additions (install timestamp, migration importer flags, the permanently-hide-migrate-section flag, per-user dismiss flags for dashboard notices and the Rate Us card). Deleting KooKoa Folders truly leaves zero traces behind.
* Hardening: Smart Startup Folder "Specific folder" preference now verifies that the saved folder still exists in the matching taxonomy before storing it, so a deleted folder no longer leaves a stale reference in user meta.
* Hardening: download Content-Disposition HTTP header now passes the filename through sanitize_file_name() as defense-in-depth against control-character injection.
* Improvement: minor admin UI refinements.

= 1.1.0 =
* New: Migration importer for FileBird (by Ninja Team), Folders (by Premio) and Real Media Library (by devowl.io). Detects existing folders straight from your database and rebuilds the full tree, with file assignments, inside KooKoa Folders in one click. No JSON export needed, no rebuilding from scratch. Optional one-click deactivation of the source plugin after a successful import. Data-driven: imports keep working even when the source plugin section has been partially disabled in its own settings.
* New: Sidebar hint in the Media Library that surfaces detected folder plugins and links straight to the importer.
* New: Architecture ready for more importers. HappyFiles, Enhanced Media Library, Wicked Folders and others can be added in a few lines each.
* Improvement: minor admin UI refinements.

= 1.0.4 =
* New: Dutch translation bundled (nl_NL).
* Improvement: minor admin UI refinements.

= 1.0.3 =
Translations + bug fix release.

* New: Polish translation bundled (pl_PL).
* New: Brazilian Portuguese translation bundled — also covers European Portuguese (pt_PT) and other Portuguese-speaking locales (pt_AO, pt_MZ and others) via automatic locale fallback.
* Fix: "Sidebar width" in Settings → General now applies immediately to the admin who saves it, and the field always reflects the width currently on screen (drag-resized value if any, else the site-wide default).
* Removed: "Sticky sidebar" toggle in Settings → General — the toggle had no effect since the folder sidebar was always pinned regardless of the setting. Sidebar behavior is unchanged for all users.

= 1.0.2 =
Translations release.

* New: Italian translation bundled.
* New: Spanish translation bundled — covers Spain plus all Latin American Spanish variants (es_MX, es_AR, es_CL, es_CO, es_VE, es_PE and others) via automatic locale fallback.
* New: French translation bundled — covers France, Belgium, Canada, Switzerland and other Francophone locales via automatic locale fallback.
* New: German translation bundled — covers Germany, Austria, Switzerland and other German-speaking locales via automatic locale fallback.
* New: Japanese translation bundled.
* Improvement: smart locale fallback — when a region-specific .mo is not present (e.g. es_MX) the plugin now loads the generic language file (es) instead of leaving strings untranslated.
* Improvement: the Force English toggle now appears for users on regional locale variants whenever a generic fallback translation is bundled.

= 1.0.1 =
Bug fix release.

* Fix: media modal "Load more" no longer resets the grid back to the first page.
* Fix: downloading a single selected file now reliably saves to disk instead of occasionally opening it inline in the browser.
* Fix: "Download ZIP" entry no longer appears in the folder context menu on Posts, Pages and Custom Post Types — Media Library only.
* Fix: smart folders with two file extension rules (e.g. avif + webp) now return the union of both, not just one extension.
* Improvement: smart folder rules split per post type — Media gets a clearer "Text contains (Title+Caption+Desc.)" label plus a new "Alt Text contains" rule; Posts/Pages/CPT get a "Title contains" rule that searches post titles only.
* Improvement: folder bulk toolbar now hides Pin/Lock buttons when the matching context-menu entries are disabled in Settings, so the actions stay reversible from a single place.
* Polish: replaced three book emojis in the Folders icon category with new icons that don't duplicate the Documents category.

= 1.0.0 =
Initial release on WordPress.org.

* Unlimited folders and subfolders in the Media Library.
* Unlimited smart folders (rule-based, auto-populated, multiple rules with AND logic).
* Drag and drop attachments into folders.
* Auto-assign new uploads to the current folder.
* Custom folder colors and emoji icons.
* Pin and lock folders.
* Resizable, sticky sidebar with search, sort and keyboard shortcuts.
* Breadcrumb bar, subfolder cards, Smart Startup Folder.
* Mobile responsive layout.
* Bulk Organize mode.
* Download a folder (with all subfolders) or just selected items as a ZIP archive.
* Upload a folder structure from your computer.
* JSON export and import of the folder structure (Merge or Replace).
* Metadata and EXIF tooltip on hover over media items.
* Role-based access control.
* Self-hosted font, admin-only, no frontend footprint.
* Media modal integration with Gutenberg, Classic Editor, Divi 4/5, Elementor, and WooCommerce product galleries.

== Upgrade Notice ==

= 1.4.1 =
Bug-fix release: fixes the media modal drag preview, confirmation messages and initial tab in the Divi 5 builder, and keeps Cleanup-trashed attachments hidden in Smart Folders and ZIP downloads.

= 1.4.0 =
Performance update: faster folder sidebar and faster migrations on large media libraries, plus extra hardening on folder reordering and on uninstall cleanup. Recommended update.

= 1.3.0 =
New WooCommerce "Category" and "Tag" rules for Smart Folders, completing the product automation trio alongside the existing Stock status rule. Visible only on the product post type when WooCommerce is active.

= 1.2.0 =
Important fix: smart folders are now preserved across JSON export and import (a previous bug demoted them to plain folders on import, wiping their automation rules). Adds an Alt + B keyboard shortcut for Bulk Organize. Recommended update.

= 1.1.2 =
WordPress 7.0 compatibility — sidebar, modals and bulk toolbar restored to the original retro-dark look under the new Modern admin theme. Repairs the Smart Startup Folder "Last opened folder" mode. Recommended update.

= 1.1.1 =
New WooCommerce stock-status rule for Smart Folders, hardened uninstall cleanup, plus defense-in-depth security tightening on the Smart Startup Folder and ZIP download paths. Recommended update.

= 1.1.0 =
One-click migration importer from FileBird (Ninja Team), Folders (Premio) and Real Media Library (devowl.io) — full tree and file assignments come over intact.

= 1.0.4 =
Adds Dutch (nl_NL) translation and minor admin UI refinements.

= 1.0.3 =
Adds Polish and Brazilian Portuguese translations (Brazilian Portuguese also serves European and other Portuguese variants). Bug fix for the Sidebar width setting and removal of the non-functional Sticky sidebar toggle.

= 1.0.2 =
Adds Italian, Spanish, French, German and Japanese translations, with automatic fallback for regional variants (es_MX, fr_BE, de_AT and others).

= 1.0.1 =
Bug fix release. Recommended for everyone.

= 1.0.0 =
First public release of KooKoa Folders on WordPress.org.

== Open Source Libraries ==

KooKoa Folders is built on top of these open source projects. Thanks to their authors for sharing their work with the community.

* **jsTree** v3.3.16 by Ivan Bozhanov (vakata) — MIT License
  Website: https://www.jstree.com/

* **Share Tech Mono** by Carrois Apostrophe (Ralph du Carrois) — SIL Open Font License 1.1 — https://www.carrois.com/
  Self-hosted monospace font used throughout the interface. No Google Fonts CDN.

For everything else, KooKoa Folders uses the libraries that already ship with WordPress core — **jQuery**, **jQuery UI** (Draggable, Droppable, Sortable) and **Dashicons** — instead of bundling its own copies.

== Credits ==

KooKoa Folders is designed and developed by Adamo Lussana — https://www.kookoa.com
