Merge branch 'release/2.6.1'

Author: danieliser

.cursor/rules/content-control/content-control-js.mdc

@@ -0,0 +1,90 @@
+---
+description: Rules for the JavaScript/React codebase of the Content Control Plugin
+globs: ["packages/**/*.{js,jsx,ts,tsx}"]
+alwaysApply: false
+---
+
+# Content Control Plugin - JavaScript/React Codebase Rules
+
+These rules are specific to the JavaScript/React codebase of the Content Control plugin, providing guidance for AI agents working with the frontend logic and user interface components.
+
+## JavaScript/React Architecture Overview
+
+The Content Control plugin utilizes React and WordPress's `@wordpress/scripts` build tooling for its admin user interface. The frontend codebase is located within the `packages/` directory and is structured as a monorepo managed by NX.
+
+### Key Packages
+
+-   **`packages/block-editor/`**: Contains code related to Block Editor (Gutenberg) integration.
+    -   **`src/block-extensions/`**: Extends existing blocks with Content Control settings.
+    -   **`src/components/`**: Reusable React components specific to the block editor integration.
+    -   **`src/contexts/`**: React Contexts for managing state within the block editor UI.
+-   **`packages/components/`**: Contains reusable React components used throughout the plugin's admin UI (Settings Page, Block Editor, etc.). These are general-purpose components.
+-   **`packages/core-data/`**: Implements Redux-like data stores using `@wordpress/data` for managing client-side application state. Stores are organized by feature (license, restrictions, settings, url-search).
+-   **`packages/data/`**: A wrapper around `@wordpress/data`, potentially for custom extensions or utilities.
+-   **`packages/fields/`**: React components for rendering various form field types used in settings and rule configurations.
+-   **`packages/icons/`**: Custom SVG icons used in the React UI.
+-   **`packages/query-builder/`**: Contains React components, contexts, and reducers for building the visual rule query builder UI.
+-   **`packages/settings-page/`**: The main React application for the plugin's settings page.
+    -   **`src/restrictions-view/`**: Components for managing and displaying restrictions within the settings page.
+    -   **`src/settings-view/`**: Components for displaying and managing general plugin settings.
+    -   **`src/upgrades-view/`**: Components related to plugin upgrades and license management.
+-   **`packages/utils/`**: General JavaScript utility functions used across packages.
+-   **`packages/widget-editor/`**: Code for integration with the legacy widget editor (if applicable).
+
+### Important JavaScript/React Components and Modules
+
+-   **`packages/settings-page/src/App.tsx`**: The main entry point for the Settings Page React application.
+-   **`packages/block-editor/src/block-extensions/block-controls/edit.tsx`**:  The main component that adds Content Control UI to the Block Editor inspector controls.
+-   **`packages/core-data/src/*/index.ts`**: Entry points for each data store slice (e.g., `restrictions`, `settings`, `license`).
+-   **`packages/components/src/entity-select-control/`**: Reusable component for selecting WordPress entities (posts, terms, users) with search and multi-select capabilities.
+-   **`packages/query-builder/src/components/`**: Components that make up the rule query builder UI (groups, rules, operators, etc.).
+-   **`packages/components/src/controlled-tab-panel/`**: Reusable tab panel component used in the settings page.
+
+### Coding Standards and Best Practices (JavaScript/React)
+
+-   **React Best Practices:** Follow established React best practices for component design, state management, and performance.
+    -   Use functional components and hooks where appropriate.
+    -   Keep components small, focused, and reusable.
+    -   Optimize component rendering and avoid unnecessary re-renders.
+    -   Use keys for lists of components.
+-   **WordPress JavaScript Coding Standards:** Adhere to WordPress JavaScript coding standards.
+    -   Use spaces for indentation (typically 2 spaces).
+    -   Use single quotes for strings.
+    -   Avoid long lines of code.
+    -   Document components and functions with JSDoc-style comments.
+-   **TypeScript:** The codebase uses TypeScript. Write type-safe code and utilize TypeScript features effectively.
+    -   Define clear interfaces and types for components, data structures, and API interactions.
+    -   Use type checking to catch errors early in development.
+-   **`@wordpress/scripts` Build Tooling:** Utilize the tools and configurations provided by `@wordpress/scripts` for building, linting, and testing JavaScript code.
+    -   Use `npm run start` for development with hot reloading.
+    -   Use `npm run build` for production builds.
+    -   Use `npm run lint:js` for JavaScript linting.
+    -   Use `npm run format:js` for code formatting.
+-   **State Management with `@wordpress/data`:** Understand and utilize `@wordpress/data` for managing application state.
+    -   Use `useSelect` to access data from stores.
+    -   Use `useDispatch` to dispatch actions to stores.
+    -   Define clear selectors and actions for data store interactions.
+-   **Component Reusability:** Design and build reusable components in the `packages/components/` directory to promote code sharing and consistency across the UI.
+-   **Context API for State Management:** Utilize React Context API for managing component-level or feature-specific state, especially within the Block Editor and Query Builder packages.
+
+### Important JavaScript/React Functions and Hooks
+
+-   **React Hooks:** Utilize common React hooks like `useState`, `useEffect`, `useContext`, `useCallback`, `useMemo`.
+-   **`@wordpress/data` Hooks:**
+    -   `useSelect`: Hook to select data from WordPress data stores.
+    -   `useDispatch`: Hook to dispatch actions to WordPress data stores.
+    -   `withSelect`: Higher-order component for connecting components to data stores (less common in modern React).
+    -   `withDispatch`: Higher-order component for connecting components to dispatch actions (less common in modern React).
+-   **WordPress Components (`@wordpress/components`):** Utilize pre-built WordPress components from the `@wordpress/components` library for UI elements (buttons, inputs, selects, modals, etc.).
+-   **WordPress Block Editor APIs (`@wordpress/block-editor`, `@wordpress/blocks`):** When working with Block Editor integration, use APIs from `@wordpress/block-editor` and `@wordpress/blocks` to extend blocks, register block attributes, and interact with the editor.
+-   **REST API Interactions:** Use `wp.apiFetch` (or standard `fetch` API) for making requests to WordPress REST API endpoints.
+
+### Debugging JavaScript/React Code
+
+-   **Browser Developer Tools:** Use browser developer tools (Chrome DevTools, Firefox Developer Tools) extensively for debugging JavaScript code.
+    -   **Console:** Use `console.log()`, `console.warn()`, `console.error()` for logging messages.
+    -   **Debugger:** Set breakpoints in the code and step through execution.
+    -   **React Developer Tools Extension:** Use the React Developer Tools browser extension to inspect React component trees, props, and state.
+    -   **Network Tab:** Inspect network requests to REST API endpoints.
+-   **`WP_DEBUG` (WordPress):** Enabling `WP_DEBUG` in `wp-config.php` can sometimes provide additional JavaScript error information in the browser console.
+-   **Source Maps:** Ensure source maps are enabled in development builds to debug against the original source code instead of bundled code.

.cursor/rules/content-control/content-control-php.mdc

@@ -0,0 +1,85 @@
+---
+description: Rules for the PHP codebase of the Content Control Plugin
+globs: ["**/*.php"]
+alwaysApply: false
+---
+# Content Control Plugin - PHP Codebase Rules
+
+These rules are specific to the PHP codebase of the Content Control plugin and provide guidance for AI agents working with the backend logic.
+
+## PHP Architecture Overview
+
+The Content Control plugin's backend is primarily written in PHP, following WordPress coding standards and best practices. The architecture is modular and object-oriented, with a clear separation of concerns.
+
+### Key Directories
+
+-   **`classes/`**: Contains the core PHP logic of the plugin, organized into subdirectories based on functionality.
+    -   **`Base/`**: Abstract base classes and the dependency injection container.
+    -   **`Controllers/`**: Handles specific areas of functionality (Admin, Frontend, Compatibility, REST API).
+    -   **`Installers/`**: Classes for plugin installation and upgrades.
+    -   **`Interfaces/`**: Defines interfaces for controllers and upgrades.
+    -   **`Models/`**: Data models representing plugin entities (Restriction, Rule, Group).
+    -   **`Plugin/`**: Core plugin classes (Core, Autoloader, License, Connect, etc.).
+    -   **`QueryMonitor/`**: Integration with the Query Monitor plugin.
+    -   **`RestAPI/`**: REST API endpoint implementations.
+    -   **`RuleEngine/`**: Classes related to the Rule Engine logic.
+    -   **`Services/`**: Reusable services and utilities.
+    -   **`Upgrades/`**: Classes for specific upgrade routines (data migrations).
+-   **`inc/`**: Contains utility functions, organized into subdirectories.
+    -   **`functions/`**: Various function files (compatibility, content, developers, options, rules, etc.).
+    -   **`deprecated/`**: Deprecated classes and functions.
+-   **`bin/`**: Utility scripts, including stub generation scripts.
+-   **`tests/`**: PHPUnit tests for the plugin.
+
+### Important PHP Classes
+
+-   **`classes/Plugin/Core.php`**: The main plugin class, responsible for initialization, service registration, and defining plugin paths.
+-   **`classes/RuleEngine/RuleEngine.php`**: (Note: Class name might be `Handler.php` or `Rules.php`) The core Rule Engine class that evaluates rules and restrictions.
+-   **`classes/Models/Restriction.php`**: The data model for a Restriction, handling loading settings, checking rules, and providing access to restriction data.
+-   **`classes/Controllers/Admin/*.php`**: Controllers for admin-related functionality (Settings Page, Upgrades, Reviews).
+-   **`classes/Controllers/Frontend/*.php`**: Controllers for frontend restriction logic (Main Query, Post Content, REST API).
+-   **`classes/RestAPI/*.php`**: REST API endpoint controllers.
+-   **`classes/Services/*.php`**: Service classes like `Restrictions.php`, `Options.php`, `Logging.php`, `UpgradeStream.php`.
+-   **`classes/Base/Container.php`**: Dependency injection container (Pimple).
+
+### Coding Standards and Best Practices (PHP)
+
+-   **WordPress Coding Standards for PHP:** Strictly adhere to the WordPress PHP coding standards.
+    -   Use spaces for indentation, not tabs.
+    -   Follow WordPress PHPDoc standards for documentation.
+    -   Use lowercase with hyphens for function names.
+    -   Use underscores for class and method names (in many legacy parts, but new code should aim for camelCase).
+    -   Sanitize and escape data properly to prevent security vulnerabilities.
+    -   Use nonces for form submissions and AJAX requests.
+-   **Object-Oriented Programming (OOP):** Utilize OOP principles for code organization and reusability.
+-   **Dependency Injection (DI):** Leverage the simple DI container (`classes/Base/Container.php`) for managing services and dependencies.
+-   **Modularity and Separation of Concerns:** Keep code modular and separate concerns into different classes and functions.
+-   **Code Documentation:** Write clear and comprehensive PHPDoc comments for all classes, methods, and functions.
+-   **Performance Optimization:** Write efficient code, optimize database queries, and use caching where appropriate.
+-   **Error Handling and Logging:** Implement proper error handling and use the `Logging` service for logging important events and errors.
+-   **Security Best Practices:** Follow WordPress security best practices to prevent vulnerabilities.
+
+### Important PHP Functions and Hooks
+
+-   **WordPress Options API:** Use `get_option()`, `update_option()`, `delete_option()` for managing plugin settings.
+-   **WordPress Custom Post Types API:** Use `register_post_type()` to register the `cc_restriction` custom post type.
+-   **WordPress REST API Functions:** Use `register_rest_route()` to register REST API endpoints.
+-   **WordPress Filters and Actions:** Utilize WordPress action and filter hooks for extending plugin functionality and integrating with WordPress core and other plugins.
+    -   `the_content` filter: Used to filter post content and apply restrictions.
+    -   `pre_get_posts` action: Used to modify the main query and apply restrictions to content listings.
+    -   `rest_api_init` action: Used to register REST API endpoints.
+    -   Numerous custom action and filter hooks within the plugin codebase.
+-   **Plugin API Functions (in `inc/functions/developers.php`):**
+    -   `content_has_restrictions()`: Checks if content has any restrictions applied.
+    -   `user_can_view_content()`: Checks if the current user can view specific content.
+    -   `content_is_restricted()`: Checks if content is currently restricted for the current user.
+    -   `get_applicable_restriction()`: Gets the most applicable restriction for the current context.
+    -   `get_all_applicable_restrictions()`: Gets all applicable restrictions for the current context.
+
+### Debugging PHP Code
+
+-   **`error_log()`:** Use `error_log()` to write debug messages to the PHP error log.
+-   **`WP_DEBUG`:** Enable `WP_DEBUG` in `wp-config.php` for more detailed error reporting.
+-   **`Logging` Service:** Use the `plugin('logging')->log()` method to log messages using the plugin's logging service.
+-   **Xdebug:** Consider using Xdebug for step-by-step debugging and code inspection.
+-   **Query Monitor Plugin:** Use the Query Monitor plugin to inspect database queries, PHP errors, hooks, and other aspects of WordPress execution.

.cursor/rules/content-control/content-control.mdc

@@ -0,0 +1,78 @@
+---
+description: Rules for the Content Control Plugin
+globs:
+alwaysApply: true
+---
+# Content Control Plugin - AI Agent Rules
+
+These rules provide context and guidance for AI agents working with the Content Control plugin codebase.
+
+## Plugin Description
+
+Content Control is a WordPress plugin designed to provide fine-grained control over content visibility. It allows administrators to restrict access to various parts of their WordPress site based on a flexible rule engine. Restrictions can be applied based on user roles, login status, specific dates/times, device types, and custom rules.
+
+The plugin is built with a modular architecture, utilizing both PHP for the backend and React for the admin user interface. It leverages WordPress best practices and coding standards, aiming for performance, security, and extensibility.
+
+## Key Features
+
+-   **Rule-Based Restrictions:** Define complex rules using a combination of conditions and logical operators (AND/OR).
+-   **Multiple Restriction Types:** Restrict content based on user roles, login status, date/time, device type, and more.
+-   **Flexible Protection Methods:** Choose how restricted content is handled: redirect to another page, replace content with a message, or hide content entirely.
+-   **Block-Level Control:** Apply restrictions directly to individual Gutenberg blocks within post content.
+-   **Widget Restrictions:** Control the visibility of WordPress widgets based on rules.
+-   **REST API Control:** Secure WordPress REST API endpoints by applying content restrictions.
+-   **Extensibility:** Developers can extend the plugin by creating custom rules and integrations.
+-   **Settings Page:** A comprehensive settings page built with React for managing plugin options and restrictions.
+-   **Developer-Friendly:** Well-documented codebase with clear architecture, making it easy for developers to understand and contribute.
+
+## Architecture Overview
+
+The plugin follows a modular architecture with distinct components for the backend (PHP) and frontend (React).
+
+### PHP Backend
+
+-   **Rule Engine:** Core logic for evaluating rules and applying restrictions (`classes/RuleEngine/`).
+-   **Restrictions CPT:** Restrictions are stored as a custom post type (`cc_restriction`).
+-   **Controllers:** Handle specific functionalities like admin settings, frontend restrictions, and REST API endpoints (`classes/Controllers/`).
+-   **Models:** Represent data structures like `Restriction` and `Rule` (`classes/Models/`).
+-   **Services:** Provide reusable business logic and utilities (`classes/Services/`).
+-   **REST API Endpoints:** Expose plugin functionality via WordPress REST API (`classes/RestAPI/`).
+
+### React Admin UI
+
+-   **Settings Page:** React application for managing plugin settings and restrictions (`packages/settings-page/`).
+-   **Block Editor UI:** Integrations with Gutenberg block editor for block-level restrictions (`packages/block-editor/`).
+-   **Data Stores:** Uses `@wordpress/data` for client-side state management (`packages/core-data/`).
+-   **Reusable Components:** React components used across the admin UI (`packages/components/`).
+-   **Query Builder UI:** React-based UI for building complex rule queries (`packages/query-builder/`).
+
+## Key Concepts
+
+-   **Restrictions:** Saved configurations that combine rules and protection settings to control content access.
+-   **Rules:** Individual conditions evaluated by the Rule Engine (e.g., "User Role is Administrator").
+-   **Rule Engine:** The system that processes restrictions and determines if they should be applied.
+-   **Contexts:** Define the environment in which rules are evaluated (e.g., 'main', 'blocks', 'restapi').
+-   **Protection Methods:** Actions taken when a restriction's rules are met (e.g., redirect, replace content).
+
+## Coding Standards and Best Practices
+
+-   **WordPress Coding Standards:** Adheres to WordPress PHP and JavaScript coding standards.
+-   **Security:** Implements security best practices, including data sanitization, validation, and nonce verification.
+-   **Performance:** Optimized for performance with efficient queries and asset management.
+-   **Accessibility:** Follows WCAG guidelines for accessible user interfaces.
+-   **Internationalization:** Uses WordPress internationalization functions for translatable strings.
+-   **Modular Design:** Code is organized into modules with clear separation of concerns.
+-   **Object-Oriented Programming (PHP):** Utilizes OOP principles in PHP codebase.
+-   **React and `@wordpress/scripts` (JavaScript):** Uses modern React practices and WordPress `@wordpress/scripts` build tooling for JavaScript development.
+
+## Important File Locations
+
+-   **Plugin Entry Point:** `content-control.php`
+-   **Main Plugin Class:** `classes/Plugin/Core.php`
+-   **Rule Engine Classes:** `classes/RuleEngine/`
+-   **Restriction Model:** `classes/Models/Restriction.php`
+-   **Settings Page React App:** `packages/settings-page/src/App.tsx`
+-   **Block Editor Integration:** `packages/block-editor/src/`
+-   **Core Data Stores:** `packages/core-data/src/`
+-   **Reusable Components:** `packages/components/src/`
+-   **Documentation Files:** `docs/`