=== Media Shelf – Media Library Folders ===
Contributors: jeanswiegers
Tags: media library folders, media folders, media categories, folders, organize media
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Media Library folders with drag and drop: nested folders, colours and search in grid view, list view and every media dialog. All free.

== Description ==

Media Shelf adds a folder panel to the WordPress Media Library, so you can organise images, videos and documents into media folders and find them again in seconds. Files are filed with real WordPress taxonomies, so nothing moves on disk and URLs never change.

Every folder feature is free: unlimited folders and subfolders, folder colours, drag and drop, and the panel in every media dialog.

* **A folder tree where you work.** It appears in the Media Library grid and list views, and in every media dialog, including the block editor's Media Library and the featured image picker. "All files" and "Uncategorised" are always one click away.
* **Drag and drop.** Drag one file or a whole selection onto a folder. Dropping moves files by default; hold Alt (Option on a Mac) to add them to a folder while keeping their other folders. Every change can be undone from the notice that follows.
* **Organise folders in place.** Create, rename and delete folders inline. Drag a folder onto another to nest it, or between folders to reorder. You can also sort A–Z and pick from nine folder colours. Nesting has no limit.
* **Right-click menu, keyboard and screen readers.** Folders have a context menu. The tree is a proper ARIA tree, controlled with arrow keys, type-ahead, F2 to rename, Delete, and Alt+arrows to move folders. Folder moves are announced.
* **Upload into a folder.** Files you upload land in the folder that is selected.
* **Search folders.** Each result shows where the folder lives.
* **Collapsible and resizable.** The panel's width and collapsed state are remembered in your browser.
* **Fast with large trees.** Subfolders load when you open them, through the REST API.
* **Switching from Enhanced Media Library?** Media Shelf offers a one-click import of Enhanced Media Library's settings. Your categories become folders with every assignment intact. It also understands Enhanced Media Library's taxonomy attributes in gallery and playlist shortcodes, for example `[gallery media_category="5"]`.
* **Works with what WordPress already has.** Folders are taxonomy terms. You can add more "folder sets" (for example clients or vendors), or use post categories and tags on media. The attachment details sidebar keeps its checkboxes, and the list view has Move, Add and Remove bulk actions.
* **Works where you edit.** Tested with the block editor, the Classic Editor plugin and the Elementor editor's media dialogs, on single sites and multisite networks (network-activated or per site).
* **Right-to-left ready, translatable, private.** No tracking, no external requests, no ads in your dashboard.

Media Shelf is not affiliated with or endorsed by the authors of Enhanced Media Library, FileBird, Real Media Library or Folders.

= Source code =

The JavaScript in `build/` is compiled with @wordpress/scripts. The uncompressed source is in the `src/` folder of this plugin, with `package.json`. Run `npm install && npm run build` to rebuild it.

== Installation ==

1. Install and activate Media Shelf from Plugins → Add New.
2. Open Media → Library. The folder panel is on the left; click "New" to create your first folder.
3. Optionally, visit Media → Media Shelf to choose where the panel appears, set the drop behaviour, or import from Enhanced Media Library.

== Frequently Asked Questions ==

= Does it create folders on disk? =

No. Folders are WordPress taxonomy terms, which is metadata only. Files and their URLs stay exactly where WordPress put them.

= Can a file be in more than one folder? =

Yes. Hold Alt (Option on a Mac) while dropping, or use "Also add to folder…" in the list view. You can also make Add the default in the settings.

= What do the numbers next to folders mean? =

They are the number of files directly in that folder. Files in subfolders are counted in the subfolder.

= Switching from Enhanced Media Library =

Enhanced Media Library's categories are ordinary WordPress taxonomies, so nothing has to be copied or converted:

1. Keep Enhanced Media Library active for now and activate Media Shelf.
2. On the Dashboard, Plugins or Media screen, Media Shelf shows a notice listing the taxonomies it found. Click "Import now" (or "Review first" to see them under Media → Media Shelf).
3. Your media categories, and any extra taxonomies you created in Enhanced Media Library, appear as folder sets in the panel, with every file assignment intact.
4. Deactivate Enhanced Media Library. Gallery and playlist shortcodes that filter by its taxonomies, such as `[gallery media_category="5"]`, keep working.

Media Shelf only takes over folders and categories. Enhanced Media Library's other settings, such as its MIME type options, are not imported.

= Does it work with page builders and the Classic Editor? =

Media Shelf extends WordPress's own media dialog, so it appears wherever a plugin uses it. It is tested with the Classic Editor plugin (Add Media and Featured image) and with Elementor's image controls.

= Does it work on multisite? =

Yes. Network-activate it or activate it on individual sites. Each site has its own folders and settings. When the plugin is deleted, the clean-up runs on every site.

= What happens to my folders if I delete Media Shelf? =

By default they stay in the database. If you tick "Delete Media Shelf's folders when the plugin is deleted", folders created by Media Shelf are removed. Files are never deleted, and imported Enhanced Media Library sets and post categories are always kept.

= Is there a Pro version? =

Yes, as an optional, separate add-on (Media Shelf Pro). It adds auto-filing rules for uploads, folder permissions per role or user, a folder gallery block and shortcode, sort options, and ZIP download of folders. Nothing in this free plugin is limited or locked, and it never asks you to upgrade.

= Does Media Shelf collect data? =

No. It sends nothing anywhere. See Privacy below.

== Privacy ==

Media Shelf does not collect or send any data.

Media Shelf itself does not set front-end cookies and does not contact any other service.

== Screenshots ==

1. The folder panel in the Media Library grid view.
2. Dragging a selection of files onto a folder.
3. The right-click menu, with folder colours.
4. Creating a subfolder inline.
5. Searching folders.
6. The folder panel in the list view.
7. The folder panel in the block editor's media dialog.
8. Settings.
9. Right-to-left layout.
10. One-click import from Enhanced Media Library.
11. Deleting a folder keeps its files.
12. The panel collapsed.

== Changelog ==

= 1.0.0 – first public release =
* Folder panel in the Media Library grid view, list view and every media dialog (block editor, Classic Editor, featured image, Elementor), with "All files" and "Uncategorised".
* Unlimited nested folders with counts, search, inline create, rename and delete, sorting and nine folder colours, all free.
* Drag and drop: move or add one file or a whole selection onto a folder; drag folders to nest and reorder. Undo after every change.
* Right-click menu, full keyboard support (ARIA tree), screen reader announcements and right-to-left layout.
* Uploads land in the selected folder.
* Extra folder sets (any taxonomy), optional post categories and tags on media, folder checkboxes in attachment details, and Move/Add/Remove bulk actions in the list view.
* One-click import from Enhanced Media Library, including its gallery and playlist shortcode attributes.
* Multisite support (network-wide or per site). Works with WordPress 6.5+ and PHP 7.4+.
* Developer hooks for add-ons (folder permissions, data and order filters, settings sections, JavaScript menu, badge and browser hooks).
* Enhanced Media Library import notices are dismissible and appear only on the Plugins and Media screens, never on the Dashboard.
