=== Technovia Paper Submissions ===
Contributors: technoviadev
Tags: paper submission, document management, custom post type, ajax form, user dashboard, file upload, gutenberg, elementor, email notifications, moderation
Requires at least: 5.8
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A professional paper and document submission system with AJAX-powered forms, admin moderation, email notifications, Gutenberg blocks, Elementor widgets, multi-file upload with MIME validation, and a full user dashboard.

== Description ==

**Technovia Paper Submissions** provides a complete end-to-end paper submission and review workflow for WordPress. Built with OOP architecture, it covers everything from frontend submission to admin moderation with automated email notifications.

= Core Features =

* **Custom Post Type** — `paper` with full status support: Draft, Pending Review, Approved, Rejected, Revision Requested, Published.
* **Frontend Submission Form** — AJAX-powered with drag-and-drop file upload, live file preview, per-type size limits, and a preview-before-submit step.
* **User Dashboard** — Responsive table with search, pagination, inline edit modal, and delete. Batch meta cache for performance.
* **Custom Login & Registration** — Tabbed auth widget via shortcode with Forgot Password link. New registrations are automatically assigned the Contributor role (configurable).
* **Admin Moderation UI** — Approve, Reject, or Request Revision directly from the paper edit screen with a single click. Status updates fire email notifications automatically.
* **Email Notifications** — Automatic emails on: new submission (admin), submission received (user), approved, rejected, and revision requested. Falls back to the WP account email if no contact email was provided.
* **Gutenberg Blocks** — Native blocks for the Submission Form and User Dashboard, with a live form-selector dropdown in the block inspector.
* **Elementor Widgets** — Dedicated widgets for the Submission Form and User Dashboard inside a "Paper Submissions" Elementor category.
* **Custom Form Builder** — Create unlimited reusable forms from the admin (TPS Forms CPT). Supports text, email, phone, number, textarea, select/dropdown, and checkbox fields with labels, placeholders, and required toggles. Drag-to-reorder rows. Embed with `[tps_form id="X"]`.
* **Security First** — Nonce verification on every AJAX action, `finfo` real MIME-type validation (not just extension), dangerous-extension blacklist (php, exe, sh, etc.), honeypot anti-spam field, login brute-force protection (5 attempts / 10-minute lockout), capability checks, full input sanitization and output escaping throughout.
* **Performance** — Assets load conditionally only on pages that contain plugin shortcodes, blocks, or Elementor widgets. Composite database indexes on `(form_id, submitted_at)` and `(user_id, submitted_at)`. Post meta loaded in a single batch query on the dashboard (no N+1).
* **Admin Settings** — Control allowed file types (PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, ZIP, JPG, JPEG, PNG), per-type upload size limits (images 5 MB, ZIP 50 MB, documents configurable), max files per submission, redirect URLs, login page URL, default submission status, default user role, email notification toggles, and primary/secondary UI colors.

= Supported File Types =

PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, ZIP, JPG, JPEG, PNG

= File Size Limits (defaults) =

* Images (JPG, PNG): 5 MB
* ZIP archives: 50 MB
* Documents (PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX): configurable via admin settings (default 10 MB)

== Installation ==

1. **Download** the plugin zip file.
2. In your WordPress admin go to **Plugins → Add New → Upload Plugin**.
3. Upload the `.zip` file and click **Install Now**, then **Activate**.
4. **Deactivate and reactivate** the plugin once to apply database indexes (or it happens automatically on first activation).
5. Navigate to **Papers → Settings** to configure the plugin.

== Shortcodes ==

= [paper_auth] =
Displays a Login / Register tabbed form with a Forgot Password link. Logged-in users see a welcome message with a logout link.

= [paper_submission_form] =
Displays the AJAX-powered paper submission form with drag-and-drop file upload and a preview-before-submit step. Guests who are not logged in are redirected to the configured login page.

= [paper_dashboard] =
Displays a responsive table of the logged-in user's submitted papers with search, pagination, status badges, file links, and inline edit/delete actions.

= [tps_form id="X"] =
Renders a custom form built in the TPS Forms builder. Replace `X` with the form's post ID (visible in the Shortcode column on the TPS Forms list, or in the Shortcode metabox on the form edit screen).

== Setup Guide ==

1. Create a page called **Login** and add the shortcode `[paper_auth]`.
2. Create a page called **Submit Paper** and add the shortcode `[paper_submission_form]`.
3. Create a page called **My Dashboard** and add the shortcode `[paper_dashboard]`.
4. Go to **Papers → Settings**:
   * Set the **Login Page URL** to the Login page you just created.
   * Set **Redirect After Submission** to the Dashboard page (optional).
   * Set **Default Post Status** (Pending Review recommended for a moderated workflow).
   * Set **Default Role for Registrations** (Contributor recommended).
   * Choose **Allowed File Types** and configure upload size limits.
   * Enable/disable **Email Notifications** for admin and user.
5. (Optional) Go to **Papers → Paper Categories** to create categories for submissions.
6. (Optional) Go to **TPS Forms → Add New** to build a custom form, then embed it with `[tps_form id="X"]`.

== Moderation Workflow ==

1. User registers (auto-assigned Contributor role) → logs in → submits a paper.
2. Admin receives a notification email with a direct link to the submission.
3. User receives a "Submission Received" confirmation email.
4. Admin opens the paper in **Papers → All Papers** and uses the **Submission Details & Files** metabox to:
   * **Approve** — sets status to Approved, emails the user.
   * **Reject** — sets status to Rejected, emails the user.
   * **Request Revision** — sets status to Revision Requested, emails the user.
5. Users can see the current status of each paper in their Dashboard.

== Gutenberg Blocks ==

After activating the plugin, two blocks are available in the block inserter under the **Widgets** category:

* **BPS Dashboard** — renders the `[paper_dashboard]` shortcode output.
* **BPS Form** — select a form from a dropdown in the Block Inspector to embed `[paper_submission_form]`.

== Elementor Widgets ==

If Elementor is active, two widgets appear under the **Paper Submissions** category in the Elementor widget panel:

* **Submission Form** — select a form from the widget controls.
* **User Dashboard** — no additional configuration needed.

== Frequently Asked Questions ==

= What file types are supported? =
PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, ZIP, JPG, JPEG, and PNG. You can enable or disable any of these from **Papers → Settings → Allowed File Types**.

= How many files can a user upload per submission? =
Between 1 and 10, configurable in the admin settings.

= Is there a file size limit? =
Yes. Images are capped at 5 MB and ZIP files at 50 MB. Document size is configurable (default 10 MB, max 50 MB). Limits are enforced both client-side (JS preview) and server-side (PHP validation).

= How does file security work? =
Every uploaded file is validated in three layers: (1) allowed-extension check, (2) real MIME-type check via PHP's `finfo` extension comparing actual file content — not just the browser-reported type, (3) dangerous-extension blacklist (`.php`, `.exe`, `.sh`, etc.) that cannot be overridden by settings.

= Can guests submit papers? =
By default, no — users must be registered and logged in. Guest submissions can be enabled from **Papers → Settings → Allow Guest Submissions**.

= What role are new registrants assigned? =
Contributor by default. This is configurable from **Papers → Settings → Default Role for Registrations**.

= Will the plugin slow down my site? =
No. CSS and JavaScript are loaded only on pages that actually use plugin shortcodes, Gutenberg blocks, or Elementor widgets — no global asset injection.

= Can I change the UI colors? =
Yes. Go to **Papers → Settings → UI Customisation** and pick a Primary and Secondary color using the color picker.

= How do I get the shortcode for a custom form? =
Open **TPS Forms** in the admin. The shortcode is shown in the **Shortcode** column on the list screen, and in the **Shortcode** sidebar metabox on the form edit screen.

== Changelog ==

= 1.1.0 =
* Added: Admin Moderation UI — Approve, Reject, and Request Revision buttons in the paper metabox.
* Added: `rejected` and `revision_requested` custom post statuses with admin badge support.
* Added: `tps_moderate_paper` AJAX handler for secure status updates.
* Added: Email notifications for Approved, Rejected, and Revision Requested statuses.
* Added: Email fallback to WordPress account email when no contact email was submitted.
* Added: Gutenberg blocks — BPS Dashboard and BPS Form with live form-selector dropdown.
* Added: Elementor widgets — Submission Form and User Dashboard.
* Added: `[tps_form id="X"]` shortcode handler (`custom_form_shortcode()` method implemented).
* Added: `rejected` and `revision_requested` status labels and badge CSS classes.
* Added: PPT, PPTX, XLS, XLSX, ZIP to allowed file types in admin settings and MIME validation map.
* Added: Forgot Password link in the Login tab of the auth template.
* Added: `show_in_rest => true` on `tps_form` CPT for Gutenberg block form-selector API.
* Added: Honeypot anti-spam field on the submission form.
* Added: Login brute-force protection — 5 failed attempts triggers a 10-minute IP lockout via transients.
* Added: Real MIME-type validation using PHP `finfo` extension (validates file content, not just extension).
* Added: Per-type file size limits — images 5 MB, ZIP 50 MB, documents use admin-configured limit.
* Added: Dangerous-extension blacklist (php, php3-7, phtml, exe, sh, bat, cmd, ps1, js).
* Added: New registrants are automatically assigned Contributor role (configurable in settings).
* Added: Post status control in settings — Auto Publish, Pending Review, or Draft.
* Added: Guest submission toggle in settings.
* Added: Admin notification email toggle and custom admin email address field.
* Added: User confirmation email toggle.
* Added: Preview-before-submit step on the submission form.
* Added: File attachment viewer in the paper metabox with View/Download buttons and image thumbnails.
* Added: Composite database indexes on `(form_id, submitted_at)` and `(user_id, submitted_at)`.
* Improved: Assets now load conditionally only on pages using plugin shortcodes, blocks, or Elementor widgets.
* Improved: Dashboard query uses `update_post_meta_cache` to eliminate N+1 meta queries.
* Improved: Moderation JS nonce passed via `wp_json_encode` data object — no PHP string concatenation.
* Improved: Admin moderation errors shown in a styled inline notice instead of a native browser `alert()`.
* Fixed: `get_option('tps_settings')` now called only when assets are actually needed (after early-return check).
* Fixed: Inline `<script>` in CPT metabox replaced with `wp_add_inline_script()` for CSP compliance.
* Security: `wp_unslash()` applied consistently to all `$_POST` reads in AJAX handlers.

= 1.0.0 =
* Initial release.
* Custom Post Type `paper` with taxonomy `paper_category`.
* AJAX paper submission with multi-file upload.
* User dashboard with search, pagination, edit, and delete.
* Custom login/registration shortcode with auto-login on register.
* Admin settings panel (file types, upload limits, redirects, UI colors).
* Custom Form Builder CPT (`tps_form`) with sortable field rows.
* Form submission storage in custom database table.
* Admin form submissions viewer with detail modal.
