=== 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: 6.9
Requires PHP: 7.4
Stable tag: 1.0.3
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

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

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

== Changelog ==

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