array(), 'h3' => array(), 'h4' => array(), 'p' => array(), 'br' => array(), 'strong' => array(), 'em' => array(), 'b' => array(), 'i' => array(), 'a' => array( 'href' => true, 'title' => true, 'rel' => true, 'target' => true ), 'ul' => array(), 'ol' => array(), 'li' => array(), 'table' => array(), 'thead' => array(), 'tbody' => array(), 'tr' => array(), 'th' => array( 'scope' => true ), 'td' => array(), ); /** * Render one section from its resolved payload. * * @param array $section Normalized BlueprintSection. * @param array $payload array{heading?:string,paragraphs?:string[],items?:string[],rows?:array,extension?:array}; `extension` holds a data section extension's own data. * @param string $heading_level 'h2' | 'h3' | 'h4'. * @return array{heading:string,html:string,text:string,items:string[],rows:array} */ public function renderSection( array $section, array $payload, string $heading_level ): array { if ( 'fixed' === ( $section['mode'] ?? '' ) ) { $heading_text = $this->resolveHeadingText( $section['heading'] ?? array(), '' ); $fixed_html = (string) ( $section['fixedText'] ?? '' ); $html = $this->headingHtml( $heading_text, $heading_level ) . $fixed_html; return array( 'heading' => $heading_text, 'html' => $this->finalizeHtml( $html ), 'text' => trim( wp_strip_all_tags( $fixed_html ) ), 'items' => array(), 'rows' => array(), ); } $heading_text = $this->resolveHeadingText( $section['heading'] ?? array(), (string) ( $payload['heading'] ?? '' ) ); if ( array_key_exists( 'extension', $payload ) ) { $extension = SectionTypeExtensions::data( (string) ( $section['type'] ?? '' ) ); $rendered = null !== $extension && is_array( $payload['extension'] ) && ! empty( $payload['extension'] ) ? $extension->render( $payload['extension'] ) : array( 'html' => '', 'text' => '', 'rows' => array() ); $body = (string) ( $rendered['html'] ?? '' ); $html = '' !== $body ? $this->headingHtml( $heading_text, $heading_level ) . $body : ''; return array( 'heading' => $heading_text, 'html' => $this->finalizeHtml( $html ), 'text' => (string) ( $rendered['text'] ?? '' ), 'items' => array(), 'rows' => array_values( (array) ( $rendered['rows'] ?? array() ) ), ); } switch ( $section['format'] ?? 'paragraph' ) { case 'bullets': case 'numbered': $items = array_values( (array) ( $payload['items'] ?? array() ) ); $html = $this->renderList( $items, $heading_text, $heading_level, 'numbered' === $section['format'] ); return array( 'heading' => $heading_text, 'html' => $this->finalizeHtml( $html ), 'text' => implode( "\n", $items ), 'items' => $items, 'rows' => array() ); case 'table': $rows = array_values( (array) ( $payload['rows'] ?? array() ) ); $html = $this->renderTable( $rows, $heading_text, $heading_level ); return array( 'heading' => $heading_text, 'html' => $this->finalizeHtml( $html ), 'text' => $this->rowsToText( $rows ), 'items' => array(), 'rows' => $rows ); default: $paragraphs = array_values( (array) ( $payload['paragraphs'] ?? array() ) ); $extension = array_key_exists( 'answerFacts', $payload ) ? SectionTypeExtensions::isolated( (string) ( $section['type'] ?? '' ) ) : null; if ( $extension instanceof ContextualIsolatedSectionExtension ) { $body = $extension->withFacts( (array) $payload['answerFacts'] )->renderParagraphs( $paragraphs ); $html = $this->headingHtml( $heading_text, $heading_level ) . (string) ( $body['html'] ?? '' ); return array( 'heading' => $heading_text, 'html' => $this->finalizeHtml( $html ), 'text' => (string) ( $body['text'] ?? '' ), 'items' => array(), 'rows' => array() ); } $html = $this->renderParagraphs( $paragraphs, $heading_text, $heading_level ); return array( 'heading' => $heading_text, 'html' => $this->finalizeHtml( $html ), 'text' => implode( "\n\n", $paragraphs ), 'items' => array(), 'rows' => array() ); } } /** * @param string[] $paragraphs Paragraph strings (plain text). * @param string $heading Heading text, already resolved ('' = none). * @param string $level 'h2' | 'h3' | 'h4'. * @return string */ public function renderParagraphs( array $paragraphs, string $heading, string $level ): string { $html = $this->headingHtml( $heading, $level ); foreach ( $paragraphs as $paragraph ) { if ( '' === $paragraph ) { continue; } $html .= '

' . esc_html( $paragraph ) . '

'; } return $html; } /** * @param string[] $items List item strings (plain text). * @param string $heading Heading text, already resolved ('' = none). * @param string $level 'h2' | 'h3' | 'h4'. * @param bool $ordered True for a numbered list, false for bullets. * @return string */ public function renderList( array $items, string $heading, string $level, bool $ordered ): string { $tag = $ordered ? 'ol' : 'ul'; $html = $this->headingHtml( $heading, $level ) . '<' . $tag . '>'; foreach ( $items as $item ) { if ( '' === $item ) { continue; } $html .= '
  • ' . esc_html( $item ) . '
  • '; } $html .= ''; return $html; } /** * @param array $rows Table rows. * @param string $heading Heading text, already resolved ('' = none). * @param string $level 'h2' | 'h3' | 'h4'. * @return string */ public function renderTable( array $rows, string $heading, string $level ): string { $html = $this->headingHtml( $heading, $level ) . ''; foreach ( $rows as $row ) { $html .= ''; } $html .= '
    ' . esc_html( (string) ( $row['label'] ?? '' ) ) . '' . esc_html( (string) ( $row['value'] ?? '' ) ) . '
    '; return $html; } /** * Resolve which heading text to use for a section, per its heading * mode: `fixed` always uses the saved heading text; `ai` uses the * model's (already cleaned) heading when it provided one, falling back * to the saved text otherwise; `none` never shows a heading. * * @param array $heading_spec {mode,text}. * @param string $ai_heading The unit's cleaned `heading` field (ai mode only; ignored otherwise). * @return string */ public function resolveHeadingText( array $heading_spec, string $ai_heading ): string { switch ( $heading_spec['mode'] ?? 'none' ) { case 'fixed': return (string) ( $heading_spec['text'] ?? '' ); case 'ai': return '' !== trim( $ai_heading ) ? $ai_heading : (string) ( $heading_spec['text'] ?? '' ); default: return ''; } } /** * Final structural-allowlist pass. Call this on every rendered HTML * fragment before it is stored or returned. * * @param string $html Rendered HTML. * @return string */ public function finalizeHtml( string $html ): string { return wp_kses( $html, self::STRUCTURAL_ALLOWED_HTML ); } /** * Append any ``/`
    ` elements found in $existing_html, after * $rendered_html, unchanged in content but sanitized for safety: this * preserves content images when a Blueprint output replaces a * description that contained them. * * @param string $rendered_html Freshly rendered Blueprint HTML. * @param string $existing_html The description HTML being replaced. * @return string */ public function preserveContentImages( string $rendered_html, string $existing_html ): string { if ( '' === trim( $existing_html ) ) { return $rendered_html; } if ( 0 === preg_match_all( '/<(img|figure)\b[^>]*>(?:.*?<\/\1>)?/is', $existing_html, $matches ) ) { return $rendered_html; } $kept = wp_kses( implode( '', $matches[0] ), self::preservedImageAllowedHtml() ); return $rendered_html . $kept; } /** * The ``/`
    `-preserving `wp_kses()` allowlist: the Blueprint * structural allowlist, widened with the image attributes a preserved * `` legitimately carries and the wrapper tags WordPress's Image * block renders it inside. Shared with {@see * \AIPT\Api\ContentStructure\Engine\ExecutionContextBuilder::extractImagesAndFigures()}, * which extracts the same elements via `DOMDocument` instead of this * method's regex and must sanitize them identically. * * @return array */ public static function preservedImageAllowedHtml(): array { $allowed = self::STRUCTURAL_ALLOWED_HTML; $allowed['img'] = array( 'src' => true, 'alt' => true, 'width' => true, 'height' => true, 'class' => true, 'srcset' => true, 'sizes' => true ); $allowed['figure'] = array( 'class' => true ); $allowed['figcaption'] = array(); return $allowed; } /** * @param string $heading Heading text, already resolved. * @param string $level 'h2' | 'h3' | 'h4'. * @return string */ private function headingHtml( string $heading, string $level ): string { if ( '' === trim( $heading ) ) { return ''; } return '<' . $level . '>' . esc_html( $heading ) . ''; } /** * @param array $rows Table rows. * @return string */ private function rowsToText( array $rows ): string { $lines = array(); foreach ( $rows as $row ) { $lines[] = ( $row['label'] ?? '' ) . ': ' . ( $row['value'] ?? '' ); } return implode( "\n", $lines ); } }