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( $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; } if ( '' === $body ) { return ''; } if ( '' !== $a['caption'] ) { $body .= '' . esc_html( $c['text'] ) . '
'; if ( '' !== $c['attribution'] ) { $cite = $c['attribution'] . ( '' !== $c['role'] ? ', ' . $c['role'] : '' ); $body .= '' . esc_html( $cite ) . ''; } $body .= '
' . 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 . '' . '' . 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 . '' . esc_html( $c['title'] ) . '
'; } return $out . '' . esc_html( $c['body'] ) . '
' . esc_html( $c['title'] ) . '
'; } $out .= ''; if ( '' !== $c['attribution'] ) { $out .= '' . esc_html( $c['text'] ) . '
' . esc_html( $c['attribution'] ) . ''; if ( '' !== $c['role'] ) { $out .= '' . esc_html( $c['role'] ) . ''; } $out .= '
'; } return $out . '' . esc_html( $c['label'] ) . '
'; if ( '' !== $c['supporting_text'] ) { $out .= '' . esc_html( $c['supporting_text'] ) . '
'; } if ( '' !== $c['source'] ) { $out .= '' . esc_html( $c['source'] ) . '
'; } return $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 . '' . esc_html( $c['title'] ) . '
'; } $out .= '