Refine handling of fictioneer_chapters_added meta

This controls the order of stories in the Latest Updates shortcodes and Stories template. Up to this point, it had been updated a bit too often and could cause confusion in the order of stories.

CUSTOMIZE.md

@@ -359,7 +359,7 @@ If the "Next Chapter" note above the chapter list is not enough and you want to
 
 ```php
 /**
- * Show scheduled (future) chapter in story chapter list
+ * Shows scheduled (future) chapter in story chapter list
  *
  * @since x.x.x
  *
@@ -378,7 +378,7 @@ add_filter( 'fictioneer_filter_story_chapter_posts_query', 'child_show_scheduled
 // If you want to remove the "Next Chapter" note above the list:
 
 /**
- * Remove "Next Chapter" note above list
+ * Removes "Next Chapter" note above list
  *
  * @since x.x.x
  */
@@ -387,6 +387,24 @@ function child_remove_scheduled_chapter() {
   remove_action( 'fictioneer_story_after_content', 'fictioneer_story_scheduled_chapter', 41 );
 }
 add_action( 'wp', 'child_remove_scheduled_chapter', 11 ); // The action is added late, so you need to be even later
+
+// If you want scheduled chapters to be considered a story update,
+// which is important for the Stories page template and shortcodes:
+
+/**
+ * Adds the 'future' post status to the update allow list
+ *
+ * Note: Hidden chapters are still ignored.
+ *
+ * @since x.x.x
+ */
+
+function child_consider_scheduled_chapters_as_update( $statuses ) {
+  $statuses[] = 'future';
+
+  return $statuses;
+}
+add_action( 'fictioneer_filter_chapters_added_statuses', 'child_consider_scheduled_chapters_as_update' );
 ```
 
 ## Modify or remove items from card footers

FILTERS.md

@@ -79,7 +79,7 @@ Filters the array of allowed orderby arguments for WP_Query.
 ---
 
 ### `apply_filters( 'fictioneer_filter_append_chapter_to_story_statuses', $statuses, $post_id, $story_id, $force )`
-Filters the array of chapter statuses that can be appended to a story’s `fictioneer_story_chapters` metadata in the `fictioneer_append_chapter_to_story()` function. By default, the statuses are `['publish']`.
+Filters the array of chapter statuses that can be auto-appended to a story’s `fictioneer_story_chapters` metadata in the `fictioneer_append_chapter_to_story()` function. By default, the statuses are `['publish', 'future']`.
 
 **Parameters:**
 * $statuses (array) – Array of chapter statuses.
@@ -413,6 +413,15 @@ Filters the array of chapter statuses that can be appended to a story’s `index
 
 ---
 
+### `apply_filters( 'fictioneer_filter_chapters_added_statuses', $statuses, $story_id )`
+Filters the array of chapter statuses that are eligible to update the `fictioneer_chapters_modified` story meta field in several functions. By default, the statuses are `['publish']`. Note that hidden chapters (meta flag) will still be ignored regardless of status since they are not listed.
+
+**Parameters:**
+* $statuses (array) – Array of chapter statuses.
+* $story_id (int) – The story post ID.
+
+---
+
 ### `apply_filters( 'fictioneer_filter_chapters_card_args', $card_args, $args )`
 Filters the arguments passed to the `partials/_card-chapter` template part in the `fictioneer_chapters_list( $args )` function, normally added via the `fictioneer_chapters_after_content` hook.
 

includes/functions/_service-posts.php

@@ -333,7 +333,12 @@ add_action( 'private_to_draft', 'fictioneer_chapter_to_draft' );
 
 function fictioneer_chapter_future_to_publish( $new_status, $old_status, $post ) {
   // Validate transition...
-  if ( $post->post_type !== 'fcn_chapter' || $old_status !== 'future' || $new_status !== 'publish' ) {
+  if (
+    $post->post_type !== 'fcn_chapter' ||
+    $old_status !== 'future' ||
+    $new_status !== 'publish' ||
+    get_post_meta( $post->ID, 'fictioneer_chapter_hidden', true )
+  ) {
     return;
   }
 

includes/functions/_setup-meta-fields.php

@@ -2390,8 +2390,43 @@ function fictioneer_save_story_metaboxes( $post_id ) {
       update_post_meta( $post_id, 'fictioneer_chapters_modified', current_time( 'mysql', true ) );
     }
 
-    if ( count( $previous_chapter_ids ) < count( $chapter_ids ) ) {
+    // Remember when chapters have been added
-      update_post_meta( $post_id, 'fictioneer_chapters_added', current_time( 'mysql', true ) );
+    $chapter_diff = array_diff( $chapter_ids, $previous_chapter_ids );
+
+    if ( ! empty( $chapter_diff ) ) {
+      $allowed_statuses = apply_filters(
+        'fictioneer_filter_chapters_added_statuses',
+        ['publish'],
+        $post_id
+      );
+
+      $new_chapters = new WP_Query(
+        array(
+          'post_type' => 'fcn_chapter',
+          'post_status' => $allowed_statuses,
+          'post__in' => $chapter_diff,
+          'fields' => 'ids',
+          'posts_per_page' => 10, // Sensible limit in case of bulks
+          'update_post_meta_cache' => true,
+          'update_post_term_cache' => false, // Improve performance
+          'no_found_rows' => true // Improve performance
+        )
+      );
+
+      if ( $new_chapters->have_posts() ) {
+        $valid_new_chapters = false;
+
+        foreach ( $new_chapters->posts as $chapter_id ) {
+          if ( ! get_post_meta( $chapter_id, 'fictioneer_chapter_hidden', true ) ) {
+            $valid_new_chapters = true;
+            break;
+          }
+        }
+
+        if ( $valid_new_chapters ) {
+          update_post_meta( $post_id, 'fictioneer_chapters_added', current_time( 'mysql', true ) );
+        }
+      }
     }
 
     // Log changes

includes/functions/_utility.php

@@ -1422,7 +1422,7 @@ function fictioneer_get_falsy_meta_allow_list() {
 function fictioneer_append_chapter_to_story( $post_id, $story_id, $force = false ) {
   $allowed_statuses = apply_filters(
     'fictioneer_filter_append_chapter_to_story_statuses',
-    ['publish'],
+    ['publish', 'future'],
     $post_id,
     $story_id,
     $force
@@ -1462,9 +1462,21 @@ function fictioneer_append_chapter_to_story( $post_id, $story_id, $force = false
     // Save updated list
     update_post_meta( $story_id, 'fictioneer_story_chapters', $story_chapters );
 
-    // Remember when chapter list has been last updated
+    // Remember when chapters have been changed
     update_post_meta( $story_id, 'fictioneer_chapters_modified', current_time( 'mysql', true ) );
-    update_post_meta( $story_id, 'fictioneer_chapters_added', current_time( 'mysql', true ) );
+
+    // Remember when chapters have been added
+    $allowed_statuses = apply_filters(
+      'fictioneer_filter_chapters_added_statuses',
+      ['publish'],
+      $post_id
+    );
+
+    if ( in_array( get_post_status( $post_id ), $allowed_statuses ) ) {
+      if ( ! get_post_meta( $post_id, 'fictioneer_chapter_hidden', true ) ) {
+        update_post_meta( $story_id, 'fictioneer_chapters_added', current_time( 'mysql', true ) );
+      }
+    }
 
     // Log changes
     fictioneer_log_story_chapter_changes( $story_id, $story_chapters, $previous_chapters );