array( 'label' => 'Stat highlight', 'templates' => array( 'metric-card', 'metric-inline', 'metric-ring', 'metric-bleed' ), 'fields' => array( 'value' => array( 'max' => 16, 'required' => true ), 'label' => array( 'max' => 90, 'required' => true ), 'supporting_text' => array( 'max' => 220, 'required' => false ), 'source' => array( 'max' => 140, 'required' => false ), // 0-100, or null when the text states no proportion. // // Explicit rather than parsed out of `value`, because "3.4x", // "£12/mo" and "9 out of 10" are all legitimate headline // figures and only one of them implies a fraction. Guessing a // proportion from a value that has none would be inventing // data, which is the one thing this feature must never do. 'proportion' => array( 'numeric' => true, 'required' => false ), ), ), 'takeaway' => array( 'label' => 'Key takeaway', 'templates' => array( 'takeaway-card', 'takeaway-banner', 'takeaway-rule' ), 'fields' => array( 'title' => array( 'max' => 90, 'required' => false ), 'body' => array( 'max' => 420, 'required' => true ), ), ), 'checklist' => array( 'label' => 'Checklist', 'templates' => array( 'checklist-card', 'checklist-plain', 'checklist-numbered', 'checklist-timeline' ), 'fields' => array( 'title' => array( 'max' => 90, 'required' => false ), 'items' => array( 'max' => 150, 'required' => true, 'list' => true, 'max_items' => 5 ), ), ), 'quote' => array( 'label' => 'Pull quote', 'templates' => array( 'quote-card', 'quote-rule', 'quote-mark' ), 'fields' => array( 'text' => array( 'max' => 420, 'required' => true ), 'attribution' => array( 'max' => 90, 'required' => false ), 'role' => array( 'max' => 90, 'required' => false ), ), ), ); /** * Content a template cannot render without. * * A gauge with nothing to gauge is not a design choice, it is a bug that * looks deliberate. Rather than special-casing the ring, every template can * declare what it needs, the registry filters on it, and the renderer falls * back rather than drawing something meaningless. Adding a template later * means declaring its requirements, not patching another branch. */ const TEMPLATE_REQUIRES = array( 'metric-ring' => array( 'proportion' ), ); const WIDTHS = array( 'compact', 'content', 'wide', 'full' ); const ALIGNMENTS = array( 'left', 'center', 'right' ); const BACKGROUNDS = array( 'light', 'dark', 'transparent' ); const SPACINGS = array( 'compact', 'comfortable', 'roomy' ); /** * Visual styles. * * Not decoration on top of one design: each rebuilds the block's weight, * fill and typography, so the same content genuinely reads differently. * The Brand Kit collects this once and every block inherits it, which is * what stops a site looking like four plugins had a go at it. */ const STYLES = array( 'clean', 'bold', 'editorial', 'playful' ); /* ─────────────────────────── Introspection ─────────────────────────── */ /** * The registry, in a shape the editor can build a picker from. * * @return array */ public static function registry() { $out = array(); foreach ( self::TYPES as $type => $def ) { $requires = array(); foreach ( $def['templates'] as $template ) { $requires[ $template ] = self::TEMPLATE_REQUIRES[ $template ] ?? array(); } $out[] = array( 'type' => $type, 'label' => $def['label'], 'templates' => $def['templates'], 'requires' => $requires, 'fields' => $def['fields'], 'icons' => VisualIcons::names(), ); } return $out; } /** * Whether a template name belongs to a content type. * * @param string $type Content type. * @param string $template Template name. * @return bool */ public static function template_belongs( $type, $template ) { return isset( self::TYPES[ $type ] ) && in_array( $template, self::TYPES[ $type ]['templates'], true ); } /** * Whether this content can actually fill this template. * * @param string $template Template name. * @param array $content Sanitised content fields. * @return bool */ public static function template_supported( $template, $content ) { foreach ( self::TEMPLATE_REQUIRES[ $template ] ?? array() as $needs ) { if ( ! isset( $content[ $needs ] ) || null === $content[ $needs ] || '' === $content[ $needs ] ) { return false; } } return true; } /** * Every template of a type that this content could actually fill. * * The editor uses it to disable the ones that would not work rather than * letting someone pick a gauge and wonder why it is full. * * @param string $type Content type. * @param array $content Sanitised content fields. * @return string[] */ public static function usable_templates( $type, $content ) { $all = self::TYPES[ $type ]['templates'] ?? array(); return array_values( array_filter( $all, function ( $t ) use ( $content ) { return self::template_supported( $t, $content ); } ) ); } /* ─────────────────────────── Sanitising ─────────────────────────── */ /** * Clean a full set of block attributes. * * Returns null when the block has no usable content, so callers can render * nothing rather than an empty shell. Over-long values are truncated rather * than rejected, because silently dropping a customer's paragraph is worse * than shortening it, and the editor shows the same limits live. * * @param array $attrs Untrusted attributes. * @return array|null Sanitised attributes, or null when unusable. */ public static function sanitize( $attrs ) { $attrs = is_array( $attrs ) ? $attrs : array(); $type = isset( $attrs['contentType'] ) ? (string) $attrs['contentType'] : ''; if ( ! isset( self::TYPES[ $type ] ) ) { return null; } $def = self::TYPES[ $type ]; $template = isset( $attrs['template'] ) ? (string) $attrs['template'] : ''; if ( ! self::template_belongs( $type, $template ) ) { $template = $def['templates'][0]; } $incoming = isset( $attrs['content'] ) && is_array( $attrs['content'] ) ? $attrs['content'] : array(); $content = array(); foreach ( $def['fields'] as $field => $rules ) { if ( ! empty( $rules['numeric'] ) ) { $raw = $incoming[ $field ] ?? null; // Absent and "not stated" are the same thing here, and both // must stay null so template_supported() can see the gap. // Always a float, never sometimes an int: min()/max() return // whichever operand wins, so clamping 420 handed back an int // while an ordinary value came back as a float. A field whose // type depends on its value is a trap for every later caller. $content[ $field ] = is_numeric( $raw ) ? (float) max( 0, min( 100, round( (float) $raw, 1 ) ) ) : null; continue; } if ( ! empty( $rules['list'] ) ) { $items = isset( $incoming[ $field ] ) && is_array( $incoming[ $field ] ) ? $incoming[ $field ] : array(); $clean = array(); foreach ( $items as $item ) { $item = self::text( $item, $rules['max'] ); if ( '' !== $item ) { $clean[] = $item; } if ( count( $clean ) >= $rules['max_items'] ) { break; } } $content[ $field ] = $clean; continue; } $content[ $field ] = self::text( $incoming[ $field ] ?? '', $rules['max'] ); } // A block missing a required field has nothing worth rendering. foreach ( $def['fields'] as $field => $rules ) { if ( empty( $rules['required'] ) ) { continue; } if ( empty( $content[ $field ] ) ) { return null; } } $layout = isset( $attrs['layout'] ) && is_array( $attrs['layout'] ) ? $attrs['layout'] : array(); // Degrade rather than render something meaningless. A ring with no // proportion falls back to the type's default card, keeping every // field the customer or the model supplied. if ( ! self::template_supported( $template, $content ) ) { $template = $def['templates'][0]; } $brand = BrandKit::resolve(); // Style defaults to the Brand Kit rather than to a constant, so a site // that chose "bold" once gets bold blocks without setting it per block. // An explicit per-block value still wins. $style = self::pick( $attrs['style'] ?? '', self::STYLES, $brand['visual_style'] ); return array( 'schemaVersion' => self::SCHEMA_VERSION, 'contentType' => $type, 'template' => $template, 'templateVersion' => max( 1, (int) ( $attrs['templateVersion'] ?? 1 ) ), 'content' => $content, 'icon' => VisualIcons::resolve( (string) ( $attrs['icon'] ?? '' ), $type ), 'caption' => self::text( $attrs['caption'] ?? '', 220 ), 'style' => $style, 'shape' => in_array( (string) ( $attrs['shape'] ?? '' ), VisualIcons::shape_names(), true ) ? (string) $attrs['shape'] : self::default_shape( $style, $type ), 'layout' => array( 'width' => self::pick( $layout['width'] ?? '', self::WIDTHS, 'content' ), 'align' => self::pick( $layout['align'] ?? '', self::ALIGNMENTS, 'left' ), 'background' => self::pick( $layout['background'] ?? '', self::BACKGROUNDS, 'light' ), 'spacing' => self::pick( $layout['spacing'] ?? '', self::SPACINGS, 'comfortable' ), ), ); } /** * The decorative shape a style reaches for by default. * * Clean stays bare on purpose. Anything else and "clean" would just be * "playful with fewer dots", and a customer who picked restraint would * not get it. * * @param string $style Visual style. * @param string $type Content type. * @return string Shape name, or '' for none. */ private static function default_shape( $style, $type ) { if ( 'clean' === $style ) { return ''; } $by_type = array( 'metric' => array( 'bold' => 'arc', 'editorial' => 'grid', 'playful' => 'blob' ), 'takeaway' => array( 'bold' => 'wedge', 'editorial' => 'grid', 'playful' => 'blob' ), 'checklist' => array( 'bold' => 'arc', 'editorial' => 'dots', 'playful' => 'dots' ), 'quote' => array( 'bold' => 'rings', 'editorial' => 'dots', 'playful' => 'blob' ), ); return $by_type[ $type ][ $style ] ?? ''; } /** * Strip a value to safe plain text within a length budget. * * Blocks carry no inline markup by design: a stat card is a stat, not a * rich-text field. Tags are removed rather than escaped so that pasted * markup collapses to its text instead of showing as literal angle * brackets to the reader. * * @param mixed $value Raw input. * @param int $max Character budget. * @return string */ private static function text( $value, $max ) { if ( ! is_scalar( $value ) ) { return ''; } $value = wp_strip_all_tags( (string) $value, true ); $value = preg_replace( '/\s+/u', ' ', $value ); $value = trim( (string) $value ); if ( '' === $value ) { return ''; } if ( function_exists( 'mb_substr' ) && mb_strlen( $value ) > $max ) { $value = rtrim( mb_substr( $value, 0, $max ) ); } elseif ( strlen( $value ) > $max ) { $value = rtrim( substr( $value, 0, $max ) ); } return $value; } /** * Constrain a value to an allowlist. * * @param mixed $value Raw input. * @param array $allowed Permitted values. * @param string $default Value to use when input is not permitted. * @return string */ private static function pick( $value, $allowed, $default ) { $value = is_string( $value ) ? strtolower( trim( $value ) ) : ''; return in_array( $value, $allowed, true ) ? $value : $default; } /* ──────────────────────────── Rendering ──────────────────────────── */ /** * Render a visual block. * * @param array $attrs Attributes; sanitised here, so callers may pass raw. * @return string HTML, or '' when there is nothing renderable. */ public static function render( $attrs ) { $a = self::sanitize( $attrs ); if ( null === $a ) { return ''; } $method = 'render_' . str_replace( '-', '_', $a['template'] ); if ( ! method_exists( __CLASS__, $method ) ) { return ''; } $layout = $a['layout']; $classes = array( 'aeogm-visual', 'aeogm-visual--' . $a['contentType'], 'aeogm-visual--' . $a['template'], 'aeogm-visual--w-' . $layout['width'], 'aeogm-visual--a-' . $layout['align'], 'aeogm-visual--bg-' . $layout['background'], 'aeogm-visual--s-' . $layout['spacing'], 'aeogm-visual--style-' . $a['style'], ); if ( '' !== $a['shape'] ) { $classes[] = 'aeogm-visual--has-shape'; } $inner = VisualIcons::shape( $a['shape'] ) . self::$method( $a ); if ( '' === trim( $inner ) ) { return ''; } if ( '' !== $a['caption'] ) { $inner .= '
' . esc_html( $a['caption'] ) . '
'; } return '
' . $inner . '
'; } /** * The plain-HTML version saved into post content. * * This is what a reader sees if the plugin is ever deactivated, so it must * carry the whole point of the block in ordinary tags. A dynamic block that * saves nothing leaves a hole in the article the day the plugin is switched * off, which is indefensible for something that writes into posts. * * @param array $attrs Attributes. * @return string HTML, or '' when there is nothing renderable. */ public static function fallback( $attrs ) { $a = self::sanitize( $attrs ); if ( null === $a ) { return ''; } $c = $a['content']; $body = ''; switch ( $a['contentType'] ) { case 'metric': $body = '

' . esc_html( $c['value'] ) . ' ' . esc_html( $c['label'] ) . '

'; if ( '' !== $c['supporting_text'] ) { $body .= '

' . esc_html( $c['supporting_text'] ) . '

'; } if ( '' !== $c['source'] ) { $body .= '

' . esc_html( $c['source'] ) . '

'; } break; case 'takeaway': if ( '' !== $c['title'] ) { $body = '

' . esc_html( $c['title'] ) . '

'; } $body .= '

' . esc_html( $c['body'] ) . '

'; break; case 'checklist': if ( '' !== $c['title'] ) { $body = '

' . esc_html( $c['title'] ) . '

'; } $body .= ''; break; case 'quote': $body = '

' . esc_html( $c['text'] ) . '

'; if ( '' !== $c['attribution'] ) { $cite = $c['attribution'] . ( '' !== $c['role'] ? ', ' . $c['role'] : '' ); $body .= '' . esc_html( $cite ) . ''; } $body .= '
'; break; } if ( '' === $body ) { return ''; } if ( '' !== $a['caption'] ) { $body .= '
' . esc_html( $a['caption'] ) . '
'; } return '
' . $body . '
'; } /* ─────────────────────────── Templates ─────────────────────────── */ private static function icon_chip( $a ) { $svg = VisualIcons::svg( $a['icon'] ); return '' === $svg ? '' : '
' . $svg . '
'; } private static function render_metric_card( $a ) { $c = $a['content']; $out = self::icon_chip( $a ) . '
' . '

' . esc_html( $c['value'] ) . '

' . '

' . esc_html( $c['label'] ) . '

'; if ( '' !== $c['supporting_text'] ) { $out .= '

' . esc_html( $c['supporting_text'] ) . '

'; } if ( '' !== $c['source'] ) { $out .= '

' . esc_html( $c['source'] ) . '

'; } return $out . '
'; } private static function render_metric_inline( $a ) { $c = $a['content']; $out = '
' . '

' . '' . esc_html( $c['value'] ) . '' . '' . esc_html( $c['label'] ) . '' . '

'; if ( '' !== $c['supporting_text'] ) { $out .= '

' . esc_html( $c['supporting_text'] ) . '

'; } if ( '' !== $c['source'] ) { $out .= '

' . esc_html( $c['source'] ) . '

'; } return $out . '
'; } private static function render_takeaway_card( $a ) { $c = $a['content']; $out = self::icon_chip( $a ) . '
'; if ( '' !== $c['title'] ) { $out .= '

' . esc_html( $c['title'] ) . '

'; } return $out . '

' . esc_html( $c['body'] ) . '

'; } private static function render_takeaway_banner( $a ) { return self::render_takeaway_card( $a ); } private static function render_checklist_card( $a ) { $c = $a['content']; $out = self::icon_chip( $a ) . '
'; if ( '' !== $c['title'] ) { $out .= '

' . esc_html( $c['title'] ) . '

'; } $out .= '
'; } private static function render_checklist_plain( $a ) { return self::render_checklist_card( $a ); } private static function render_quote_card( $a ) { $c = $a['content']; $out = self::icon_chip( $a ) . '
' . '

' . esc_html( $c['text'] ) . '

'; if ( '' !== $c['attribution'] ) { $out .= '

' . esc_html( $c['attribution'] ) . ''; if ( '' !== $c['role'] ) { $out .= '' . esc_html( $c['role'] ) . ''; } $out .= '

'; } return $out . '
'; } private static function render_quote_rule( $a ) { return self::render_quote_card( $a ); } /** * A metric wrapped in an SVG progress ring. * * This is where SVG genuinely earns its place rather than being used for * its own sake: a ring is geometry, not text, and drawing it in CSS would * mean conic-gradient hacks that behave differently across browsers. The * ring is decorative and the number is real text beside it, so nothing is * lost to anything that cannot read the graphic. */ private static function render_metric_ring( $a ) { $c = $a['content']; // The proportion is a field, not something inferred from the value // string. sanitize() guarantees a number here, because a ring with no // proportion degrades to metric-card before it reaches this method. $pct = (float) $c['proportion']; $r = 52; $circ = 2 * M_PI * $r; $dash = $circ * ( max( 0, min( 100, $pct ) ) / 100 ); $ring = ''; // "68%" and "9 out of 10" are both legitimate headline figures, and one // of them does not fit a circle at the same size. Size by length rather // than assuming every value is short, which is what pushed "9 out of // 10" straight through the stroke. $len = function_exists( 'mb_strlen' ) ? mb_strlen( $c['value'] ) : strlen( $c['value'] ); $fit = $len <= 4 ? 'short' : ( $len <= 8 ? 'medium' : 'long' ); $out = '
' . $ring . '' . esc_html( $c['value'] ) . '
' . '
' . '

' . esc_html( $c['label'] ) . '

'; if ( '' !== $c['supporting_text'] ) { $out .= '

' . esc_html( $c['supporting_text'] ) . '

'; } if ( '' !== $c['source'] ) { $out .= '

' . esc_html( $c['source'] ) . '

'; } return $out . '
'; } /** An oversized numeral running to the edge, with the label beneath it. */ private static function render_metric_bleed( $a ) { $c = $a['content']; $out = '
' . '

' . esc_html( $c['value'] ) . '

' . '

' . esc_html( $c['label'] ) . '

'; if ( '' !== $c['supporting_text'] ) { $out .= '

' . esc_html( $c['supporting_text'] ) . '

'; } if ( '' !== $c['source'] ) { $out .= '

' . esc_html( $c['source'] ) . '

'; } return $out . '
'; } /** A takeaway carried by a heavy accent rule instead of a panel. */ private static function render_takeaway_rule( $a ) { return self::render_takeaway_card( $a ); } /** Numbered steps. Reads as a sequence, where ticks read as a set. */ private static function render_checklist_numbered( $a ) { $c = $a['content']; $out = self::icon_chip( $a ) . '
'; if ( '' !== $c['title'] ) { $out .= '

' . esc_html( $c['title'] ) . '

'; } $out .= '
    '; foreach ( $c['items'] as $i => $item ) { $out .= '
  1. ' . ( $i + 1 ) . '' . '' . esc_html( $item ) . '
  2. '; } return $out . '
'; } /** The same steps, joined by a connecting line. */ private static function render_checklist_timeline( $a ) { return self::render_checklist_numbered( $a ); } /** A quote against an oversized quotation mark watermark. */ private static function render_quote_mark( $a ) { return self::render_quote_card( $a ); } /* ────────────────────────────── Styles ────────────────────────────── */ /** * The block stylesheet, as raw CSS. * * Deliberately not a