JezK

Edit File: SavedForLater.php

<?php

declare( strict_types = 1 );

namespace Automattic\WooCommerce\Blocks\BlockTypes;

use Automattic\WooCommerce\Blocks\Utils\BlocksSharedState;
use Automattic\WooCommerce\Internal\ShopperLists\ShopperListRenderer;
use Automattic\WooCommerce\Proxies\LegacyProxy;

/**
 * Saved for Later block.
 *
 * Renders the shopper's "Saved for Later" list, wired to the `shopper-lists`
 * Store API endpoints via the shared `woocommerce/shopper-lists` iAPI store.
 * PHP prefetches the list so the first paint is already populated; JS then
 * takes over for adds, removes, and Move-to-cart.
 *
 * The row markup (image, name, price, remove badge, variation overlay) is
 * shared with other shopper-list blocks via `ShopperListRenderer`. This
 * class composes those fragments and adds the bits that are unique to
 * Saved for Later: auto-injection via the Block Hooks API, the
 * `hasShownItems` empty-state gating, the per-row quantity span, and the
 * Move-to-cart action button.
 */
final class SavedForLater extends AbstractBlock {
	/**
	 * The list slug this block renders. Constant — when additional list
	 * types ship as their own blocks (e.g. Wishlist), each one will
	 * hardcode its own slug.
	 */
	private const LIST_SLUG = 'saved-for-later';

/**
	 * Block name.
	 *
	 * @var string
	 */
	protected $block_name = 'saved-for-later';

/**
	 * Initialize this block type.
	 */
	protected function initialize(): void {
		parent::initialize();

// We do not use `BlockHooksTrait` currently as it has issues with PHPStan.
		add_filter( 'hooked_block_types', array( $this, 'register_hooked_block' ), 9, 4 );
		add_filter( 'hooked_block_woocommerce/saved-for-later', array( $this, 'set_hooked_block_attributes' ), 10, 4 );
	}

/**
	 * Auto-inject this block after `woocommerce/cart`, scoped to the cart page.
	 *
	 * @param array                                  $hooked_block_types Block names hooked at this position.
	 * @param string                                 $relative_position  Position of the insertion point.
	 * @param string                                 $anchor_block_type  Anchor block name.
	 * @param array|\WP_Post|\WP_Block_Template|null $context            Where the block is being embedded.
	 * @return array
	 */
	public function register_hooked_block( $hooked_block_types, $relative_position, $anchor_block_type, $context ) {
		if ( 'after' !== $relative_position || 'woocommerce/cart' !== $anchor_block_type ) {
			return $hooked_block_types;
		}

// `wc_get_page_id()` returns -1 when the page option isn't set.
		$cart_page_id = (int) wc_get_page_id( 'cart' );
		if ( $cart_page_id <= 0 || ! ( $context instanceof \WP_Post ) || (int) $context->ID !== $cart_page_id ) {
			return $hooked_block_types;
		}

// Don't double-inject if the block is already in the cart page
		// content.
		if ( has_block( $this->get_full_block_name(), $context ) ) {
			return $hooked_block_types;
		}

$hooked_block_types[] = $this->get_full_block_name();
		return $hooked_block_types;
	}

/**
	 * Seed a default heading inner block on the auto-injected block.
	 *
	 * @param array|null $parsed_hooked_block The parsed hooked block array, or null to suppress insertion.
	 * @param string     $hooked_block_type   The hooked block type name.
	 * @param string     $relative_position   Position of the insertion point.
	 * @param array      $parsed_anchor_block The anchor block, in parsed block array format.
	 * @return array|null
	 */
	public function set_hooked_block_attributes( $parsed_hooked_block, $hooked_block_type, $relative_position, $parsed_anchor_block ) {
		if ( null === $parsed_hooked_block || 'after' !== $relative_position ) {
			return $parsed_hooked_block;
		}
		if ( ! isset( $parsed_anchor_block['blockName'] ) || 'woocommerce/cart' !== $parsed_anchor_block['blockName'] ) {
			return $parsed_hooked_block;
		}

// Seed a `core/heading` inner block so freshly-injected instances
		// ship with the same heading the editor template seeds. We append
		// unconditionally — extensions are free to hook
		// `hooked_block_woocommerce/saved-for-later` to add their own
		// inner blocks, and gating on `empty( innerBlocks )` would silently
		// suppress our heading whenever any other extension ran first.
		//
		// `core/heading` is a static block, so the serialised markup must
		// match what the editor would have saved (`<h2 class="wp-block-heading">…</h2>`)
		// or it'll fail block validation when the cart page is opened in the
		// editor. `attrs.content` mirrors what the editor's template seeds
		// (`{ content, level }`) so the parsed shape round-trips identically;
		// the value is the raw string because attrs are JSON-encoded into the
		// block comment and `esc_html()` would corrupt translations whose text
		// contains `&`, `<`, etc. The matching `null` push onto `innerContent`
		// is what makes `WP_Block::render()` walk into the heading when
		// building `$content`.
		$list_heading = __( 'Saved for later', 'woocommerce' );
		$heading_html = '<h2 class="wp-block-heading">' . esc_html( $list_heading ) . '</h2>';

if ( ! isset( $parsed_hooked_block['innerBlocks'] ) || ! is_array( $parsed_hooked_block['innerBlocks'] ) ) {
			$parsed_hooked_block['innerBlocks'] = array();
		}
		$parsed_hooked_block['innerBlocks'][] = array(
			'blockName'    => 'core/heading',
			'attrs'        => array(
				'level'   => 2,
				'content' => $list_heading,
			),
			'innerBlocks'  => array(),
			'innerHTML'    => $heading_html,
			'innerContent' => array( $heading_html ),
		);
		if ( ! isset( $parsed_hooked_block['innerContent'] ) || ! is_array( $parsed_hooked_block['innerContent'] ) ) {
			$parsed_hooked_block['innerContent'] = array();
		}
		$parsed_hooked_block['innerContent'][] = null;

return $parsed_hooked_block;
	}

/**
	 * Render the block.
	 *
	 * @param array     $attributes Block attributes.
	 * @param string    $content    Block content.
	 * @param \WP_Block $block      Block instance.
	 * @return string Rendered block type output.
	 */
	protected function render( $attributes, $content, $block ) {
		// Guests have no personal list — bail before enqueuing assets or seeding state.
		if ( ! is_user_logged_in() ) {
			return '';
		}

// Set from render() (not Cart::enqueue_data via has_block()) so it works when this
		// block is auto-injected via the Block Hooks API and isn't in stored post_content.
		if ( wc_get_container()->get( LegacyProxy::class )->call_function( 'is_cart' ) ) {
			$this->asset_data_registry->add( 'cartPageHasSavedForLater', true );
		}

// Clamp to the 2-6 range the SCSS `@for $i from 2 through 6` loop and
		// the editor `RangeControl` both support. `absint()` first defends
		// against a code-editor override (the attribute can be set to any
		// JSON value there); the `min`/`max` then keep the value within the
		// range where a `&.columns-#{$i}` rule actually exists.
		$column_count = min( 6, max( 2, absint( $attributes['columnCount'] ?? 5 ) ) );

wp_enqueue_script_module( $this->get_full_block_name() );

$consent = 'I acknowledge that using private APIs means my theme or plugin will inevitably break in the next version of WooCommerce';
		BlocksSharedState::load_store_config( $consent );
		BlocksSharedState::load_placeholder_image( $consent );
		// `Move to cart` calls into the shared cart store, which expects
		// `state.cart.items` and friends. Without this load the cart store
		// would have no hydrated cart and the action would throw on the
		// first click.
		BlocksSharedState::load_cart_state( $consent );

$items = $this->prefetch_items();

// Seed the shared shopper-lists store with the rest URL, the
		// pre-fetched items, and a starter nonce. The starter nonce is
		// what the cart store also seeds via `state.nonce` — the JS layer
		// keeps it fresh by reading the `Nonce` response header on every
		// subsequent request, so this is just the bootstrap value (and
		// avoids deadlocking mutations that await `isNonceReady` before
		// any GET has fired).
		wp_interactivity_state(
			'woocommerce/shopper-lists',
			array(
				'restUrl' => get_rest_url(),
				'nonce'   => wp_create_nonce( 'wc_store_api' ),
				'lists'   => array(
					self::LIST_SLUG => array(
						'items'     => $items,
						'isLoading' => false,
					),
				),
			)
		);

// Templates flow through `wp_interactivity_config` so the JS-side
		// getters can interpolate them (`%d`, `%s`). Visible strings (empty
		// state, error, action label) are rendered server-side and toggled
		// with directives, so they don't need to ride here too.
		wp_interactivity_config(
			'woocommerce/saved-for-later',
			array(
				'quantityLabelTemplate' => $this->get_quantity_label_template(),
				'removeLabelTemplate'   => $this->get_remove_label_template(),
			)
		);

// `hasShownItems` seeds the per-block context so the empty message
		// stays hidden for new shoppers who land on a page with nothing
		// saved. The JS-side watcher flips it to `true` the first time the
		// list has any items (whether that's the SSR seed or a runtime add
		// via "Save for later"), and `state.isEmpty` only flips on when the
		// flag is set *and* the list is currently empty. The flag lives in
		// the per-block context, so it naturally resets on every full page
		// load — no extra Store API field or persisted flag needed.
		// `data-wp-context---notices` seeds the store-notices namespace
		// alongside the block's own context on the same wrapper.
		$wrapper_attributes = array(
			'class'                     => 'wc-block-saved-for-later',
			'data-wp-interactive'       => 'woocommerce/saved-for-later',
			'data-wp-context'           => (string) wp_json_encode(
				array(
					'hasShownItems' => ! empty( $items ),
					// `stdClass` so it serialises as `{}`, not `[]` —
					// iAPI's reactive proxy only fires updates on object
					// writes, not array expandos.
					'pendingKeys'   => new \stdClass(),
				)
			),
			'data-wp-context---notices' => 'woocommerce/store-notices::' . (string) wp_json_encode( array( 'notices' => array() ) ),
			'data-wp-watch'             => 'callbacks.trackShownItems',
		);

$list_class = sprintf( 'wc-block-saved-for-later__list columns-%d', $column_count );

$ul_inner    = $this->render_template_markup() . $this->render_items_markup( $items ) . $this->render_empty_markup();
		$before_list = $this->render_header_markup( $content, empty( $items ) ) . ShopperListRenderer::render_interactivity_notices_region( 'wc-block-saved-for-later__notices' );

return ShopperListRenderer::render_grid_wrapper( $wrapper_attributes, $list_class, $ul_inner, $before_list );
	}

/**
	 * Prefetch the saved-for-later items via `rest_do_request()`. Logged-out
	 * users short-circuit to an empty list — the route requires authentication
	 * and we don't want to fire an API call that's only going to 401.
	 *
	 * @return array<int, array<string, mixed>> Items in the schema response shape.
	 */
	private function prefetch_items(): array {
		if ( ! is_user_logged_in() ) {
			return array();
		}

$request  = new \WP_REST_Request( 'GET', '/wc/store/v1/shopper-lists/' . self::LIST_SLUG . '/items' );
		$response = rest_do_request( $request );

if ( $response->is_error() ) {
			$error   = $response->as_error();
			$message = $error instanceof \WP_Error ? $error->get_error_message() : 'Unknown error';
			// Logged at debug level on purpose: prefetch failures are
			// often transient (network blips, auth refresh races) and
			// the user-visible behaviour is the empty state — nothing
			// for ops to act on. Anyone investigating a regression can
			// flip the WC logger to debug to surface them.
			wc_get_logger()->debug(
				sprintf( 'Saved for Later prefetch failed: %s', $message ),
				array(
					'source' => 'saved-for-later',
					'data'   => array( 'slug' => self::LIST_SLUG ),
				)
			);
			return array();
		}

$data = $response->get_data();
		if ( ! is_array( $data ) && ! is_object( $data ) ) {
			return array();
		}

// The schema casts `prices` and image entries to stdClass so the
		// JSON response renders objects, not arrays. Round-trip through
		// JSON encode/decode to normalise everything to nested arrays so
		// the SSR markup helpers below can treat fields uniformly.
		$decoded = json_decode( (string) wp_json_encode( $data ), true );
		return is_array( $decoded ) ? $decoded : array();
	}

/**
	 * The `<template data-wp-each>` describing how each item is rendered on
	 * the client. Pre-rendered children sit alongside as `data-wp-each-child`
	 * elements so first paint is populated. Composes the shared row markup
	 * with Saved for Later's quantity span and Move-to-cart action button.
	 *
	 * @return string
	 */
	private function render_template_markup(): string {
		$row_inner = ShopperListRenderer::render_template_common_row()
			. $this->render_template_quantity()
			. $this->render_template_move_to_cart();
		return ShopperListRenderer::render_each_template( $row_inner );
	}

/**
	 * Render the SSR markup for each item. JS will reconcile these via
	 * `data-wp-each-child` after hydration.
	 *
	 * @param array<int, array<string, mixed>> $items Schema-shape items.
	 * @return string
	 */
	private function render_items_markup( array $items ): string {
		$markup = '';
		foreach ( $items as $item ) {
			$markup .= $this->render_item_markup( $item );
		}
		return $markup;
	}

/**
	 * Render a single SSR item. Composes the shared image / name / price
	 * markup with the SFL-specific quantity span and Move-to-cart button.
	 *
	 * @param array<string, mixed> $item Schema-shape item.
	 * @return string
	 */
	private function render_item_markup( array $item ): string {
		$row_inner = ShopperListRenderer::render_ssr_common_row( $item, $this->get_remove_label_template() )
			. $this->render_ssr_quantity( $item )
			. $this->render_ssr_move_to_cart( $item );
		return ShopperListRenderer::render_each_child( $item, $row_inner );
	}

/**
	 * Template-mode markup for the quantity span. SFL-specific — Wishlist
	 * has no quantity column.
	 *
	 * @return string
	 */
	private function render_template_quantity(): string {
		return sprintf(
			'<span class="%s__quantity" data-wp-text="state.currentItemQuantityLabel"></span>',
			esc_attr( ShopperListRenderer::ROW_CLASS )
		);
	}

/**
	 * Template-mode markup for the Move-to-cart action button. SFL-specific.
	 *
	 * @return string
	 */
	private function render_template_move_to_cart(): string {
		ob_start();
		?>
		<div class="wp-block-button wc-block-components-product-button" data-wp-bind--hidden="state.isMoveToCartHidden">
			<button
				type="button"
				class="wp-block-button__link wp-element-button add_to_cart_button wc-block-components-product-button__button"
				data-wp-on--click="actions.onClickMoveToCart"
				data-wp-bind--disabled="state.isCurrentItemPending"
			>
				<?php echo esc_html( $this->get_move_to_cart_label() ); ?>
			</button>
		</div>
		<?php
		return (string) ob_get_clean();
	}

/**
	 * SSR-mode markup for the quantity span. SFL-specific.
	 *
	 * @param array<string, mixed> $item Schema-shape item.
	 * @return string
	 */
	private function render_ssr_quantity( array $item ): string {
		$quantity       = (int) ( $item['quantity'] ?? 1 );
		$quantity_label = sprintf( $this->get_quantity_label_template(), $quantity );
		return sprintf(
			'<span class="%s__quantity">%s</span>',
			esc_attr( ShopperListRenderer::ROW_CLASS ),
			esc_html( $quantity_label )
		);
	}

/**
	 * SSR-mode markup for the Move-to-cart action button. SFL-specific.
	 * Always emits the wrapper so iAPI can toggle `hidden` after hydration
	 * without swapping the row out. Starts hidden when the row isn't
	 * purchasable.
	 *
	 * @param array<string, mixed> $item Schema-shape item.
	 * @return string
	 */
	private function render_ssr_move_to_cart( array $item ): string {
		$is_move_to_cart_hidden = empty( $item['is_purchasable'] );
		ob_start();
		?>
		<div
			class="wp-block-button wc-block-components-product-button"
			data-wp-bind--hidden="state.isMoveToCartHidden"
			<?php
			if ( $is_move_to_cart_hidden ) {
				echo 'hidden';
			}
			?>
		>
			<button
				type="button"
				class="wp-block-button__link wp-element-button add_to_cart_button wc-block-components-product-button__button"
				data-wp-on--click="actions.onClickMoveToCart"
				data-wp-bind--disabled="state.isCurrentItemPending"
			>
				<?php echo esc_html( $this->get_move_to_cart_label() ); ?>
			</button>
		</div>
		<?php
		return (string) ob_get_clean();
	}

/**
	 * Wrap the inner-block content (heading + any future siblings) in an
	 * element whose visibility mirrors the empty-state gating: hidden when
	 * the shopper has never seen items in this session, revealed once
	 * `context.hasShownItems` flips to `true`. Returns an empty string when
	 * there's no content to wrap (e.g. merchant deleted the heading and
	 * saved), so we don't emit an empty `<div>`.
	 *
	 * @param string $content  Rendered inner-block content (typically the heading HTML).
	 * @param bool   $is_empty Whether the saved-for-later list is empty on initial paint.
	 * @return string
	 */
	private function render_header_markup( string $content, bool $is_empty ): string {
		if ( '' === $content ) {
			return '';
		}
		$hidden_attr = $is_empty ? ' hidden' : '';
		return sprintf(
			'<div class="wc-block-saved-for-later__header" data-wp-bind--hidden="!context.hasShownItems"%s>%s</div>',
			$hidden_attr,
			$content
		);
	}

/**
	 * Render the empty-state markup. Always present in the DOM so JS can
	 * toggle it on once the last item is removed. Initially hidden: SSR
	 * never shows the message, since `state.isEmpty` requires the JS-side
	 * `hasShownItems` context flag to flip first.
	 *
	 * @return string
	 */
	private function render_empty_markup(): string {
		return ShopperListRenderer::render_empty_state(
			__( 'Nothing saved yet — items you save from the cart will appear here.', 'woocommerce' ),
			'wc-block-saved-for-later__empty',
			true
		);
	}

/**
	 * Sprintf template for the per-row quantity label. Used both by PHP SSR
	 * (`render_ssr_quantity()`) and by the JS-side getter (via
	 * `wp_interactivity_config`) so both paths produce the same string after
	 * `%d` interpolation.
	 */
	private function get_quantity_label_template(): string {
		/* translators: %d: quantity of saved items. */
		return __( 'Quantity: %d', 'woocommerce' );
	}

/**
	 * Sprintf template for the per-row remove button's aria-label. Same dual
	 * use as the quantity template.
	 */
	private function get_remove_label_template(): string {
		/* translators: %s: product name. */
		return __( 'Remove %s from Saved for later list', 'woocommerce' );
	}

/**
	 * Visible label for the move-to-cart action button, used by both the
	 * iAPI `<template>` and the SSR per-row markup.
	 */
	private function get_move_to_cart_label(): string {
		return __( 'Move to cart', 'woocommerce' );
	}

/**
	 * Get the frontend script handle for this block type.
	 *
	 * Scripts are loaded via `viewScriptModule` in block.json.
	 *
	 * @param string|null $key The key of the script to get.
	 * @return null
	 */
	protected function get_block_type_script( $key = null ) {
		return null;
	}

/**
	 * Get the frontend style handle for this block type.
	 *
	 * Returning null lets WP use the `style` array from block.json, which
	 * lists this block's own stylesheet plus the atomic
	 * product-image / product-price / product-button stylesheets we
	 * borrow class names from. We can't render those atomic blocks as
	 * inner blocks (they rely on WP_Query / $post loop context, which
	 * this block doesn't have — it hydrates from a Store API call), so
	 * declaring them as style dependencies is the only way to get WP
	 * to enqueue their CSS whenever Saved for Later renders.
	 *
	 * @return null
	 */
	protected function get_block_type_style() {
		return null;
	}

/**
	 * Disable the editor style handle for this block type.
	 *
	 * @return null
	 */
	protected function get_block_type_editor_style() {
		return null;
	}
}