@simmalugnt-se/payload-content-health 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+export declare const CHECK_IDS: readonly ["media.alt-missing", "seo.title-missing", "seo.title-length", "seo.description-missing", "seo.description-length", "seo.image-missing", "content.h1-missing", "content.h1-multiple", "content.heading-skip", "content.thin"];
+export type CheckId = (typeof CHECK_IDS)[number];
+export type LengthRange = {
+    min: number;
+    max: number;
+};
+/** One problem in one field of one document, in one locale when the field is localized. */
+export type Finding = {
+    check: CheckId;
+    collection: string;
+    id: string | number;
+    /** The document's title (`useAsTitle`), falling back to the filename and then the id. */
+    title: string;
+    /** Dot path of the field in the document, e.g. `meta.description`. */
+    path: string;
+    /** Set when the field is localized. */
+    locale?: string;
+    /** For length checks: the current length and the range it falls outside. */
+    length?: LengthRange & {
+        actual: number;
+    };
+    /** For heading checks: the heading's level and, for a skip, the level before it. */
+    heading?: {
+        level: number;
+        previous?: number;
+        count?: number;
+    };
+    /** For thin content: words on the page and the minimum. */
+    words?: {
+        actual: number;
+        min: number;
+    };
+    /** Draft status of the checked version, for collections with drafts. */
+    status?: "draft" | "published";
+};
+export type SeoOptions = {
+    /** Field paths; `false` turns that field's checks off. Defaults follow `@payloadcms/plugin-seo`. */
+    title?: string | false;
+    description?: string | false;
+    image?: string | false;
+    /** Allowed length in characters; `false` turns the length check off. Default 50–60. */
+    titleLength?: LengthRange | false;
+    /** Default 100–150. */
+    descriptionLength?: LengthRange | false;
+};
+/**
+ * Heading levels per block, as the block components render them: block slug → field path in the
+ * block → level. Array fields fan out: `"items.title": 3` makes every item's title an H3.
+ */
+export type HeadingLevels = Record<string, Record<string, number>>;
+export type ContentOptions = {
+    /** The blocks or rich text field holding the page body, e.g. `layout`. */
+    field: string;
+    /**
+     * Heading levels of block fields. Headings inside rich text count by their own tag. Without this
+     * option the heading checks are off, since only the frontend knows what it renders as an H1.
+     */
+    headings?: HeadingLevels;
+    /** Fewer words than this is thin content; `false` turns the check off. Default 300. */
+    minWords?: number | false;
+};
+export type AltTextOptions = {
+    /** Field holding the alt text. Default `alt`. */
+    field?: string;
+};
+export type CollectionHealthOptions = {
+    /** SEO checks on the fields `@payloadcms/plugin-seo` adds, or the paths given here. */
+    seo?: boolean | SeoOptions;
+    /** Alt text on images in an upload collection. Files that are not images are skipped. */
+    altText?: boolean | AltTextOptions;
+    /** Heading structure and thin content, read from the page body. */
+    content?: ContentOptions;
+};
+export type ContentHealthPluginOptions = {
+    /** Collection slugs and the checks to run on each. */
+    collections: Record<string, CollectionHealthOptions>;
+    disabled?: boolean;
+    /**
+     * Put the widget on the default dashboard, below the collection cards, when the project sets no
+     * `admin.dashboard.defaultLayout` of its own. Editors who already saved a layout add it themselves.
+     * Default `true`.
+     */
+    addToDefaultLayout?: boolean;
+};

package/dist/types.js

@@ -0,0 +1,12 @@
+export const CHECK_IDS = [
+    "media.alt-missing",
+    "seo.title-missing",
+    "seo.title-length",
+    "seo.description-missing",
+    "seo.description-length",
+    "seo.image-missing",
+    "content.h1-missing",
+    "content.h1-multiple",
+    "content.heading-skip",
+    "content.thin",
+];

package/dist/widget/ContentHealthWidget.d.ts

@@ -0,0 +1,7 @@
+import type { WidgetServerProps } from "payload";
+import "../styles/widget.css";
+/**
+ * Dashboard widget: the share of checked fields in order, overall and per check, and the documents
+ * that need work, each linking to the document in the right locale.
+ */
+export declare function ContentHealthWidget({ req, widgetData }: WidgetServerProps): Promise<import("react").JSX.Element>;

package/dist/widget/ContentHealthWidget.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { formatAdminURL } from "payload/shared";
+import { COPY, STATUS, TILE_LABELS, uiLanguage } from "../copy.js";
+import { checkStats, countDocuments } from "../group.js";
+import { scanContentHealth } from "../scan.js";
+import { CHECK_IDS } from "../types.js";
+import { Ring } from "./Ring.js";
+import "../styles/widget.css";
+const ROWS_PER_CHECK = 4;
+/**
+ * Dashboard widget: the share of checked fields in order, overall and per check, and the documents
+ * that need work, each linking to the document in the right locale.
+ */
+export async function ContentHealthWidget({ req, widgetData }) {
+    const language = uiLanguage(req.i18n?.language);
+    const copy = COPY[language];
+    const selected = Array.isArray(widgetData?.checks)
+        ? widgetData.checks.filter((id) => CHECK_IDS.includes(id))
+        : [];
+    const result = await scanContentHealth({
+        payload: req.payload,
+        user: req.user,
+        checks: selected,
+    });
+    const stats = checkStats(result.checks, result.checked, result.findings);
+    const total = stats.reduce((sum, stat) => sum + stat.checked, 0);
+    const failing = stats.reduce((sum, stat) => sum + stat.failing, 0);
+    const passing = stats.filter((stat) => stat.checked > 0 && stat.failing === 0).length;
+    const documents = Object.values(result.documents).reduce((sum, count) => sum + count, 0);
+    const adminRoute = req.payload.config.routes.admin;
+    return (_jsxs("section", { className: "content-health", children: [_jsx("h2", { className: "content-health__heading", children: copy.title }), _jsxs("div", { className: "content-health__panel", children: [_jsxs("div", { className: "content-health__overview", children: [_jsx(Ring, { className: "content-health__ring content-health__ring--large", failing: failing, label: copy.ok(total - failing, total), total: total }), _jsxs("div", { children: [_jsx("p", { className: "content-health__overall", children: copy.overall }), _jsxs("p", { className: "content-health__summary", children: [result.findings.length
+                                                ? copy.summary(countDocuments(result.findings), documents)
+                                                : copy.allGood, passing > 0 && result.findings.length > 0 ? ` · ${copy.passing(passing)}` : null] })] })] }), _jsx("ul", { className: "content-health__tiles", children: stats.map((stat) => (_jsx(CheckTile, { adminRoute: adminRoute, language: language, stat: stat }, stat.check))) }), result.problems.length ? (_jsxs("div", { className: "content-health__problems", children: [_jsx("p", { children: copy.problems }), _jsx("ul", { children: result.problems.map((problem) => (_jsx("li", { children: problem }, problem))) })] })) : null] })] }));
+}
+function CheckTile({ adminRoute, language, stat, }) {
+    const copy = COPY[language];
+    const status = !stat.checked
+        ? copy.nothingYet
+        : stat.failing
+            ? STATUS[language][stat.check](stat.checked - stat.failing, stat.checked)
+            : copy.checkPasses;
+    return (_jsxs("li", { className: "content-health__tile", children: [_jsxs("div", { className: "content-health__tile-head", children: [_jsx(Ring, { className: "content-health__ring", failing: stat.failing, label: status, total: stat.checked }), _jsxs("div", { children: [_jsx("h3", { className: "content-health__tile-title", children: TILE_LABELS[language][stat.check] }), _jsx("p", { className: "content-health__tile-status", children: status })] })] }), stat.documents.length ? (_jsxs("ul", { className: "content-health__rows", children: [stat.documents.slice(0, ROWS_PER_CHECK).map((row) => (_jsxs("li", { className: "content-health__row", children: [_jsx("a", { href: editURL(adminRoute, row.findings[0]), children: row.title }), row.findings.map((finding) => (_jsxs("span", { className: "content-health__locale", children: [finding.locale ? (_jsx("a", { className: "content-health__pill", href: editURL(adminRoute, finding), children: finding.locale })) : null, _jsx(Detail, { copy: copy, finding: finding })] }, finding.locale ?? "")))] }, `${row.collection}:${row.id}`))), stat.documents.length > ROWS_PER_CHECK ? (_jsx("li", { className: "content-health__more", children: copy.more(stat.documents.length - ROWS_PER_CHECK) })) : null] })) : null] }));
+}
+function Detail({ copy, finding }) {
+    const { heading, length, words } = finding;
+    const text = length
+        ? copy.length(length.actual, length.min, length.max)
+        : words
+            ? copy.words(words.actual, words.min)
+            : heading?.previous !== undefined
+                ? copy.headingSkip(heading.previous, heading.level)
+                : heading?.count
+                    ? copy.h1Count(heading.count)
+                    : undefined;
+    return text ? _jsx("span", { className: "content-health__detail", children: text }) : null;
+}
+function editURL(adminRoute, finding) {
+    const path = `/collections/${finding.collection}/${encodeURIComponent(String(finding.id))}`;
+    const url = formatAdminURL({ adminRoute, path });
+    return finding.locale ? `${url}?locale=${encodeURIComponent(finding.locale)}` : url;
+}

package/dist/widget/Ring.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A progress ring: the share of values in order as an arc on a neutral track, with the percentage in
+ * the middle. What is missing stays track-colored; the text beside the ring says how much. Sized by
+ * CSS; drawn in a 100×100 box.
+ */
+export declare function Ring({ className, failing, label, total, }: {
+    className: string;
+    failing: number;
+    /** Accessible text, e.g. "4 of 6 OK". */
+    label: string;
+    total: number;
+}): import("react").JSX.Element;

package/dist/widget/Ring.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A progress ring: the share of values in order as an arc on a neutral track, with the percentage in
+ * the middle. What is missing stays track-colored; the text beside the ring says how much. Sized by
+ * CSS; drawn in a 100×100 box.
+ */
+const SIZE = 100;
+const STROKE = 12;
+const RADIUS = (SIZE - STROKE) / 2;
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+export function Ring({ className, failing, label, total, }) {
+    const ok = total - failing;
+    const okLength = total ? (CIRCUMFERENCE * ok) / total : 0;
+    const percent = total ? Math.round((ok / total) * 100) : undefined;
+    return (_jsxs("svg", { "aria-label": label, className: className, role: "img", viewBox: `0 0 ${SIZE} ${SIZE}`, children: [_jsx("title", { children: label }), _jsxs("g", { transform: `rotate(-90 ${SIZE / 2} ${SIZE / 2})`, children: [_jsx("circle", { className: "content-health__ring-track", ...circle }), okLength > 0 ? (_jsx("circle", { className: "content-health__ring-ok", ...circle, strokeDasharray: `${okLength} ${CIRCUMFERENCE}`, strokeLinecap: ok < total ? "round" : "butt" })) : null] }), _jsx("text", { className: "content-health__ring-value", dominantBaseline: "central", textAnchor: "middle", x: SIZE / 2, y: SIZE / 2, children: percent === undefined ? "–" : `${percent}%` })] }));
+}
+const circle = {
+    cx: SIZE / 2,
+    cy: SIZE / 2,
+    fill: "none",
+    r: RADIUS,
+    strokeWidth: STROKE,
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@simmalugnt-se/payload-content-health",
+  "version": "0.1.0",
+  "description": "Content health checks and dashboard widgets for Payload Admin: alt texts, SEO fields and more",
+  "keywords": [
+    "payload",
+    "payload-plugin"
+  ],
+  "license": "MIT",
+  "author": "Simmalugnt AB",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simmalugnt-se/payload-plugins.git",
+    "directory": "packages/payload-content-health"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./rsc": {
+      "import": "./dist/exports/rsc.js",
+      "types": "./dist/exports/rsc.d.ts",
+      "default": "./dist/exports/rsc.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "payload": ">=3.90.2 <4",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/react": "^19.2.18",
+    "payload": "3.90.2",
+    "react": "19.2.8",
+    "tsx": "^4.21.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -R src/styles dist/styles",
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}