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 (
{/* The identity gradient — this is a score instrument, one of the three places the brand ramp is allowed to appear. */} {pct > 0 && ( )} {value} / {max} {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')}

{__('See Pro', 'ai-rank-suite')}
); } if (error) { return (
{error}

{__('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 (
{metrics.map((m) => { const Tag = onSelect ? 'button' : 'div'; return ( onSelect(m.id || m.label) : undefined} style={m.accent ? { '--ars-metric-accent': m.accent } : undefined} > {m.label} {m.hint && ( ? )} {m.value} {m.unit && {m.unit}} {m.delta !== undefined && m.delta !== null && } {m.spark && m.spark.length > 1 && ( )} {m.sub && {m.sub}} {m.accent && } ); })}
); } /** * 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) => { const share = (r.value || 0) / total; const dash = `${share * C} ${C}`; const rot = `rotate(${-90 + (offset / total) * 360} 70 70)`; offset += r.value || 0; return ( ); })} {value} / {max}
{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 (
{label} {invert ? sprintf(__('best %s', 'ai-rank-suite'), formatValue(rawMin)) : sprintf(__('peak %s', 'ai-rank-suite'), formatValue(rawMax))}
setHover(null)} onMouseMove={(e) => { const rect = e.currentTarget.getBoundingClientRect(); const px = ((e.clientX - rect.left) / rect.width) * width; const i = Math.round(((px - pad.l) / (width - pad.l - pad.r)) * (data.length - 1)); setHover({ i: Math.max(0, Math.min(data.length - 1, i)) }); }} role="img" aria-label={label} > {gridLines.map((f) => ( {formatValue(Math.round(yValue(f) * 10) / 10)} ))} {/* Endpoint marker — the ring is the surface colour, so it reads as a punched hole in both themes instead of a hardcoded white halo. */} {hover && ( {(() => { const tip = `${data[hover.i].date} · ${formatValue(data[hover.i].value)}`; const w = tip.length * 6.2 + 18; const tx = Math.max(pad.l, Math.min(width - pad.r - w, x(hover.i) - w / 2)); const ty = Math.max(2, y(data[hover.i].value) - 30); // Ink-on-ink inverted chip: --ars-ink is near-black in light and // near-white in dark, so pairing it with --ars-surface text keeps // the tooltip readable in both themes (ink+white was white-on-white // the moment the dark palette landed). return ( {tip} ); })()} )} {data[0].date} {data[data.length - 1].date}
); } /** * 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 (
{label} {counted && {pct}%}
{note && (

{note}

)}
); } export function Bar({ value, color, running = false }) { const pct = Math.max(0, Math.min(100, value ?? 0)); 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 (
{__('Nothing analyzed yet.', 'ai-rank-suite')}
); } return (
{columns.map((c) => ( ))} {rows.map((row) => ( {columns.map((c) => { const score = row.values[c.key]; const heat = heatColor(score); const key = `${row.id}-${c.key}`; const isHover = hover === key; return ( ); })} ))}
{__('Page', 'ai-rank-suite')} {c.label}
onRow && onRow(row)} > {row.label}
{__('Needs work', 'ai-rank-suite')} {HEAT_STOPS.map((s) => ( ))} {__('Excellent', 'ai-rank-suite')}
); } /* ---------- 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 ( {fill && } {/* No endpoint marker: preserveAspectRatio="none" turns a circle into an ellipse, and the one it drew sat half outside the viewBox. */} ); } /** * 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 (
{label && ( {label} )} {shown.map((o) => ( ))} {hidden > 0 && ( )} {expanded && options.length > collapseAt && ( )}
); } /** 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 (
{rows.map((r, i) => (
onItem(r) : undefined} role={onItem ? 'button' : undefined} tabIndex={onItem ? 0 : undefined} onKeyDown={onItem ? (e) => e.key === 'Enter' && onItem(r) : undefined} > {r.label} {format(r.value)}
))}
); } /** * 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 (
{rows.map((r, i) => stacked ? (
`${k.label}: ${Number(r[k.key]) || 0}`).join(' · ')}`} > {keys.map((k, ki) => { const v = Number(r[k.key]) || 0; return ( !(Number(r[kk.key]) || 0)) && v > 0 ? 'var(--ars-r-xs) var(--ars-r-xs) 0 0' : 0, transition: 'height 380ms cubic-bezier(0.2,0,0,1)', }} /> ); })}
) : (
{keys.map((k) => { const v = Number(r[k.key]) || 0; return ( ); })}
) )}
{rows .filter((_, i) => i % step === 0) .map((r, i) => ( {r.label} ))}
{keys.map((k) => ( {k.label} ))}
); } /** * 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 (
{value.length > 0 && (
{value.map((tag) => ( {tag} ))}
)} setDraft(e.target.value)} onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ',') { e.preventDefault(); commit(draft); } else if (e.key === 'Backspace' && draft === '' && value.length) { onChange(value.slice(0, -1)); } }} onBlur={() => commit(draft)} /> {remaining.length > 0 && (
{remaining.map((sug) => ( ))}
)}
); } /** * 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 (
`${p.label}: ${p.value}`).join(', ')}> {parts.filter((p) => (p.value || 0) > 0).map((p) => ( ))}
{parts.map((p) => ( {Number(p.value || 0).toLocaleString()} {p.label} ))}
{total !== null && total !== undefined && (

{sprintf( /* translators: %s: total. */ __('%s in total right now', 'ai-rank-suite'), Number(total).toLocaleString() )}

)}
); }