Merge pull request #2 from humanmade/post-context-consumer

Post template count override

Author: roborourke

.github/workflows/playwright-tests.yml

@@ -62,7 +62,7 @@ jobs:
         if: always()
         with:
           name: playwright-report
-          path: playwright-report/
+          path: test-results/
           retention-days: 30
           if-no-files-found: ignore
 

.gitignore

@@ -30,3 +30,9 @@ playwright-report/
 playwright/.cache/
 
 /vendor/
+
+# Playwright
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/playwright/.auth/

CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+HM Query Loop is a WordPress plugin that extends the core Query Loop block with advanced controls for managing multiple query loops on a single page. It provides three main features: posts per page override for inherited queries, hide on paginated pages, and exclude already displayed posts.
+
+## Development Commands
+
+### Build and Development
+- `npm run start` - Start development build with watch mode
+- `npm run build` - Create production build (required before testing)
+- `npm run lint:js` - Lint JavaScript files
+- `npm run lint:css` - Lint CSS/SCSS files
+- `npm run format` - Format all files
+
+### Testing
+- `npm run wp-env start` - Start WordPress test environment (ports 8888 dev, 8889 tests)
+- `npm run test:e2e` - Run Playwright end-to-end tests
+- `npm run test:e2e:debug` - Run tests in debug mode
+- `npm run test:e2e:watch` - Run tests in watch mode (reruns on changes)
+- `npm run wp-env stop` - Stop WordPress environment
+
+**Important**: Always run `npm run build` before running tests, as tests run against built assets.
+
+## Architecture
+
+### Block Extension Approach
+The plugin uses WordPress block filters to extend the `core/query` block without creating a custom block variant. This allows it to work with any Query Loop block while preserving core functionality.
+
+### Context System
+The plugin exposes a `hm-query-loop/settings` context object from `core/query` to `core/post-template`:
+```js
+{
+  perPage: number | undefined,      // Custom posts per page value
+  hideOnPaged: boolean,             // Whether to hide on paginated pages
+  excludeDisplayed: boolean         // Whether to exclude displayed posts
+}
+```
+
+Context is registered in both JavaScript (via `blocks.registerBlockType` filters in src/index.js) and PHP (via `filter_block_metadata` in hm-query-loop.php).
+
+### Dual Query Modification Strategy
+
+The plugin handles two different query scenarios:
+
+**For Inherited Queries** (uses main WP_Query):
+- `pre_render_block` - Captures block attributes, checks pagination visibility, re-runs main query with modified args
+- Main query is modified before rendering to apply settings
+- `render_block` - Returns empty string if block should be hidden on paginated pages
+
+**For Non-Inherited Queries** (custom WP_Query):
+- `query_loop_block_query_vars` filter - Passes block attributes into WP_Query vars
+- This filter only fires for non-inherited queries, which is why the dual approach is necessary
+
+### Post Tracking
+- `the_posts` filter tracks displayed post IDs across all query loops on a page
+- Global `$displayed_post_ids` array accumulates IDs from rendered query loops
+- Subsequent query loops with `excludeDisplayed` enabled filter out tracked IDs via `post__not_in`
+
+### Editor Preview Synchronization
+In src/index.js, a `useEffect` hook syncs the `hmQueryLoop.perPage` attribute to `query.perPage` to reflect the override in the editor preview. The `withPostTemplateStyles` filter adds inline CSS to hide excess posts in the editor beyond the `perPage` limit.
+
+## Key Files
+
+- `hm-query-loop.php` - Main plugin file with all PHP hooks and query modification logic
+- `src/index.js` - Block filters for adding inspector controls and editor preview behavior
+- `tests/e2e/posts-per-page.spec.js` - E2E tests for posts per page functionality
+- `tests/e2e/fixtures.js` - Playwright test fixtures for WordPress admin
+
+## Testing Environment
+
+Tests use `@wordpress/env` with WordPress 6.7.1, configured in `.wp-env.json`. The environment includes TwentyTwentyFour and TwentyTwentyFive themes. Tests run on port 8889 and use Playwright with `@wordpress/e2e-test-utils-playwright`.
+
+## Important Implementation Notes
+
+- The plugin modifies queries without creating database entries or custom post types
+- All settings are stored as block attributes in post content
+- The `$original_paged` global preserves the original pagination state when blocks override it
+- Hidden blocks (via `hideOnPaged`) still track their post IDs for exclusion purposes
+- The plugin works with both FSE templates and classic posts/pages

hm-query-loop.php

@@ -35,10 +35,10 @@ function init() {
 	add_filter( 'pre_render_block', __NAMESPACE__ . '\\pre_render_block', 10, 3 );
 	add_filter( 'render_block', __NAMESPACE__ . '\\render_block', 10, 2 );
 
-	// Hook pre_get_posts to modify the query.
+	// Hook query_loop_block_query_vars to modify the query.
 	add_filter( 'query_loop_block_query_vars',  __NAMESPACE__ . '\\filter_query_loop_block_query_vars', 10, 2 );
 
-	// Hook into the_posts to track displayed posts.
+	// Hook into the_posts to track displayed posts and limit post-template posts.
 	add_filter( 'the_posts', __NAMESPACE__ . '\\track_displayed_posts', 10, 2 );
 
 	// Add contexts to query and post-template block.
@@ -109,6 +109,14 @@ function filter_block_metadata( $metadata ) {
  */
 $displayed_post_ids = [];
 
+/**
+ * Track used post IDs within each query loop block.
+ * Keyed by block ID to scope posts to each query loop.
+ *
+ * @var array
+ */
+$query_loop_used_posts = [];
+
 /**
  * Get displayed post IDs.
  *
@@ -132,6 +140,31 @@ function add_displayed_post_ids( $post_ids ) {
 	$displayed_post_ids = array_unique( array_merge( $displayed_post_ids, $post_ids ) );
 }
 
+/**
+ * Get used post IDs for a specific query loop.
+ *
+ * @param string $query_id Query loop block ID.
+ * @return array
+ */
+function get_query_loop_used_posts( $query_id ) {
+	global $query_loop_used_posts;
+	return $query_loop_used_posts[ $query_id ] ?? [];
+}
+
+/**
+ * Add used post IDs for a specific query loop.
+ *
+ * @param string $query_id Query loop block ID.
+ * @param array  $post_ids Post IDs to add.
+ */
+function add_query_loop_used_posts( $query_id, $post_ids ) {
+	global $query_loop_used_posts;
+	if ( ! isset( $query_loop_used_posts[ $query_id ] ) ) {
+		$query_loop_used_posts[ $query_id ] = [];
+	}
+	$query_loop_used_posts[ $query_id ] = array_unique( array_merge( $query_loop_used_posts[ $query_id ], $post_ids ) );
+}
+
 /**
  * Pre-render block callback.
  *
@@ -178,7 +211,6 @@ function pre_render_block( $pre_render, $parsed_block ) {
  * @return string Block content.
  */
 function render_block( $block_content, $block ) {
-	// Only process core/query blocks.
 	if ( 'core/query' !== $block['blockName'] ) {
 		return $block_content;
 	}
@@ -204,6 +236,14 @@ function render_block( $block_content, $block ) {
  * @return array The modified query vars.
  */
 function filter_query_loop_block_query_vars( $query, WP_Block $block ) {
+	if ( $block->name === 'core/post-template' ) {
+		$attrs = $block->parsed_block['attrs'];
+		if ( empty( $attrs['hmQueryLoop']['perPage'] ) ) {
+			return $query;
+		}
+		$attrs['hmQueryLoop']['excludeDisplayedForCurrentLoop'] = $block->context['queryId'];
+		return modify_query_from_block_attrs( $query, $attrs );
+	}
 	return modify_query_from_block_attrs( $query, $block->context );
 }
 
@@ -248,6 +288,19 @@ function modify_query_from_block_attrs( $query = [], $attrs = [] ) {
 		}
 	}
 
+	// Exclude already displayed posts for this loop if enabled.
+	if ( isset( $settings['excludeDisplayedForCurrentLoop'] ) ) {
+		$query['query_id'] = $settings['excludeDisplayedForCurrentLoop'];
+		$displayed_ids = get_query_loop_used_posts( $settings['excludeDisplayedForCurrentLoop'] );
+		if ( ! empty( $displayed_ids ) ) {
+			$existing_exclusions = $query['post__not_in'] ?? [];
+			if ( ! is_array( $existing_exclusions ) ) {
+				$existing_exclusions = [];
+			}
+			$query['post__not_in'] = array_unique( array_merge( $existing_exclusions, $displayed_ids ) );
+		}
+	}
+
 	return $query;
 }
 
@@ -267,6 +320,7 @@ function track_displayed_posts( $posts, $query ) {
 	if ( ! empty( $posts ) ) {
 		$post_ids = wp_list_pluck( $posts, 'ID' );
 		add_displayed_post_ids( $post_ids );
+		add_query_loop_used_posts( $query->get( 'query_id', -1 ), $post_ids );
 	}
 
 	return $posts;