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

Unlimited folders and subfolders for your WordPress Media Library, with drag and drop.

== 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

= 🚀🚀🚀 Pro add-on =

A separate commercial add-on, KooKoa Folders Pro, extends folders to Posts, Pages and Custom Post Types. It also adds image editing, watermarking, WebP/AVIF conversion, duplicate detection and unused media cleanup.
👉 [**TRY THE LIVE DEMO**](https://demo.kookoa.com/live) ☝️

== 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. Import & Export Settings
8. Mobile view

== Changelog ==

= 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.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
  Source: https://github.com/vakata/jstree (tag 3.3.16)
  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
