import React from 'react';
import { __, _n, sprintf } from '@wordpress/i18n';
import { copyText } from '../copy';
/**
* A card with a defined header zone.
*
* The header used to be a margin-separated block inside the same padding box
* as the content, which meant a card had no internal structure — title and
* body shared one field and the eye had nothing to anchor on. Now the header
* is its own zone with a rule under it, an optional tinted icon square, and
* the action on the title's line. Every card on every screen changes shape
* from this one edit.
*
* `flush` drops the body padding for cards whose content is a full-bleed
* table; the table's own header band then sits directly under the rule.
*/
export function Card({ title, subtitle, action, icon, tag, children, className = '', flush = false }) {
const hasHead = title || action || icon;
return (
{hasHead && (
{icon && {icon}}
{tag && {tag}}
{title &&
{title}
}
{/* 70ch broke an 88-character subtitle two words from the end and
left "it" alone on a second line. */}
{subtitle &&
{subtitle}
}
{action &&
{action}
}
)}
{children}
);
}
/**
* The screen's own conclusion, stated before its evidence.
*
* A screen made of ten equally-weighted cards is a report, and a report makes
* the reader do the synthesis. Most people opening one of these screens have a
* few minutes and a different job — they need to know whether anything is wrong
* and what to press, and only then whether the chart on card six is trending.
*
* So the conclusion goes first, at a size nothing else on the page competes
* with, with the reason underneath it and the action beside it. The `why` line
* always names a number that appears further down, so the verdict can be
* checked rather than believed.
*
* Tone is the loudest thing here, so it is the thing most worth getting right:
* `bad` is reserved for something that is actually costing the customer
* something right now, never for a threshold. A banner that is permanently red
* is a banner people stop reading, and then the one time it matters they will
* not see it either.
*/
export function Verdict({ tone = 'neutral', text, why, action, onAction, busy = false, children }) {
return (
{text}
{why &&
{why}
}
{children}
{action && (
)}
);
}
/**
* The advisor strip — one line that knows what to do next.
*
* The dashboard used to open on a greeting and a four-line banner, and the
* list of prioritised fixes lived a full screen further down. This is the
* Copilot pattern the reference tools use instead: a single quiet row —
* coloured dot, one sentence, a count, the one button — that unfolds into
* the recommendations when asked. The sentence changes; the height never
* does, so the numbers below always start in the same place.
*/
export function Advisor({ tone = 'neutral', text, sub, count = 0, action, onAction, busy = false, defaultOpen = false, children }) {
const [open, setOpen] = React.useState(defaultOpen);
const expandable = !!children;
return (
{action && (
)}
{open && children &&
{children}
}
);
}
/**
* A half-circle gauge — the reference tools' shape for "how healthy".
*
* Always the working violet: the gauge is identity, and the bands beside it
* carry the judgement. A gauge that turns red is a second verdict competing
* with the real one.
*/
export function Gauge({ value, max = 100, label = 'Score', delta }) {
const R = 58;
const C = Math.PI * R;
const pct = Math.max(0, Math.min(1, (Number(value) || 0) / max));
const gid = React.useId();
return (
{delta !== undefined && delta !== null && (
)}
);
}
/**
* The page-level loading and error state, shared by every screen.
*
* Forty screens used to open on a bare card that said "Loading…" — a word,
* in a box, for as long as the request took. This is the shape of the page
* that is coming (a title bar and three content bands, shimmering), so the
* layout does not jump when data lands; and when it fails, the reason in a
* card the reader can act on rather than a sentence that replaced the page.
*/
export function PageState({ error, licensed = true, proTitle, proNote, label = __('Loading', 'ai-rank-suite') }) {
// A screen whose data needs a licence is not a broken screen. Callers pass
// licensed={false} (or catch a 402 and pass it here) and get the Pro
// stand-in instead of the red "could not load" card.
if (! licensed) {
return (
{__('Pro', 'ai-rank-suite')}
{proNote || __('This screen reads data that Pro collects. Activating your licence turns it on; nothing here has been deleted.', 'ai-rank-suite')}
{__('Usual causes: a security plugin or host firewall blocking /wp-json/, an expired login, or a module quarantined after an error — the developer tools show which.', 'ai-rank-suite')}
);
}
return (
);
}
/**
* What a card shows when it has nothing to show.
*
* The default was a card with a heading, a subtitle and 200px of white space,
* which reads as broken rather than as empty. Three things fix that: say what
* would be here, say why it is not, and offer the one action that would fill
* it. The third is the part usually missing — an empty state with no way out of
* it is just a dead end with better manners.
*/
export function Empty({ icon, title, children, action, onAction, compact = false }) {
return (
{icon && {icon}}
{title}
{children &&
{children}
}
{action && (
)}
);
}
/**
* A ranked list where the bar *is* the row.
*
* Used wherever the question is "which of these first" — the leverage board,
* audit findings, prompts by visibility. Three things are always true of that
* question and are built in here rather than re-decided per screen: the list is
* sorted by consequence and not by count, the bar is scaled against the largest
* item so the top row is always full width, and the number on the right is the
* thing being counted rather than a percentage of something unstated.
*/
export function Board({ items, onItem, empty }) {
const max = Math.max(1, ...items.map((i) => i.value || 0));
if (!items.length) return empty || null;
return (
{items.map((item) => (
))}
);
}
/**
* A dense grid of numbers, in the shape every serious SEO tool uses.
*
* The tiles this replaces were generous: one metric each, a sentence of
* explanation underneath, four across a row. Six metrics therefore took two
* screenfuls and carried four sentences nobody re-reads after the first visit.
*
* Semrush, Ahrefs and Rank Math all land on the same answer, and it is not a
* stylistic one — somebody checking a site wants every headline number in one
* glance so they can spot the one that moved. So: a bordered grid, three
* across, value and change and nothing else, with the explanation demoted to a
* hover. Density is the feature.
*
* `accent` draws the coloured rule under a cell — used to tie a metric to its
* series in the chart below it, which is the only reason to colour a number.
*/
export function MetricGrid({ metrics, columns = 3, onSelect, active }) {
/*
* Never more tracks than tiles.
*
* Twelve screens pass `columns={4}` as a constant, which is right until a
* tile becomes conditional — and then the row ends in an empty cell that
* reads as a missing number rather than as one nobody needed. Clamping
* here fixes the whole class at once, including the callers that have not
* grown a conditional tile yet.
*/
const cols = Math.max(1, Math.min(columns, (metrics || []).length || 1));
return (
);
}
/**
* A donut with its categories named beside it.
*
* The bare ring said "88 / 100" and nothing else, so the only way to learn what
* made it 88 was to scroll. Rank Math's version of this puts the breakdown next
* to the number — good, fair, poor, no data, each with a count — and it is
* strictly better: the score and its composition are one glance instead of two.
*/
export function DonutBreakdown({ value, max = 100, label, rows, footnote }) {
const total = rows.reduce((a, r) => a + (r.value || 0), 0) || 1;
let offset = 0;
const R = 54;
const C = 2 * Math.PI * R;
return (
{rows.map((r, i) => (
{r.label}
{r.value}
))}
{footnote &&
{footnote}
}
);
}
/**
* The row that "Where this site is weak" is made of, as a component.
*
* A number, what it measures, a bar showing how the pages are distributed
* across good and bad, and how much of the site it touches. It is the most
* useful thing in this plugin because it answers four questions at once — how
* bad, at what, how widespread, and is it worth my afternoon — and it does it
* in one line that can be scanned down a column.
*
* Everything that ranks areas of a site now uses it, so the audit, the
* dashboard and the score breakdown read as the same instrument rather than
* three different ones.
*
* The score is optional on purpose. Where there is a real measured number it is
* shown; where there is not, inventing one to fill the column would be worse
* than leaving it out.
*/
export function ScoreRow({ score, label, sub, segments = [], reach, note, tone, onClick, wide = false }) {
const total = segments.reduce((a, s) => a + (s.value || 0), 0) || 1;
const band = (n) => (n >= 80 ? 'good' : n >= 50 ? 'mid' : 'bad');
return (
);
}
/**
* Configuration, folded away from the thing it configures.
*
* An API key, a property ID, a connection: typed once, then read never. The
* report underneath is read every week. Putting the first above the second
* meant every visit to Search Console or Analytics opened on a form the person
* had already filled in, with the numbers they came for pushed below the fold.
*
* Collapsed by default — except when the thing it configures is not connected
* yet, because then the form *is* the task and hiding it would be a puzzle.
* That is the `defaultOpen` prop, and it should always be driven by connection
* state rather than by taste.
*/
export function Panel({ title, note, defaultOpen = false, children }) {
const [open, setOpen] = React.useState(defaultOpen);
return (
{open &&
{children}
}
);
}
/**
* A label above a group of cards or tiles.
*
* A long screen is a stack of equally-weighted cards with nothing saying
* where one subject ends and the next begins. This is that.
*/
export function SectionTitle({ children, hint, action }) {
return (
{children}
{/* The hint wraps; it used to be `truncate`, which is
`white-space: nowrap`, and a nowrap child makes its whole
sentence the minimum width of every box above it — no
min-w-0 anywhere in the chain can undo that. In German,
about a third longer than English, that minimum grew past
the page and the entire screen scrolled sideways. A second
line costs 18 pixels and cannot do that. */}
{hint && (
{hint}
)}
{action}
);
}
/**
* Counts a number up on first paint.
*
* A dashboard whose figures are simply *there* on load reads as static; the
* same figures arriving read as measured. Short enough that nobody waits for
* it, and skipped entirely for anything that is not a number — "Live", "Off"
* and "—" must not animate.
*/
function useCountUp(value, ms = 620) {
const numeric = typeof value === 'number' ? value : null;
const [shown, setShown] = React.useState(numeric === null ? value : 0);
React.useEffect(() => {
if (numeric === null) {
setShown(value);
return undefined;
}
if (window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) {
setShown(numeric);
return undefined;
}
let raf;
const start = performance.now();
const tick = (now) => {
const p = Math.min(1, (now - start) / ms);
// Ease-out: the number decelerates into place rather than stopping.
setShown(Math.round(numeric * (1 - Math.pow(1 - p, 3))));
if (p < 1) raf = requestAnimationFrame(tick);
};
raf = requestAnimationFrame(tick);
return () => cancelAnimationFrame(raf);
}, [numeric, value, ms]);
return shown;
}
const BUTTON_VARIANTS = {
primary: 'ars-btn ars-btn-primary',
tonal: 'ars-btn ars-btn-tonal',
ghost: 'ars-btn ars-btn-ghost',
danger: 'ars-btn ars-btn-danger',
};
export function Button({ variant = 'primary', busy = false, children, ...props }) {
return (
);
}
export function Spinner() {
return (
);
}
export function Switch({ checked, onChange, label, disabled = false }) {
return (
);
}
export function Badge({ tone = 'neutral', children }) {
const tones = {
neutral: { bg: 'var(--ars-surface-3)', fg: 'var(--ars-ink-2)' },
brand: { bg: 'var(--ars-brand-tonal)', fg: 'var(--ars-brand-tonal-ink)' },
good: { bg: 'var(--ars-good-tonal)', fg: 'var(--ars-good)' },
warning: { bg: 'var(--ars-warning-tonal)', fg: 'var(--ars-warning)' },
serious: { bg: 'var(--ars-serious-tonal)', fg: 'var(--ars-serious)' },
};
const t = tones[tone] || tones.neutral;
return (
{children}
);
}
const STATUS = {
pass: { tone: 'good', icon: '✓', label: __('Pass', 'ai-rank-suite') },
warn: { tone: 'warning', icon: '!', label: __('Improve', 'ai-rank-suite') },
fail: { tone: 'serious', icon: '✕', label: __('Fix', 'ai-rank-suite') },
};
export function StatusBadge({ status }) {
const s = STATUS[status] || STATUS.warn;
return (
{s.icon} {s.label}
);
}
export function ScoreRing({ value, size = 152, label = 'AI Score', onLight = false }) {
const stroke = 14;
const r = (size - stroke) / 2;
const c = 2 * Math.PI * r;
const pct = Math.max(0, Math.min(100, value ?? 0));
const gid = React.useId();
return (
{/* A screen reader was told "0 / 100" for a ring the eye saw as "–":
the visual said not scored yet, the label said scored zero. */}
{value ?? '–'}
/ 100
);
}
export function ScorePill({ value }) {
if (value === null || value === undefined) {
return —;
}
const v = Number(value);
const tone = v >= 80 ? 'good' : v >= 50 ? 'mid' : 'bad';
// A dot, not a glyph: "!" beside every score made the whole table shout.
// The chip's colour carries the judgement; the dot anchors it.
return (
{v}
);
}
/**
* Page-level tabs, as an underlined bar.
*
* These were a boxed segmented control with a tick inside the active tab.
* A segmented control says "pick one setting"; a tab bar says "this page has
* several views", which is what these actually are — and the box drew a hard
* grey outline across the top of every screen for no information at all.
* The rule under the bar ties the tabs to the content below them.
*/
export function Tabs({ tabs, active, onChange, right }) {
return (
{/* Wrap, never scroll. A scrollbar under a four-item tab strip is
both ugly and useless — the tabs simply take a second line. */}
{tabs.map((t) => (
))}
{right &&
{right}
}
);
}
/**
* StatTile is the old name for what KpiTile does better.
*
* The two shipped side by side with different palettes (hand-mixed hexes vs
* the --ars-c-* tokens), different geometry (no accent hairline, no minimum
* height) and a different number size, so the tile row on Links, Analytics and
* Search Console did not match the tile row on the Dashboard. Same role, one
* component: this is now a thin alias so existing call sites keep working.
*/
export function StatTile({ label, value, sub, tone, ...rest }) {
return ;
}
/**
* Single-series line chart (SVG): smooth monotone curve, gradient area,
* y-axis labels, endpoint marker and a floating tooltip pill.
* Two measures of different scale get two charts — never a dual axis.
*/
/** The three horizontal rules every line chart draws, as fractions of its height. */
const GRID_LINES = [0, 0.5, 1];
export function LineChart({
data,
color = 'var(--ars-series-1)',
label,
height = 140,
formatValue = (v) => v,
/** Flip the y-axis — for rank positions, where a lower number is better. */
invert = false,
/**
* Fix the top of the axis.
*
* A series that is a percentage or a 0-100 score should be drawn against
* its real ceiling. Scaling to the highest observed value instead makes a
* four-point move fill the whole card, which reads as a dramatic
* improvement and is not one.
*/
axisMax = null,
/**
* Let the drawing run to the card's edge.
*
* A chart is the one element on a card that gains nothing from the card's
* gutter: the axis labels already sit inside the drawing, so the padding
* is a second margin around a picture that had one. On a wide card it
* costs 40px of the only element that can use them.
*/
bleed = false,
}) {
const [hover, setHover] = React.useState(null);
const gid = React.useId();
/*
* The viewBox was a fixed 640 wide while the box on screen is as wide as the
* card. preserveAspectRatio then scaled the whole drawing down to the fixed
* height and centred it, so on a wide screen the chart sat in a ~640px
* column with dead space either side. Measuring the box and drawing at that
* width keeps the viewBox 1:1 with the pixels: the line spans the card, and
* strokes and labels stay the size they were designed at instead of being
* scaled with it.
*/
const [width, setWidth] = React.useState(640);
const node = React.useRef(null);
const observer = React.useRef(null);
const measure = React.useCallback((el) => {
if (observer.current) {
observer.current.disconnect();
observer.current = null;
}
node.current = el;
if (!el || typeof ResizeObserver === 'undefined') {
return;
}
const ro = new ResizeObserver((entries) => {
const w = Math.round(entries[0]?.contentRect.width || 0);
if (w > 0) {
setWidth(Math.max(320, w));
}
});
ro.observe(el);
observer.current = ro;
}, []);
/*
* Read the width on commit as well, and do not trust the observer for it.
*
* ResizeObserver's first callback is supposed to arrive right after
* observe(). It does not always: in a throttled or backgrounded rendering
* context the callback never runs at all, and the chart then keeps the 640
* default and letterboxes itself exactly as it did before any of this was
* fixed. Measured here instead, which is synchronous and cannot be
* throttled; the observer stays for later resizes, where it is reliable.
*
* No dependency array on purpose, with the guard below doing the work: a
* layout pass is cheap, a wrong width is a visible bug.
*/
React.useLayoutEffect(() => {
const el = node.current;
if (!el) {
return;
}
const w = Math.round(el.getBoundingClientRect().width);
if (w > 0) {
setWidth((prev) => (Math.abs(prev - w) > 1 ? Math.max(320, w) : prev));
}
});
/*
* The left gutter is as wide as the widest label, not a constant.
*
* It was 34, then 30 to give the drawing more room, and 30 is not enough
* for "100/100" at 9.5px: the leading digit fell off the left edge of the
* answer-score chart and the axis read "00/100". A number that is wrong by
* a factor of ten because of a padding value is worse than a chart that is
* four pixels narrower. Measured from the actual labels this chart will
* draw, so a percentage, a thousands-separated count and a score out of
* 100 each get exactly the room they need.
*/
const pad = { l: 30, r: 6, t: 12, b: 20 };
if (!data || data.length < 2) {
/*
* One reading is the first reading, not missing data.
*
* "Not enough data yet" on a freshly installed plugin appears on every
* chart at once and reads as a wall of broken panels — people conclude
* the charts were never built. When a single point exists, show it: the
* number, when it was taken, and what makes the line appear. Only a
* genuinely empty series says nothing is there.
*/
const one = data && data.length === 1 ? data[0] : null;
return (
{one && (
{formatValue(one.value)}
)}
{one
? one.date
? sprintf(__('First reading · %s', 'ai-rank-suite'), one.date)
: __('First reading', 'ai-rank-suite')
: sprintf(__('No %s recorded yet', 'ai-rank-suite'), String(label))}
{one
? __('A line needs two points. The next reading draws it.', 'ai-rank-suite')
: sprintf(__('%s appears here once there are two readings.', 'ai-rank-suite'), label)}
);
}
const values = data.map((d) => d.value);
const rawMax = Math.max(...values);
const rawMin = Math.min(...values);
// Counts read best against zero; a rank series clustered around 8.6 would
// look flat on a 0-based axis, so scale it to its own range.
const span = Math.max(rawMax - rawMin, 1e-6);
const padding = invert ? span * 0.2 : 0;
const min = invert ? rawMin - padding : 0;
const max = invert ? rawMax + padding : Math.max(1, axisMax ?? rawMax);
const range = Math.max(max - min, 1e-6);
const yValue = (f) => (invert ? min + f * range : max - f * range);
/*
* Widen the gutter before anything is placed in it.
*
* This has to happen above x() and the path, or the axis moves and the
* line does not: labels and curve would be drawn against two different
* left edges. 9.5px in this face runs about 5.4px per character, six
* pixels of air to the axis, never narrower than the old constant.
*/
pad.l = Math.max(
30,
Math.round(
Math.max(...GRID_LINES.map((f) => String(formatValue(Math.round(yValue(f) * 10) / 10)).length)) * 5.4 + 8
)
);
const x = (i) => pad.l + (i * (width - pad.l - pad.r)) / (data.length - 1);
const y = (v) => {
const t = (v - min) / range;
return pad.t + (invert ? t : 1 - t) * (height - pad.t - pad.b);
};
// Smooth monotone-ish curve: Catmull-Rom converted to cubic Beziers.
const pts = data.map((d, i) => [x(i), y(d.value)]);
let path = `M${pts[0][0].toFixed(1)},${pts[0][1].toFixed(1)}`;
for (let i = 0; i < pts.length - 1; i++) {
const p0 = pts[Math.max(0, i - 1)];
const p1 = pts[i];
const p2 = pts[i + 1];
const p3 = pts[Math.min(pts.length - 1, i + 2)];
const c1 = [p1[0] + (p2[0] - p0[0]) / 6, p1[1] + (p2[1] - p0[1]) / 6];
const c2 = [p2[0] - (p3[0] - p1[0]) / 6, p2[1] - (p3[1] - p1[1]) / 6];
path += ` C${c1[0].toFixed(1)},${c1[1].toFixed(1)} ${c2[0].toFixed(1)},${c2[1].toFixed(1)} ${p2[0].toFixed(1)},${p2[1].toFixed(1)}`;
}
const area = `${path} L${pts[pts.length - 1][0].toFixed(1)},${height - pad.b} L${pts[0][0].toFixed(1)},${height - pad.b} Z`;
const gridLines = GRID_LINES;
const last = pts[pts.length - 1];
const trendUp = invert ? values[values.length - 1] < values[0] : values[values.length - 1] > values[0];
return (
);
}
/**
* Ranking position badge: podium tones for 1-3, blue for page one, neutral after.
*/
export function PosBadge({ value }) {
if (value === null || value === undefined || value === 0) {
return —;
}
const v = Math.round(value * 10) / 10;
const tone = v <= 3 ? { bg: 'var(--ars-good-tonal)', fg: 'var(--ars-good)' }
: v <= 10 ? { bg: 'var(--ars-brand-tonal)', fg: 'var(--ars-brand-tonal-ink)' }
: { bg: 'var(--ars-surface-3)', fg: 'var(--ars-ink-2)' };
return (
{v}
);
}
/**
* @param {boolean} [running] A run is in flight: the fill carries the same
* moving stripes the audit uses. A bar that only
* grows every twenty seconds looks stopped, and to
* somebody watching it that is the difference
* between "working" and "crashed". Every screen
* that reports a job through this component gets
* it — one change instead of eight.
*/
/**
* The progress of a run, drawn the same way everywhere.
*
* There were two designs. Long jobs on the site audit and the link structure
* used a 10px striped bar that moves while the run does, with the count on the
* left and the percentage on the right. The link checker, the bulk screen and
* the site analyzer used `Bar`: six flat pixels, no percentage, labels written
* by hand in each file with their own wording. Same product, same kind of
* wait, three different answers to "is this still working?".
*
* This is the striped one, as a component, so a screen states what it is doing
* and gets the rest. `Bar` stays for what it is good at: a proportion that is
* not a run, like a budget or an average.
*
* @param {object} props
* @param {string} props.label What the run is doing right now.
* @param {number} [props.done] Units finished, for "12 of 40".
* @param {number} [props.total] Units in total; 0 or absent draws a full bar for work that cannot be counted.
* @param {number} [props.percent] Overrides the percentage derived from done/total.
* @param {React.ReactNode} [props.note] One line under the bar.
*/
export function Progress({ label, done, total, percent, note }) {
const counted = Number(total) > 0;
const pct = Math.max(
0,
Math.min(100, undefined !== percent && null !== percent ? Math.round(percent) : counted ? Math.round((Number(done) / Number(total)) * 100) : 100)
);
return (
);
}
export function Notice({ tone = 'warning', children }) {
// WordPress has one shape for "read this before you carry on": a white
// panel with a four-pixel coloured edge on the left. Every core screen and
// every plugin worth trusting uses it, so a user reads it without having to
// learn it. The tone only decides which colour that edge is.
const map = {
warning: { klass: 'is-warning', edge: 'var(--ars-warning)' },
serious: { klass: 'is-error', edge: 'var(--ars-serious)' },
info: { klass: 'is-info', edge: 'var(--ars-info-ink)' },
good: { klass: 'is-success', edge: 'var(--ars-good)' },
};
const t = map[tone] || map.warning;
return (
{children}
);
}
/* ---------- Quality meters ---------- */
/**
* Length ranges Google actually respects. Below `ok` the snippet wastes
* space, above `max` it gets truncated in the SERP.
*/
const LENGTH_RULES = {
title: { ok: 30, good: 50, best: 60, max: 60, label: __('SEO title', 'ai-rank-suite') },
description: { ok: 70, good: 120, best: 158, max: 160, label: __('Meta description', 'ai-rank-suite') },
};
function lengthVerdict(len, kind = 'title') {
const r = LENGTH_RULES[kind];
if (len === 0) return { tone: 'empty', color: 'var(--ars-ink-3)', text: __('Empty — falls back to the page title', 'ai-rank-suite') };
if (len > r.max) {
return {
tone: 'bad',
color: 'var(--ars-serious)',
text: sprintf(
_n('%d character too long — Google will cut it off', '%d characters too long — Google will cut it off', len - r.max, 'ai-rank-suite'),
len - r.max
),
};
}
if (len < r.ok) return { tone: 'bad', color: 'var(--ars-serious)', text: __('Too short to be persuasive', 'ai-rank-suite') };
if (len < r.good) return { tone: 'warn', color: 'var(--ars-warning)', text: __('Usable — a little more detail would help', 'ai-rank-suite') };
return { tone: 'good', color: 'var(--ars-good)', text: __('Perfect length', 'ai-rank-suite') };
}
/**
* Length meter: a neutral track with one marked zone — the target — and a
* live fill whose colour is the verdict.
*
* The four painted zones this replaces said the same thing four times and
* louder than the field they sat under. The fill's colour already carries
* short/usable/perfect/too-long; the single green band marks where to aim.
*/
export function LengthMeter({ value = '', kind = 'title', showText = true }) {
const r = LENGTH_RULES[kind];
const len = String(value || '').length;
const v = lengthVerdict(len, kind);
const scale = r.max * 1.25; // Leave room to visualise overrun.
const pct = (n) => Math.min(100, (n / scale) * 100);
return (
{len > 0 && (
)}
{showText && (
{v.text}
{len} / {r.max}
)}
);
}
/* ---------- Heatmap ---------- */
const HEAT_STOPS = [
{ at: 0, bg: '#fce8e6', fg: '#c5221f' },
{ at: 40, bg: '#fde7cd', fg: '#b06000' },
{ at: 60, bg: '#fef7e0', fg: '#b06000' },
{ at: 75, bg: '#e8f3ea', fg: '#188038' },
{ at: 90, bg: '#ceead6', fg: '#0d652d' },
];
function heatColor(score) {
if (score === null || score === undefined) return { bg: 'var(--ars-surface-3)', fg: 'var(--ars-ink-3)' };
let stop = HEAT_STOPS[0];
for (const s of HEAT_STOPS) if (score >= s.at) stop = s;
return stop;
}
/**
* Content health heatmap: one row per page, one cell per dimension.
* Reading a hundred pages as a grid surfaces patterns a table never will —
* a cold column means a site-wide problem, a cold row means one bad page.
*/
export function Heatmap({ rows, columns, onCell, onRow }) {
const [hover, setHover] = React.useState(null);
if (!rows || rows.length === 0) {
return (
);
}
/* ---------- Micro charts: the vocabulary for dense KPI display ---------- */
/**
* Sparkline: a trend at a glance, no axes, no labels. Deliberately tiny —
* its job is to say "rising" or "falling", not to be read precisely.
*/
export function Sparkline({ data, color = 'currentColor', height = 28, fill = true }) {
const gid = React.useId();
const values = (data || []).filter((v) => typeof v === 'number');
if (values.length < 3) {
return null;
}
const width = 100;
const min = Math.min(...values);
const max = Math.max(...values);
const range = Math.max(max - min, 1e-6);
const pad = 3;
// The endpoint marker sat exactly on x=100 and the first point on x=0, so
// half of each was outside the viewBox — every sparkline in the product
// ended in a stroke that looked cut off. Inset the series by the marker's
// own radius and it closes properly.
const padX = 3;
const x = (i) => padX + (i * (width - padX * 2)) / (values.length - 1);
const y = (v) => pad + (1 - (v - min) / range) * (height - pad * 2);
const pts = values.map((v, i) => [x(i), y(v)]);
let path = `M${pts[0][0].toFixed(1)},${pts[0][1].toFixed(1)}`;
for (let i = 0; i < pts.length - 1; i++) {
const p0 = pts[Math.max(0, i - 1)];
const p1 = pts[i];
const p2 = pts[i + 1];
const p3 = pts[Math.min(pts.length - 1, i + 2)];
const c1 = [p1[0] + (p2[0] - p0[0]) / 6, p1[1] + (p2[1] - p0[1]) / 6];
const c2 = [p2[0] - (p3[0] - p1[0]) / 6, p2[1] - (p3[1] - p1[1]) / 6];
path += ` C${c1[0].toFixed(1)},${c1[1].toFixed(1)} ${c2[0].toFixed(1)},${c2[1].toFixed(1)} ${p2[0].toFixed(1)},${p2[1].toFixed(1)}`;
}
return (
);
}
/**
* MiniBars: a distribution — how many items sit in each band. Reads faster
* than a pie for five-or-fewer categories.
*/
export function MiniBars({ data, colors, height = 28 }) {
const values = (data || []).map((v) => Number(v) || 0);
const max = Math.max(...values, 1);
// Status ramp from the tokens, not a second hand-mixed set of Google reds
// and ambers that only ever appeared in this one chart.
const palette = colors || [
'var(--ars-serious)',
'var(--ars-warning)',
'var(--ars-c-yellow-ink)',
'var(--ars-series-4)',
'var(--ars-good)',
];
return (
{values.map((v, i) => (
))}
);
}
/**
* Delta badge. `invert` for metrics where down is good (rank position,
* broken links) — the arrow follows the number, the colour follows meaning.
*/
export function Delta({ value, suffix = '', invert = false }) {
if (value === null || value === undefined || value === 0) {
return (
±0{suffix}
);
}
const up = value > 0;
const good = invert ? !up : up;
return (
{up ? '▲' : '▼'}
{Math.abs(value)}
{suffix}
);
}
/**
* KPI tile: the launchpad unit. Every tile carries a live number and goes
* somewhere — a tile that only labels a link is a wasted tile.
*/
export function KpiTile({
label,
value,
unit,
sub,
tone = 'plain',
chart,
delta,
onClick,
status,
disabled = false,
}) {
// Container colour and ink come as a pair so text contrast is never left to
// chance; `accent` drives the top hairline and any chart drawn inside.
const tones = {
plain: { bg: 'var(--ars-surface-2)', fg: 'var(--ars-ink)', mute: 'var(--ars-ink-3)', accent: 'var(--ars-ink-3)' },
blue: { bg: 'var(--ars-c-blue)', fg: 'var(--ars-c-blue-ink)', mute: 'var(--ars-c-blue-ink)', accent: 'var(--ars-c-blue-ink)' },
green: { bg: 'var(--ars-c-green)', fg: 'var(--ars-c-green-ink)', mute: 'var(--ars-c-green-ink)', accent: 'var(--ars-c-green-ink)' },
yellow: { bg: 'var(--ars-c-yellow)', fg: 'var(--ars-c-yellow-ink)', mute: 'var(--ars-c-yellow-ink)', accent: 'var(--ars-c-yellow-ink)' },
red: { bg: 'var(--ars-c-red)', fg: 'var(--ars-c-red-ink)', mute: 'var(--ars-c-red-ink)', accent: 'var(--ars-c-red-ink)' },
violet: { bg: 'var(--ars-c-violet)', fg: 'var(--ars-c-violet-ink)', mute: 'var(--ars-c-violet-ink)', accent: 'var(--ars-c-violet-ink)' },
};
const t = tones[tone] || tones.plain;
const Wrapper = onClick ? 'button' : 'div';
const shown = useCountUp(value);
// Digits get display size; words get read, not scanned. A ratio ("0 / 0",
// "37 / 37") is still a figure — excluding the slash dropped those two
// tiles to 21px in a row of 30px numbers, which read as a rendering bug.
const isFigure = typeof value === 'number' || /^[\d.,%/\s-]+$/.test(String(value ?? '').trim() || 'x');
return (
{label}
{status}
{shown}
{unit && (
{unit}
)}
{delta}
{sub && (
{sub}
)}
{chart &&
{chart}
}
);
}
/* ---------- Analytical primitives: the Insights vocabulary ---------- */
/**
* A sticky filter bar. One row, one job: change what the whole page means.
* The filter belongs to the page, not to each individual card.
*/
export function FilterBar({ children, right }) {
return (
{children}
{right &&
{right}
}
);
}
/**
* ChipBar — "narrow this list to one of these".
*
* Site Audit, Sitemap, AI Engine and Content each grew their own version of
* this control: same job, four different looks (solid blue, bordered tab
* strip, tonal segment, plain button). One chip now, with an optional count
* so a filter can say how much it will leave on screen.
*/
export function ChipBar({ options, value, onChange, label, className = '', collapseAt = 24 }) {
// A chip strip scales with the site: 70 sitemap files on a 16k-post site,
// 200+ on a 50k one. Past `collapseAt` the tail folds behind one "+N more"
// chip; the active option is always kept visible.
const [expanded, setExpanded] = React.useState(false);
let shown = options;
if (!expanded && options.length > collapseAt) {
shown = options.slice(0, collapseAt);
const active = options.find((o) => o.id === value);
if (active && !shown.some((o) => o.id === value)) shown = [...shown, active];
}
const hidden = options.length - shown.length;
return (
);
}
/** Segmented control — the compact sibling of Tabs, for filter values. */
export function Segmented({ options, value, onChange, label }) {
return (
{label && (
{label}
)}
{options.map((o) => (
))}
);
}
/**
* Proportional stacked bar — "of everything checked, this much is healthy".
* One bar beats five numbers when the parts sum to a whole.
*/
export function SegmentBar({ segments, height = 12, showLegend = true }) {
const items = (segments || []).filter((s) => s.value > 0);
const total = items.reduce((a, s) => a + s.value, 0);
if (total === 0) {
return (
{__('Nothing measured yet.', 'ai-rank-suite')}
);
}
return (
{items.map((s) => (
))}
{showLegend && (
{items.map((s) => (
{s.label}
{s.value}
))}
)}
);
}
/**
* Ranked horizontal bars. Sorted lists of "how many" read faster this way
* than as a table, and the bar length does the comparing for you.
*/
export function RankBar({ items, max, color = 'var(--ars-brand)', onItem, format = (v) => v }) {
const rows = items || [];
const peak = max ?? Math.max(...rows.map((r) => r.value), 1);
return (
);
}
/**
* Column chart for daily activity. Deliberately axis-light: the question is
* "did anything happen and when", not "exactly how much".
*
* `stacked` piles the series into one column per row instead of grouping
* them side by side — for compositions, where the column's full height is a
* total that means something (all tracked keywords on that day) and the
* bands inside it are its parts. A grouped chart of the same data would make
* the reader do the addition themselves.
*/
export function ColumnChart({ data, series, height = 110, stacked = false }) {
const rows = data || [];
const keys = series || [];
const peak = stacked
? Math.max(1, ...rows.map((r) => keys.reduce((a, k) => a + (Number(r[k.key]) || 0), 0)))
: Math.max(1, ...rows.map((r) => keys.reduce((a, k) => Math.max(a, Number(r[k.key]) || 0), 0)));
const step = Math.max(1, Math.ceil(rows.length / 8));
return (
);
}
/**
* Label + control + hint, in the one arrangement every settings screen uses.
*
* Written out by hand this is four lines and two class strings, which is how
* the same field ended up with `mb-1` on one page and `mb-1.5` on the next.
*/
export function Field({ label, hint, htmlFor, children, className = '', span = false }) {
return (
{label && (
)}
{children}
{/* WordPress calls this a description and gives it one look on every
settings screen in core. Same class, same look. */}
{hint &&
{hint}
}
);
}
/**
* Pick an image from the WordPress media library.
*
* Deliberately not a file input: the library is where the site's images
* already are, it gives us the URL WordPress will actually serve, and the user
* has driven this dialog before. Falls back to a plain URL field if the media
* scripts are not on the page, so the field is never dead.
*/
export function MediaPicker({ value, onChange, label, hint, title = __('Select image', 'ai-rank-suite'), height = 96 }) {
const open = () => {
const media = window.wp?.media;
if (!media) return;
const frame = media({ title, button: { text: __('Use this image', 'ai-rank-suite') }, multiple: false, library: { type: 'image' } });
frame.on('select', () => {
const attachment = frame.state().get('selection').first().toJSON();
// The full-size URL is what schema consumers want; sizes.full exists
// only when WordPress generated one.
onChange(attachment.sizes?.full?.url || attachment.url || '');
});
frame.open();
};
const hasMedia = !!window.wp?.media;
return (
{value ? (
) : (
{__('None', 'ai-rank-suite')}
)}
onChange(e.target.value)}
/>
{hasMedia && (
)}
{value && (
)}
);
}
/**
* A free-form list of short strings — service areas, languages, profile URLs.
*
* Enter and comma both commit, because people type both. Backspace on an empty
* field removes the last chip, which is the behaviour every tag field has.
*/
export function TagInput({ value = [], onChange, placeholder = __('Add and press Enter', 'ai-rank-suite'), suggestions = [] }) {
const [draft, setDraft] = React.useState('');
const commit = (raw) => {
const parts = String(raw)
.split(',')
.map((p) => p.trim())
.filter(Boolean);
if (!parts.length) return;
const next = [...value];
parts.forEach((p) => {
if (!next.includes(p)) next.push(p);
});
onChange(next);
setDraft('');
};
const remaining = suggestions.filter((sug) => !value.includes(sug)).slice(0, 8);
return (
);
}
/**
* A set of checkboxes laid out as a responsive grid, for catalogues that are
* too long for a row of switches and too short for a multi-select.
*/
export function CheckGrid({ options, value = [], onChange, min = '180px' }) {
const toggle = (key) => onChange(value.includes(key) ? value.filter((v) => v !== key) : [...value, key]);
return (
{options.map((o) => (
))}
);
}
/**
* Read-only code with a copy button. Six pages had grown their own.
*/
export function CodeBlock({ code, max = 420, language = '' }) {
const [copied, setCopied] = React.useState(false);
return (
{code}
);
}
/**
* The shape of a screen while its data is on the way.
*
* A module that renders nothing until its first request returns looks broken
* for the second or two that request takes — and on a large site with a slow
* host it is four seconds, which reads as "the plugin hung". A skeleton in the
* layout the page is about to take says "loading", holds the scroll position,
* and stops the content from jumping when it lands.
*/
export function PageSkeleton({ blocks = 3, hero = true, label = 'Loading' }) {
return (
{hero && }
{Array.from({ length: blocks }, (_, i) => (
))}
{label}…
);
}
/**
* Where a single number stands in the range it lives in.
*
* A score out of 100 has a shape even with one reading: the distance left to
* the band you want to be in. Three bands, a marker, and the number — which
* is more information than a flat line and reads in about a second.
*/
export function BandScale({ value, color, bands }) {
// A shared component cannot assume its caller passed the one prop it
// cannot work without. Two TrendCards did not, and every screen that
// mounted them went to the error boundary the moment their chart had no
// shape to draw — which is to say on a fresh install, on the first day,
// which is exactly when somebody is deciding whether to keep this.
if (!Array.isArray(bands) || 0 === bands.length) return null;
const v = Math.max(0, Math.min(100, Number(value) || 0));
const zone = bands.find((b) => v < b.to) || bands[bands.length - 1];
/*
* Its own root class, not `ars-gauge`.
*
* Two unrelated components shared that name: the SVG arc above, which is
* 150px wide by design, and this band meter, which has to be full width or
* its percentage bands resolve against nothing. The rule that gave this one
* `width: 100%` is later in the stylesheet, so it won — and the arc gauge
* stretched to fill whatever card it was in. On the site-tests screen that
* was a 96 rendered about a foot tall.
*/
return (
{v}/ 100{zone.label}
{bands.map((b, i) => (
))}
{bands.map((b, i) => (
{b.label}
))}
);
}
/**
* What a total is made of, when its history is still one point.
*
* 321 open findings is a number. "0 critical, 14 warnings, 307 notices" is a
* decision — and it is the same data, already on the card as tiles.
*/
export function Composition({ parts, total }) {
const sum = parts.reduce((a, p) => a + (p.value || 0), 0) || 1;
return (
) : (
{__('None', 'ai-rank-suite')}
)}