chromed

Back Back Up Advanced Editor

<?php

namespace WPForms\Integrations\AI\Admin\Chat;

/**
 * Abstract base for AI Chat surfaces.
 *
 * A surface aggregates scope contributions into the full context dict shipped
 * to the middleware (`page_state` + `surface_state` namespaced by scope slug).
 *
 * @since 2.0.0
 */
abstract class SurfaceBase {

/**
	 * Surface slug. Concrete classes define `public const SLUG = '...'`.
	 *
	 * @since 2.0.0
	 *
	 * @return string
	 */
	public function get_slug(): string {

return (string) static::SLUG;
	}

/**
	 * Capability required to view this surface.
	 *
	 * @since 2.0.0
	 *
	 * @return string
	 */
	abstract public function get_capability(): string;

/**
	 * Default scopes active on this surface.
	 *
	 * @since 2.0.0
	 *
	 * @return array
	 */
	abstract public function get_default_scopes(): array;

/**
	 * Color scheme.
	 *
	 * @since 2.0.0
	 *
	 * @return string
	 */
	public function get_color_scheme(): string {

return 'light';
	}

/**
	 * Admin body class appended when this surface is active.
	 *
	 * @since 2.0.0
	 *
	 * @return string
	 */
	public function get_body_class(): string {

return 'wpforms-admin-chat-active';
	}

/**
	 * Whether this surface is enabled.
	 *
	 * @since 2.0.0
	 *
	 * @return bool
	 */
	public function is_enabled(): bool {

return true;
	}

/**
	 * Path to the surface's JS module relative to the chat-element directory.
	 *
	 * Returning `null` (the default) means this surface does not register
	 * a JS module — the chat's `surface-admin` fallback is used. Concrete
	 * surfaces override this to ship surface-specific page-state and
	 * sample-prompts logic.
	 *
	 * @since 2.0.0
	 *
	 * @return string|null Path string (relative to the chat-element JS dir) or null.
	 */
	public function get_js_module(): ?string {

return null;
	}

/**
	 * Helper-name slug used to register the surface module in `WPFormsAi.helpers`.
	 *
	 * Convention: `surface{StudlyCaseSlug}` — e.g. `wpforms-overview` →
	 * `surfaceWpformsOverview`. This is the key the chat element looks up
	 * when resolving `admin.surface`.
	 *
	 * @since 2.0.0
	 *
	 * @return string The helper name.
	 */
	public function get_js_helper_name(): string {

$slug  = $this->get_slug();
		$parts = array_map( 'ucfirst', explode( '-', $slug ) );

return 'surface' . implode( '', $parts );
	}

/**
	 * Initialize: self-register into the surface registry, then run hooks().
	 *
	 * @since 2.0.0
	 */
	public function init(): void {

$registry = wpforms()->obj( 'ai_chat_surface_registry' );

if ( $registry instanceof SurfaceRegistry ) {
			$registry->register( $this );
		}

$this->hooks();
	}

/**
	 * Attach hooks. Override in subclasses.
	 *
	 * @since 2.0.0
	 */
	protected function hooks(): void {}

/**
	 * Surface-owned page state. Override in subclasses.
	 *
	 * @since 2.0.0
	 *
	 * @param array $surface Active surface config.
	 * @param array $request Sanitized request payload.
	 *
	 * @return array
	 */
	protected function build_page_state( array $surface, array $request ): array { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.Found, Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed

return [];
	}

/**
	 * Aggregate the full state dict for this surface.
	 *
	 * @since 2.0.0
	 *
	 * @param array $surface       Active surface config (with `slug` injected).
	 * @param array $request       Sanitized request payload.
	 * @param array $active_scopes Active scope slugs for this turn.
	 *
	 * @return array
	 */
	public function get_state( array $surface, array $request, array $active_scopes ): array {

$page_state    = $this->build_page_state( $surface, $request );
		$surface_state = $this->build_surface_state( $surface, $request, $active_scopes, $page_state );

$state = [
			'page_state'    => $page_state,
			'surface_state' => $surface_state,
		];

/**
		 * Filters the aggregated surface state before it ships to the middleware.
		 *
		 * @since 2.0.0
		 *
		 * @param array $state         Aggregated state.
		 * @param array $surface       Active surface config.
		 * @param array $request       Sanitized request payload.
		 * @param array $active_scopes Active scope slugs.
		 */
		return (array) apply_filters(
			"wpforms_integrations_ai_admin_chat_surface_base_get_state_{$this->get_slug()}",
			$state,
			$surface,
			$request,
			$active_scopes
		);
	}

/**
	 * Aggregate each active scope's contribution into the `surface_state` dict.
	 *
	 * Scopes run in `$active_scopes` order; the running `$accumulated` dict exposes
	 * earlier scopes' contributions so later scopes can read and patch prior state.
	 *
	 * @since 2.0.0
	 *
	 * @param array $surface       Active surface config.
	 * @param array $request       Sanitized request payload.
	 * @param array $active_scopes Active scope slugs for this turn.
	 * @param array $page_state    Surface-owned page state (seeds `$accumulated`).
	 *
	 * @return array Scope-slug => contribution map.
	 */
	private function build_surface_state( array $surface, array $request, array $active_scopes, array $page_state ): array {

$scope_registry = wpforms()->obj( 'ai_chat_scope_registry' );

if ( ! $scope_registry instanceof ScopeRegistry ) {
			return [];
		}

$surface_state = [];
		$accumulated   = [
			'page_state'    => $page_state,
			'surface_state' => $surface_state,
		];

foreach ( $active_scopes as $slug ) {
			$scope = $scope_registry->get( $slug );

if ( ! $scope instanceof ScopeBase ) {
				continue;
			}

$surface_state[ $slug ]       = $scope->get_state( $surface, $request, $accumulated );
			$accumulated['surface_state'] = $surface_state;
		}

return $surface_state;
	}
}