=== JT Media Folders ===
Contributors: jtruax
Tags: media, folders, library, organization, gutenberg
Requires at least: 5.0
Tested up to: 7.1.3
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A lightweight solution to add categorized folders to your WordPress Media Library. Works with bulk selection. Optimized for the Gutenberg editor.

== Description ==

= Features =

* **Folder Organization**: Create, edit, and delete media folders/categories
* **AJAX Filtering**: Filters media items using AJAX
* **Bulk Operations**: Assign multiple media items to folders using WordPress bulk selection (Grid + List view)
* **Hierarchical Structure**: Support for nested folders (parent/child relationships)
* **Lightweight**: Plugin was developed with performance in mind
* **Non-intrusive UI**: Clean and simple user interface and controls that are mobile-friendly
* **100% free**: This plugin is free to use, no paywalls or annoying notices

= Creating Folders =

1. Go to Media > Library in your WordPress admin
2. Click the "Add Folder" button in the left sidebar
3. Enter a folder name and optional description
4. Optionally select a parent folder for hierarchical organization
5. Click "Save" to create the folder

= Organizing Media =

**Individual Assignment:**

* Click on any media item to edit it
* Select a folder from the "Folder" dropdown
* Save the changes

**Bulk Assignment (Works in both List and Grid views):**

*List View:*

1. Select multiple media items using checkboxes
2. Choose a folder from the dropdown in the sidebar's "Bulk Actions" section
3. Click "Assign Selected" to move all selected items to the chosen folder

*Grid View:*

1. Click on media items to select them (they'll show a blue border when selected)
2. Choose a folder from the dropdown in the sidebar's "Bulk Actions" section
3. Click "Assign Selected" to move all selected items to the chosen folder

= Managing Folders =

* **Edit**: Click the pencil icon (✏️) next to any folder name
* **Delete**: Click the trash icon (🗑️) next to any folder name
* **Smart Filter**: Click on any folder name to filter the media library by that folder
* **All Files**: Click on "All Files" to show all media regardless of folder assignment

= AI Agents & REST API =

Scripts and AI agents (for example through an MCP connector) can organize folders without the Media Library screen. Users authenticate with application passwords and only get the access they already have: the `upload_files` capability, and editing rights on each attachment they file.

On WordPress 6.9 and newer, these Abilities are registered in the "Media Folders" category: `list-folders`, `list-media`, `get-media-folders`, `ensure-folders`, `update-folder`, `delete-folder`, `assign-media`, `remove-media` and `set-media-folders` (each prefixed `jt-media-folders/`).

REST routes under `/wp-json/jt-media-folders/v1`:

* `GET /folders`, `POST /folders`, `POST /folders/ensure`
* `GET`, `PATCH`, `DELETE /folders/{id}`
* `GET /media` (filter by `folder` ID, `unassigned` or `all`, plus `search`, `mime_type`, `page`, `per_page`)
* `GET /media/folders?ids=1,2,3`
* `POST /media/assign`, `POST /media/remove`, `POST /media/set`

Bulk calls accept up to 500 items. To turn this off, go to **Media > Folder Settings > AI & API Access**, or use the `jt_media_folders_enable_api` filter.

= Requirements =

* WordPress 5.0 or higher
* PHP 7.4 or higher
* MySQL 5.6 or higher

= Security =

The plugin follows WordPress security best practices:

* Nonce verification for all AJAX requests
* Data sanitization and validation
* Capability checks for user permissions
* SQL injection prevention using $wpdb->prepare()

== Installation ==

1. Upload the `jt-media-folders` folder to your `/wp-content/plugins/` directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Navigate to Media > Library to start organizing your media files

= Main Media Library =

Access via **Media > Library** in WordPress admin for full folder management capabilities.

= Gutenberg Media Modal =

When inserting media into posts/pages, the plugin automatically adds a sidebar to the media modal for easy filtering and organization.

== Screenshots ==

1. Media Library with folder sidebar and filtering
2. Folder management interface
3. Gutenberg media modal with folder integration

== Changelog ==
= 1.2.0 =
* New Feature: REST API (`jt-media-folders/v1`) for managing folders and filing media in bulk
* New Feature: WordPress Abilities for AI agents and MCP clients (WordPress 6.9+)
* New Setting: "AI & API Access" toggle on the Folder Settings page (on by default)
* Improved: Faster folder filtering in the Media Library and media modal for large folders
* Fixed: Folder counts included media that had since been deleted. Deleted media is now removed from its folders, and leftover entries are cleaned up once on update


= 1.1.4 =
* Confirm compatibility with WordPress 7.1.2
* Improved: Nested folders now show visible tree guide lines in the Media Library and modal


= 1.1.3 =
* Fixed: In Media Library grid view, clicking an image after switching folders sometimes wouldn't open the attachment details panel


= 1.1.2 =
* Bug fixes for the Gutenberg gallery block


= 1.1.1 =
* Modified sidebar width for the media modal


= 1.1.0 =
* New Feature: Media Settings page added with font size options
* New Feature: Export / Import folders from the Folder Settings page
* UI improvements
* Fixed: Upload progress animation not showing in the media modal when a folder was selected


= 1.0.9 =
* Compatibility improvements for third-party plugins
* Media uploads are now auto-assigned if a folder is selected

= 1.0.8 =
* Speed optimization improvements

= 1.0.7 =
* Fixed: Issue with folders not clearing after closing media modal
* UI improvements to Gutenberg media modal

= 1.0.6 =
* Fixed: "Add Folder" button content alignment on Media Library sidebar

= 1.0.5 =
* New Feature: Bulk-assign items from the Gutenberg Media Modal
* Added infinite scrolling for large libraries
* Added toggle collapse for Media Library page
* Allowed media files to be assigned multiple categories
* Security: harden AJAX auth, fix orphaned assignments, strip internal error details

= 1.0.4 =
* Fixes for the Gallery block
* Added ability to edit folder names in Gutenberg
* UI improvements

= 1.0.3 =
* Fixed issue when editing multiple folder names
* Updates to Gutenberg folder selection field
* Updates to search field

= 1.0.2 =
* New Feature: Click & drag folder reordering.
* Security hardening: Added category existence validation, prevented default category manipulation, and improved input sanitization for the folder reordering feature.

= 1.0.1 =
* AJAX filtering improvements
* UI fixes for Media Library while in List view
* Mobile improvements

== Upgrade Notice ==

= 1.0.6 =
Fixes "Add Folder" button alignment in the Media Library sidebar on live sites.

= 1.0.5 =
Adds bulk-assign in the Gutenberg Media Modal, infinite scrolling for large libraries, multi-category assignment, and security hardening.
