create-nextblock 0.15.10 → 0.16.2

package/templates/nextblock-template/components/seo/SeoIssueList.tsx

@@ -0,0 +1,195 @@
+'use client';
+
+/**
+ * The findings half of the SEO panel: every issue the audit raised, grouped
+ * under the part of the page it belongs to, each with the one-click Cortex AI
+ * repair where the engine says a repair is possible.
+ *
+ * Grouping by category rather than listing findings in severity order is a
+ * deliberate trade. Severity order answers "what is worst?", which the score
+ * dial and the summary counts already answer; category order answers "what do I
+ * have to go and change?", which is the question someone with the document open
+ * in front of them is actually asking. Within a category the audit's own
+ * severity ordering is preserved, so the worst thing in each section still
+ * comes first.
+ *
+ * Severity is never carried by colour alone. Each finding gets an icon and a
+ * spelled-out word ("Error", "Warning", "Suggestion") next to the tint, so the
+ * list reads identically to someone who cannot distinguish red from amber, and
+ * survives being printed or screenshotted in greyscale.
+ */
+
+import * as React from 'react';
+
+import { Button } from '@nextblock-cms/ui';
+import { cn } from '@nextblock-cms/utils';
+import type { SeoIssue, SeoIssueCategory, SeoIssueSeverity } from '@nextblock-cms/utils/seo';
+import { AlertTriangle, Info, Loader2, Sparkles, XCircle } from 'lucide-react';
+
+import { canFixIssueWithCortexAi } from '../../lib/seo/fix-prompts';
+
+/**
+ * Category order, chosen to walk the document the way an author does: fix the
+ * skeleton first (headings), then how it reads, then what it is about, then how
+ * much of it there is, then its assets, and finally the metadata that wraps it.
+ */
+const CATEGORY_ORDER: SeoIssueCategory[] = [
+  'headings',
+  'readability',
+  'keyword',
+  'content',
+  'images',
+  'meta',
+];
+
+const CATEGORY_LABEL: Record<SeoIssueCategory, string> = {
+  content: 'Content',
+  headings: 'Headings',
+  images: 'Images',
+  keyword: 'Keyphrase',
+  meta: 'Meta',
+  readability: 'Readability',
+};
+
+/**
+ * Severity styling, following the same raw-palette-with-dark-variant pattern as
+ * `VisibilityControl`: red for something materially broken, amber for something
+ * measurably worse than it should be, and the neutral muted tokens for advice
+ * the author is free to ignore.
+ */
+const SEVERITY_STYLE: Record<SeoIssueSeverity, string> = {
+  error: 'border-red-500/40 bg-red-500/10',
+  info: 'border-border bg-muted/40',
+  warning: 'border-amber-500/40 bg-amber-500/10',
+};
+
+const SEVERITY_ICON_STYLE: Record<SeoIssueSeverity, string> = {
+  error: 'text-red-600 dark:text-red-400',
+  info: 'text-muted-foreground',
+  warning: 'text-amber-600 dark:text-amber-400',
+};
+
+const SEVERITY_ICON: Record<SeoIssueSeverity, React.ComponentType<{ className?: string }>> = {
+  error: XCircle,
+  info: Info,
+  warning: AlertTriangle,
+};
+
+/** "Suggestion" rather than "Info": it tells the reader what to do with it. */
+const SEVERITY_LABEL: Record<SeoIssueSeverity, string> = {
+  error: 'Error',
+  info: 'Suggestion',
+  warning: 'Warning',
+};
+
+export interface SeoIssueListProps {
+  /** The issue whose fix is in flight, if any; disables every other button. */
+  busyIssueId?: string | null;
+  className?: string;
+  /** Failure text from the last fix attempt, keyed by issue id. */
+  errors?: Record<string, string>;
+  issues: SeoIssue[];
+  /**
+   * Runs the Cortex AI repair. Leaving this undefined removes every Fix button
+   * from the list — which is how the panel expresses both "Cortex AI is not
+   * activated on this install" and "no editor instance was handed to us", two
+   * situations where offering the button would only produce a dead click.
+   */
+  onFix?: (issue: SeoIssue) => void;
+}
+
+export function SeoIssueList({ busyIssueId, className, errors, issues, onFix }: SeoIssueListProps) {
+  const grouped = React.useMemo(() => {
+    return CATEGORY_ORDER.map((category) => ({
+      category,
+      issues: issues.filter((issue) => issue.category === category),
+    })).filter((group) => group.issues.length > 0);
+  }, [issues]);
+
+  if (grouped.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className={cn('space-y-4', className)}>
+      {grouped.map((group) => (
+        <section key={group.category} className="space-y-2">
+          <h4 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+            {CATEGORY_LABEL[group.category]}
+          </h4>
+
+          <ul className="space-y-2">
+            {group.issues.map((issue) => {
+              const Icon = SEVERITY_ICON[issue.severity];
+              const isBusy = busyIssueId === issue.id;
+              const error = errors?.[issue.id];
+              const showFix = onFix !== undefined && canFixIssueWithCortexAi(issue);
+
+              return (
+                <li
+                  key={issue.id}
+                  className={cn('rounded-md border p-2.5 text-sm', SEVERITY_STYLE[issue.severity])}
+                >
+                  <div className="flex items-start gap-2">
+                    <Icon
+                      aria-hidden="true"
+                      className={cn('mt-0.5 h-4 w-4 shrink-0', SEVERITY_ICON_STYLE[issue.severity])}
+                    />
+                    <div className="min-w-0 flex-1 space-y-1">
+                      <p className="font-medium leading-snug">
+                        <span className="sr-only">{SEVERITY_LABEL[issue.severity]}: </span>
+                        {issue.message}
+                      </p>
+                      {issue.detail && (
+                        <p className="text-xs leading-relaxed text-muted-foreground">
+                          {issue.detail}
+                        </p>
+                      )}
+                      <p
+                        aria-hidden="true"
+                        className={cn(
+                          'text-[11px] font-semibold uppercase tracking-wide',
+                          SEVERITY_ICON_STYLE[issue.severity]
+                        )}
+                      >
+                        {SEVERITY_LABEL[issue.severity]}
+                      </p>
+                    </div>
+                  </div>
+
+                  {showFix && (
+                    <div className="mt-2 flex justify-end">
+                      <Button
+                        className="h-7 text-xs"
+                        disabled={busyIssueId !== null && busyIssueId !== undefined}
+                        onClick={() => onFix?.(issue)}
+                        size="sm"
+                        type="button"
+                        variant="outline"
+                      >
+                        {isBusy ? (
+                          <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />
+                        ) : (
+                          <Sparkles className="mr-1.5 h-3.5 w-3.5" />
+                        )}
+                        {isBusy ? 'Fixing…' : 'Fix with Cortex AI'}
+                      </Button>
+                    </div>
+                  )}
+
+                  {error && (
+                    <p className="mt-2 text-xs text-destructive" role="alert">
+                      {error}
+                    </p>
+                  )}
+                </li>
+              );
+            })}
+          </ul>
+        </section>
+      ))}
+    </div>
+  );
+}
+
+export default SeoIssueList;

package/templates/nextblock-template/components/seo/SeoScoreDial.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+/**
+ * The 0-100 SEO score, drawn as a ring.
+ *
+ * Built from inline SVG rather than the shared `Progress` primitive because the
+ * primitive hard-codes `bg-primary` on its indicator, and the whole point of
+ * this control is that its colour carries the verdict: emerald when the page is
+ * in good shape, amber when it needs attention, red when it is failing. A bar
+ * that is always brand-purple would force the reader to parse the number before
+ * they learn anything, which defeats having a meter at all.
+ *
+ * Accessibility is the other reason for hand-drawing it. The ring is exposed as
+ * an ARIA `meter` with a real name, a real value and a spoken `aria-valuetext`
+ * that includes the band, so a screen reader announces "SEO score: 82 out of
+ * 100, good" instead of reading an unlabelled graphic. The band is also printed
+ * as text under the ring, so nothing here is communicated by colour alone.
+ */
+
+import * as React from 'react';
+
+import { cn } from '@nextblock-cms/utils';
+import type { SeoAuditScope, SeoScoreBand } from '@nextblock-cms/utils/seo';
+
+/**
+ * Band to colour, following the CMS convention set by `VisibilityControl`:
+ * emerald reads as fine, amber as a caution, red as a failure.
+ *
+ * `excellent` and `good` deliberately share emerald. Splitting them across two
+ * hues would introduce a fourth colour with no established meaning in this UI;
+ * the difference between the two bands is carried by the label instead, which
+ * is the part a reader can actually act on.
+ */
+const BAND_STROKE: Record<SeoScoreBand, string> = {
+  excellent: 'text-emerald-500',
+  fair: 'text-amber-500',
+  good: 'text-emerald-500',
+  poor: 'text-red-500',
+};
+
+const BAND_TEXT: Record<SeoScoreBand, string> = {
+  excellent: 'text-emerald-700 dark:text-emerald-400',
+  fair: 'text-amber-700 dark:text-amber-400',
+  good: 'text-emerald-700 dark:text-emerald-400',
+  poor: 'text-red-700 dark:text-red-400',
+};
+
+/** Reader-facing wording for each band; `poor` is phrased as work, not failure. */
+const BAND_LABEL: Record<SeoScoreBand, string> = {
+  excellent: 'Excellent',
+  fair: 'Fair',
+  good: 'Good',
+  poor: 'Needs work',
+};
+
+/**
+ * What the number under the ring is a score *of*.
+ *
+ * This caption is the one line that tells a reader whether they are looking at a
+ * verdict on the whole page or on the paragraph in front of them, and confusing
+ * the two is the exact bug the page-level audit was introduced to end. It is
+ * therefore keyed off the scope rather than written once and left to drift.
+ */
+const SCOPE_CAPTION: Record<SeoAuditScope, string> = {
+  block: 'Weighted across the checks a single block can pass or fail.',
+  page: 'Weighted across every check that applies to this page.',
+};
+
+export interface SeoScoreDialProps {
+  band: SeoScoreBand;
+  className?: string;
+  /** 0-100. Values outside that range are clamped rather than drawn wrong. */
+  score: number;
+  /** Defaults to `'page'`, matching the audit engine's own default scope. */
+  scope?: SeoAuditScope;
+}
+
+/**
+ * Geometry constants. The ring is drawn in a fixed 120x120 user-space viewBox
+ * and scaled by CSS, so the stroke stays circular at any rendered size and the
+ * dash maths below never has to know how big the element ended up on screen.
+ */
+const RADIUS = 52;
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+
+export function SeoScoreDial({ band, className, score, scope = 'page' }: SeoScoreDialProps) {
+  const clamped = Math.max(0, Math.min(100, Math.round(Number.isFinite(score) ? score : 0)));
+  // A stroke-dashoffset of the full circumference is an empty ring and an
+  // offset of zero is a full one, so the filled fraction is the complement.
+  const dashOffset = CIRCUMFERENCE * (1 - clamped / 100);
+
+  return (
+    <div className={cn('flex items-center gap-4', className)}>
+      <div
+        aria-label="SEO score"
+        aria-valuemax={100}
+        aria-valuemin={0}
+        aria-valuenow={clamped}
+        aria-valuetext={`${clamped} out of 100, ${BAND_LABEL[band].toLowerCase()}`}
+        className="relative h-20 w-20 shrink-0"
+        role="meter"
+      >
+        <svg className="h-full w-full -rotate-90" viewBox="0 0 120 120">
+          <circle
+            className="text-muted"
+            cx="60"
+            cy="60"
+            fill="none"
+            r={RADIUS}
+            stroke="currentColor"
+            strokeWidth="10"
+          />
+          <circle
+            className={cn('transition-[stroke-dashoffset] duration-500', BAND_STROKE[band])}
+            cx="60"
+            cy="60"
+            fill="none"
+            r={RADIUS}
+            stroke="currentColor"
+            strokeDasharray={CIRCUMFERENCE}
+            strokeDashoffset={dashOffset}
+            strokeLinecap="round"
+            strokeWidth="10"
+          />
+        </svg>
+        {/* The number inside the ring duplicates `aria-valuetext`, so it is
+            hidden from assistive technology to avoid announcing it twice. */}
+        <span
+          aria-hidden="true"
+          className="absolute inset-0 flex items-center justify-center text-xl font-semibold tabular-nums"
+        >
+          {clamped}
+        </span>
+      </div>
+
+      <div className="min-w-0">
+        <p className={cn('text-sm font-semibold', BAND_TEXT[band])}>{BAND_LABEL[band]}</p>
+        <p className="text-xs text-muted-foreground">{SCOPE_CAPTION[scope]}</p>
+      </div>
+    </div>
+  );
+}
+
+export default SeoScoreDial;

package/templates/nextblock-template/components/seo/SocialPreview.tsx

@@ -0,0 +1,243 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+import { ImageIcon, MessageCircle, Repeat2, Heart, ThumbsUp, Share2 } from 'lucide-react';
+import { cn } from '@nextblock-cms/utils';
+
+/**
+ * A read-only rehearsal of the share card a page will produce.
+ *
+ * The value here is not decoration. Meta title and description are the two fields an
+ * operator is most likely to get wrong in a way nothing else in the CMS will catch:
+ * they are invisible on the page itself, and the consequence — a headline chopped
+ * mid-word in someone's feed — only shows up after the link has already been shared.
+ * Rendering the truncation locally turns that into a visible, immediate edit.
+ *
+ * The three tabs are genuinely different, not one box repainted, because the platforms
+ * genuinely differ. Facebook shows a wide image above a grey caption bar with the domain
+ * in small caps and a hard title clamp. X's summary_large_image card has no caption bar
+ * and stamps the domain UNDER the text. LinkedIn keeps the image and gives the headline
+ * more room but drops the description entirely — which is exactly the surprise worth
+ * showing someone who has just spent five minutes wording a description. If all three
+ * looked the same, the component would be teaching a falsehood.
+ *
+ * The numbers below approximate observed rendering rather than a published spec — every
+ * platform reserves the right to reflow — so they are tuned to be slightly pessimistic.
+ * A preview that clips a little early nudges toward safer copy; one that clips late gives
+ * false confidence, which is the failure that actually costs something.
+ */
+interface SocialPreviewProps {
+  description: string;
+  imageUrl?: string | null;
+  siteName?: string | null;
+  title: string;
+  url: string;
+}
+
+type SocialPlatform = 'facebook' | 'linkedin' | 'x';
+
+const PLATFORM_TABS: ReadonlyArray<{ id: SocialPlatform; label: string }> = [
+  { id: 'facebook', label: 'Facebook' },
+  { id: 'x', label: 'X' },
+  { id: 'linkedin', label: 'LinkedIn' },
+];
+
+/**
+ * Per-platform clamps, in characters. `description: 0` means the platform does not render
+ * a description at all — a meaningfully different statement from "renders a short one",
+ * and drawn differently below.
+ */
+const PLATFORM_LIMITS: Record<SocialPlatform, { description: number; title: number }> = {
+  facebook: { description: 110, title: 65 },
+  linkedin: { description: 0, title: 90 },
+  x: { description: 125, title: 70 },
+};
+
+/**
+ * Clip to a character budget the way a feed does — at a word boundary, with an ellipsis —
+ * rather than mid-word, so the preview shows the shape of the real damage.
+ */
+function clampToLength(value: string, maxLength: number): string {
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  if (maxLength <= 0 || normalized.length <= maxLength) {
+    return normalized;
+  }
+
+  const sliced = normalized.slice(0, maxLength);
+  const lastSpace = sliced.lastIndexOf(' ');
+  const kept = lastSpace > maxLength * 0.6 ? sliced.slice(0, lastSpace) : sliced;
+  return `${kept.trimEnd()}…`;
+}
+
+/**
+ * The domain each platform stamps on the card. Falls back to the raw string when the URL
+ * is not parseable — while a slug is being typed, `url` is briefly not a valid URL.
+ */
+function toDisplayDomain(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, '');
+  } catch {
+    return url.replace(/^https?:\/\//i, '').split('/')[0] || url;
+  }
+}
+
+/**
+ * Remote share images render through a plain `<img>`, deliberately.
+ *
+ * `next/image` would require every host an operator might point a feature image at to be
+ * pre-declared in `next.config` `images.remotePatterns`, and an undeclared host does not
+ * degrade — it throws. The CMS already makes this call the same way: the external-URL
+ * branch of `ImageBlockEditor` drops to a plain `<img>` for precisely this reason. A
+ * preview thumbnail gains nothing from the optimizer in exchange for that fragility.
+ */
+function PreviewImage({
+  aspectClassName,
+  imageUrl,
+  title,
+}: {
+  aspectClassName: string;
+  imageUrl?: string | null;
+  title: string;
+}) {
+  if (!imageUrl) {
+    return (
+      <div
+        className={cn(
+          'flex w-full flex-col items-center justify-center gap-1 bg-muted text-muted-foreground',
+          aspectClassName
+        )}
+      >
+        <ImageIcon aria-hidden="true" className="h-6 w-6" />
+        <span className="text-[10px] font-medium uppercase tracking-wide">No share image</span>
+      </div>
+    );
+  }
+
+  return (
+    // eslint-disable-next-line @next/next/no-img-element
+    <img
+      alt={`Share preview for ${title}`}
+      className={cn('w-full bg-muted object-cover', aspectClassName)}
+      loading="lazy"
+      src={imageUrl}
+    />
+  );
+}
+
+export default function SocialPreview({
+  description,
+  imageUrl,
+  siteName,
+  title,
+  url,
+}: SocialPreviewProps) {
+  const [platform, setPlatform] = useState<SocialPlatform>('facebook');
+
+  const domain = useMemo(() => toDisplayDomain(url), [url]);
+  const limits = PLATFORM_LIMITS[platform];
+  const clampedTitle = clampToLength(title || 'Untitled', limits.title);
+  const clampedDescription = clampToLength(description, limits.description);
+  // LinkedIn labels the card with the publisher name when one is known and quietly falls
+  // back to the bare domain when it is not; Facebook and X only ever show the domain.
+  const publisher = (siteName ?? '').trim() || domain;
+
+  return (
+    <div className="space-y-2">
+      {/* Hand-rolled tabs: this design system ships no Tabs primitive, and the house
+          pattern for a small switcher is buttons plus useState. The ARIA roles restore
+          the semantics a real tab component would have provided for free. */}
+      <div
+        aria-label="Social platform preview"
+        className="inline-flex items-center gap-1 rounded-md border border-border bg-muted/40 p-0.5"
+        role="tablist"
+      >
+        {PLATFORM_TABS.map((tab) => (
+          <button
+            aria-selected={platform === tab.id}
+            className={cn(
+              'rounded px-2.5 py-1 text-[11px] font-medium transition-colors',
+              platform === tab.id
+                ? 'bg-background text-foreground shadow-sm'
+                : 'text-muted-foreground hover:text-foreground'
+            )}
+            key={tab.id}
+            onClick={() => setPlatform(tab.id)}
+            role="tab"
+            type="button"
+          >
+            {tab.label}
+          </button>
+        ))}
+      </div>
+
+      {platform === 'facebook' && (
+        <div className="max-w-[500px] overflow-hidden rounded-lg border border-border bg-card">
+          <PreviewImage aspectClassName="aspect-[1.91/1]" imageUrl={imageUrl} title={title} />
+          {/* Facebook's grey caption bar: domain in small caps above a bold headline. */}
+          <div className="space-y-0.5 bg-muted/60 px-3 py-2">
+            <p className="text-[11px] uppercase tracking-wide text-muted-foreground">{domain}</p>
+            <p className="text-sm font-semibold leading-snug text-foreground">{clampedTitle}</p>
+            {clampedDescription && (
+              <p className="text-xs leading-snug text-muted-foreground">{clampedDescription}</p>
+            )}
+          </div>
+          <div className="flex items-center gap-4 border-t border-border px-3 py-1.5 text-[11px] text-muted-foreground">
+            <span className="flex items-center gap-1">
+              <ThumbsUp aria-hidden="true" className="h-3 w-3" /> Like
+            </span>
+            <span className="flex items-center gap-1">
+              <MessageCircle aria-hidden="true" className="h-3 w-3" /> Comment
+            </span>
+            <span className="flex items-center gap-1">
+              <Share2 aria-hidden="true" className="h-3 w-3" /> Share
+            </span>
+          </div>
+        </div>
+      )}
+
+      {platform === 'x' && (
+        // X rounds the card hard, drops the caption bar, and puts the domain BELOW the
+        // text instead of above the headline.
+        <div className="max-w-[500px] overflow-hidden rounded-2xl border border-border bg-card">
+          <PreviewImage aspectClassName="aspect-[1.91/1]" imageUrl={imageUrl} title={title} />
+          <div className="space-y-0.5 px-3 py-2">
+            <p className="text-sm font-medium leading-snug text-foreground">{clampedTitle}</p>
+            {clampedDescription && (
+              <p className="text-xs leading-snug text-muted-foreground">{clampedDescription}</p>
+            )}
+            <p className="text-xs text-muted-foreground">{domain}</p>
+          </div>
+          <div className="flex items-center gap-5 border-t border-border px-3 py-1.5 text-[11px] text-muted-foreground">
+            <span className="flex items-center gap-1">
+              <MessageCircle aria-hidden="true" className="h-3 w-3" /> Reply
+            </span>
+            <span className="flex items-center gap-1">
+              <Repeat2 aria-hidden="true" className="h-3 w-3" /> Repost
+            </span>
+            <span className="flex items-center gap-1">
+              <Heart aria-hidden="true" className="h-3 w-3" /> Like
+            </span>
+          </div>
+        </div>
+      )}
+
+      {platform === 'linkedin' && (
+        // LinkedIn is the outlier worth showing: square-ish chrome, a roomier headline,
+        // and NO description at all — the meta description simply never appears here.
+        <div className="max-w-[520px] overflow-hidden rounded-sm border border-border bg-card">
+          <PreviewImage aspectClassName="aspect-[1.91/1]" imageUrl={imageUrl} title={title} />
+          <div className="space-y-1 bg-muted/40 px-3 py-2.5">
+            <p className="text-sm font-semibold leading-snug text-foreground">{clampedTitle}</p>
+            <p className="text-[11px] text-muted-foreground">
+              {publisher}
+              {publisher === domain ? '' : ` • ${domain}`}
+            </p>
+            <p className="text-[10px] italic text-muted-foreground/70">
+              LinkedIn does not display the meta description on link previews.
+            </p>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}