@simmalugnt-se/payload-content-health 0.1.0

package/dist/exports/rsc.js

@@ -0,0 +1 @@
+export { ContentHealthWidget } from "../widget/ContentHealthWidget.js";

package/dist/fields.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Looks up a dot path in a collection's field config, so a rule knows whether its field exists and
+ * whether it is localized. Rows, collapsibles and unnamed tabs add no path segment; groups and named
+ * tabs do.
+ */
+export type FieldLike = {
+    /** Unset on the entries of a tabs field. */
+    type?: string;
+    name?: string;
+    localized?: boolean;
+    fields?: FieldLike[];
+    tabs?: FieldLike[];
+    blocks?: BlockLike[];
+    blockReferences?: (BlockLike | string)[];
+};
+export type BlockLike = {
+    slug: string;
+    fields: FieldLike[];
+};
+export type PathInfo = {
+    field: FieldLike;
+    localized: boolean;
+    select: Record<string, unknown>;
+};
+/** Undefined when no field sits at the path. */
+export declare function lookupPath(fields: FieldLike[], path: string): PathInfo | undefined;
+/** Deep-merges Local API `select` objects. */
+export declare function mergeSelect(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/** A text-bearing field in a block, by its path in the block; arrays and groups add segments. */
+export type TextField = {
+    path: string;
+    kind: "text" | "richText";
+};
+/** Where a page body keeps its text: one rich text field, or text fields per block. */
+export type ContentSchema = {
+    kind: "richText";
+} | {
+    kind: "blocks";
+    blocks: Record<string, TextField[]>;
+};
+/**
+ * The text fields of a page body field. `localized` is set when any of them is localized, so the
+ * body is read once per locale. Undefined for fields that are neither blocks nor rich text.
+ */
+export declare function contentSchema(field: FieldLike, resolveBlock: (slug: string) => BlockLike | undefined): {
+    schema: ContentSchema;
+    localized: boolean;
+} | undefined;

package/dist/fields.js

@@ -0,0 +1,114 @@
+/**
+ * Looks up a dot path in a collection's field config, so a rule knows whether its field exists and
+ * whether it is localized. Rows, collapsibles and unnamed tabs add no path segment; groups and named
+ * tabs do.
+ */
+/** Undefined when no field sits at the path. */
+export function lookupPath(fields, path) {
+    const segments = path.split(".");
+    let current = fields;
+    let localized = false;
+    for (const [index, segment] of segments.entries()) {
+        const field = findNamed(current, segment);
+        if (!field) {
+            return undefined;
+        }
+        localized ||= Boolean(field.localized);
+        const last = index === segments.length - 1;
+        if (last) {
+            return { field, localized, select: selectFor(segments) };
+        }
+        if (!field.fields) {
+            return undefined;
+        }
+        current = field.fields;
+    }
+    return undefined;
+}
+function findNamed(fields, name) {
+    for (const field of fields) {
+        if (field.name === name) {
+            return field;
+        }
+        if (field.name) {
+            continue;
+        }
+        // Unnamed containers: row, collapsible, unnamed tab, and the tabs field itself.
+        const nested = field.type === "tabs" ? field.tabs : field.fields;
+        const found = nested && findNamed(nested, name);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+function selectFor(segments) {
+    const [head, ...rest] = segments;
+    return { [head]: rest.length ? selectFor(rest) : true };
+}
+/** Deep-merges Local API `select` objects. */
+export function mergeSelect(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        const existing = target[key];
+        if (existing === true || value === true) {
+            target[key] = true;
+        }
+        else if (existing && typeof existing === "object") {
+            mergeSelect(existing, value);
+        }
+        else {
+            target[key] = value;
+        }
+    }
+    return target;
+}
+/**
+ * The text fields of a page body field. `localized` is set when any of them is localized, so the
+ * body is read once per locale. Undefined for fields that are neither blocks nor rich text.
+ */
+export function contentSchema(field, resolveBlock) {
+    if (field.type === "richText") {
+        return { schema: { kind: "richText" }, localized: Boolean(field.localized) };
+    }
+    if (field.type !== "blocks") {
+        return undefined;
+    }
+    const blocks = {};
+    let localized = Boolean(field.localized);
+    const references = (field.blockReferences ?? []).map((block) => typeof block === "string" ? resolveBlock(block) : block);
+    for (const block of [...(field.blocks ?? []), ...references]) {
+        if (!block) {
+            continue;
+        }
+        const found = [];
+        localized = collectTextFields(block.fields, "", found) || localized;
+        blocks[block.slug] = found;
+    }
+    return { schema: { kind: "blocks", blocks }, localized };
+}
+/** Collects text fields in config order; returns whether any of them is localized. */
+function collectTextFields(fields, prefix, out) {
+    let localized = false;
+    for (const field of fields) {
+        const path = field.name ? `${prefix}${field.name}` : undefined;
+        if (path && (field.type === "text" || field.type === "textarea")) {
+            out.push({ path, kind: "text" });
+            localized ||= Boolean(field.localized);
+        }
+        else if (path && field.type === "richText") {
+            out.push({ path, kind: "richText" });
+            localized ||= Boolean(field.localized);
+        }
+        else if (field.type === "tabs") {
+            localized = collectTextFields(field.tabs ?? [], prefix, out) || localized;
+        }
+        else if (field.fields && field.type !== "blocks") {
+            // Groups, arrays and named tabs add a segment; rows, collapsibles and unnamed tabs do not.
+            // A localized group or array localizes the text fields inside it.
+            const before = out.length;
+            const nested = collectTextFields(field.fields, path ? `${path}.` : prefix, out);
+            localized ||= nested || (Boolean(field.localized) && out.length > before);
+        }
+    }
+    return localized;
+}

package/dist/group.d.ts

@@ -0,0 +1,27 @@
+import { type CheckId, type Finding } from "./types.ts";
+export type DocumentFindings = {
+    collection: string;
+    id: string | number;
+    title: string;
+    /** One per locale for localized fields, otherwise one. */
+    findings: Finding[];
+};
+export type CheckGroup = {
+    check: CheckId;
+    documents: DocumentFindings[];
+};
+/** Findings per check, in `CHECK_IDS` order, with a document's locales collected on one row. */
+export declare function groupFindings(findings: Finding[]): CheckGroup[];
+/** Distinct documents with at least one finding. */
+export declare function countDocuments(findings: Finding[]): number;
+export type CheckStats = {
+    check: CheckId;
+    /** Field values the check applied to. */
+    checked: number;
+    /** Values with a finding. */
+    failing: number;
+    /** Documents with a finding, locales collected on one row. */
+    documents: DocumentFindings[];
+};
+/** Per check that ran: how many values it looked at and which ones need work. */
+export declare function checkStats(checks: CheckId[], checked: Partial<Record<CheckId, number>>, findings: Finding[]): CheckStats[];

package/dist/group.js

@@ -0,0 +1,38 @@
+import { CHECK_IDS } from "./types.js";
+/** Findings per check, in `CHECK_IDS` order, with a document's locales collected on one row. */
+export function groupFindings(findings) {
+    const groups = new Map();
+    for (const finding of findings) {
+        let documents = groups.get(finding.check);
+        if (!documents) {
+            documents = new Map();
+            groups.set(finding.check, documents);
+        }
+        const key = `${finding.collection}:${finding.id}`;
+        const existing = documents.get(key);
+        if (existing) {
+            existing.findings.push(finding);
+        }
+        else {
+            const { collection, id, title } = finding;
+            documents.set(key, { collection, id, title, findings: [finding] });
+        }
+    }
+    return CHECK_IDS.flatMap((check) => {
+        const documents = groups.get(check);
+        return documents ? [{ check, documents: [...documents.values()] }] : [];
+    });
+}
+/** Distinct documents with at least one finding. */
+export function countDocuments(findings) {
+    return new Set(findings.map((finding) => `${finding.collection}:${finding.id}`)).size;
+}
+/** Per check that ran: how many values it looked at and which ones need work. */
+export function checkStats(checks, checked, findings) {
+    const groups = new Map(groupFindings(findings).map((group) => [group.check, group.documents]));
+    return checks.map((check) => {
+        const documents = groups.get(check) ?? [];
+        const failing = documents.reduce((sum, row) => sum + row.findings.length, 0);
+        return { check, checked: checked[check] ?? 0, failing, documents };
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { DocumentInput, DocumentResult, FieldRule, ResolvedRule } from "./checks.ts";
+export { checkDocument, DEFAULT_MIN_WORDS, rulesFor, SEO_DEFAULTS } from "./checks.ts";
+export type { Heading, PageContent } from "./content.ts";
+export { countWords, readContent } from "./content.ts";
+export type { CheckGroup, CheckStats, DocumentFindings } from "./group.ts";
+export { checkStats, countDocuments, groupFindings } from "./group.ts";
+export { contentHealthPlugin, WIDGET_SLUG } from "./plugin.ts";
+export type { ScanArgs, ScanResult } from "./scan.ts";
+export { scanContentHealth } from "./scan.ts";
+export type { AltTextOptions, CheckId, CollectionHealthOptions, ContentHealthPluginOptions, ContentOptions, Finding, HeadingLevels, LengthRange, SeoOptions, } from "./types.ts";
+export { CHECK_IDS } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { checkDocument, DEFAULT_MIN_WORDS, rulesFor, SEO_DEFAULTS } from "./checks.js";
+export { countWords, readContent } from "./content.js";
+export { checkStats, countDocuments, groupFindings } from "./group.js";
+export { contentHealthPlugin, WIDGET_SLUG } from "./plugin.js";
+export { scanContentHealth } from "./scan.js";
+export { CHECK_IDS } from "./types.js";

package/dist/package-name.d.ts

@@ -0,0 +1,2 @@
+export declare const PACKAGE_NAME = "@simmalugnt-se/payload-content-health";
+export declare const RSC_ENTRY = "@simmalugnt-se/payload-content-health/rsc";

package/dist/package-name.js

@@ -0,0 +1,2 @@
+export const PACKAGE_NAME = "@simmalugnt-se/payload-content-health";
+export const RSC_ENTRY = `${PACKAGE_NAME}/rsc`;

package/dist/plugin.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "payload";
+import { type ContentHealthPluginOptions } from "./types.ts";
+export declare const WIDGET_SLUG = "content-health";
+export declare function contentHealthPlugin(options: ContentHealthPluginOptions): Plugin;

package/dist/plugin.js

@@ -0,0 +1,51 @@
+import { CHECK_LABELS } from "./copy.js";
+import { RSC_ENTRY } from "./package-name.js";
+import { CUSTOM_KEY } from "./scan.js";
+import { CHECK_IDS } from "./types.js";
+export const WIDGET_SLUG = "content-health";
+const widget = {
+    slug: WIDGET_SLUG,
+    Component: `${RSC_ENTRY}#ContentHealthWidget`,
+    label: { en: "Content health", sv: "Innehållshälsa" },
+    minWidth: "medium",
+    fields: [
+        {
+            name: "checks",
+            type: "select",
+            hasMany: true,
+            label: { en: "Checks (all when empty)", sv: "Kontroller (alla om tomt)" },
+            options: CHECK_IDS.map((id) => ({
+                value: id,
+                label: { en: CHECK_LABELS.en[id], sv: CHECK_LABELS.sv[id] },
+            })),
+        },
+    ],
+};
+export function contentHealthPlugin(options) {
+    return (config) => {
+        if (options.disabled) {
+            return config;
+        }
+        const dashboard = config.admin?.dashboard;
+        // Payload only adds its collection cards to the default layout when none is set, so keep them.
+        const defaultLayout = dashboard?.defaultLayout ??
+            (options.addToDefaultLayout === false
+                ? undefined
+                : [
+                    { widgetSlug: "collections", width: "full" },
+                    { widgetSlug: WIDGET_SLUG, width: "full" },
+                ]);
+        return {
+            ...config,
+            admin: {
+                ...config.admin,
+                dashboard: {
+                    ...dashboard,
+                    widgets: [...(dashboard?.widgets ?? []), widget],
+                    ...(defaultLayout ? { defaultLayout } : {}),
+                },
+            },
+            custom: { ...config.custom, [CUSTOM_KEY]: options },
+        };
+    };
+}

package/dist/scan.d.ts

@@ -0,0 +1,28 @@
+import type { Payload, SanitizedConfig, TypedUser } from "payload";
+import { type CheckId, type ContentHealthPluginOptions, type Finding } from "./types.ts";
+/** Where the plugin keeps its options in the (server-only) `config.custom`. */
+export declare const CUSTOM_KEY = "contentHealth";
+export declare function contentHealthOptions(config: SanitizedConfig): ContentHealthPluginOptions | undefined;
+export type ScanResult = {
+    findings: Finding[];
+    /** The checks that ran, in `CHECK_IDS` order. */
+    checks: CheckId[];
+    /** Field values each check applied to; `checked - findings` of a check are in order. */
+    checked: Partial<Record<CheckId, number>>;
+    /** Documents read per collection. */
+    documents: Record<string, number>;
+    /** Configured checks that could not run, e.g. a field path that does not exist. */
+    problems: string[];
+};
+export type ScanArgs = {
+    payload: Payload;
+    /** Documents are read with this user's access. */
+    user: TypedUser | null;
+    /** Only these checks; all configured ones when unset or empty. */
+    checks?: CheckId[];
+};
+/**
+ * Runs the configured checks on the latest version (draft included) of every document the user can
+ * read, once per locale for localized fields.
+ */
+export declare function scanContentHealth({ payload, user, checks }: ScanArgs): Promise<ScanResult>;

package/dist/scan.js

@@ -0,0 +1,124 @@
+import { checkDocument, documentTitle, rulesFor } from "./checks.js";
+import { contentSchema, lookupPath, mergeSelect, } from "./fields.js";
+import { CHECK_IDS } from "./types.js";
+/** Where the plugin keeps its options in the (server-only) `config.custom`. */
+export const CUSTOM_KEY = "contentHealth";
+export function contentHealthOptions(config) {
+    return config.custom?.[CUSTOM_KEY];
+}
+/**
+ * Runs the configured checks on the latest version (draft included) of every document the user can
+ * read, once per locale for localized fields.
+ */
+export async function scanContentHealth({ payload, user, checks }) {
+    const result = {
+        findings: [],
+        checks: [],
+        checked: {},
+        documents: {},
+        problems: [],
+    };
+    const ran = new Set();
+    const options = contentHealthOptions(payload.config);
+    if (!options) {
+        result.problems.push("contentHealthPlugin is not installed.");
+        return result;
+    }
+    const blocks = (payload.config.blocks ?? []);
+    const resolveBlock = (slug) => blocks.find((block) => block.slug === slug);
+    const locales = payload.config.localization
+        ? payload.config.localization.localeCodes
+        : [undefined];
+    for (const [slug, collectionOptions] of Object.entries(options.collections)) {
+        const collection = payload.collections[slug]?.config;
+        if (!collection) {
+            result.problems.push(`Collection "${slug}" does not exist.`);
+            continue;
+        }
+        const fields = collection.fields;
+        const select = {};
+        const rules = [];
+        for (const rule of rulesFor(collectionOptions)) {
+            if (checks?.length && !checks.includes(rule.check)) {
+                continue;
+            }
+            const info = lookupPath(fields, rule.path);
+            if (!info) {
+                result.problems.push(`${slug}: no field at "${rule.path}" for ${rule.check}.`);
+                continue;
+            }
+            let localized = info.localized;
+            let content;
+            if (rule.kind === "outline" || rule.kind === "words") {
+                const body = contentSchema(info.field, resolveBlock);
+                if (!body) {
+                    result.problems.push(`${slug}: "${rule.path}" is not a blocks or rich text field.`);
+                    continue;
+                }
+                content = body.schema;
+                localized ||= body.localized;
+            }
+            ran.add(rule.check);
+            rules.push({
+                ...rule,
+                localized: Boolean(payload.config.localization) && localized,
+                ...(content ? { content } : {}),
+            });
+            mergeSelect(select, info.select);
+        }
+        if (!rules.length) {
+            continue;
+        }
+        const useAsTitle = collection.admin?.useAsTitle;
+        if (useAsTitle && useAsTitle !== "id") {
+            mergeSelect(select, { [useAsTitle]: true });
+        }
+        if (collection.upload) {
+            mergeSelect(select, { filename: true, mimeType: true });
+        }
+        const drafts = Boolean(collection.versions && collection.versions.drafts);
+        if (drafts) {
+            mergeSelect(select, { _status: true });
+        }
+        const anyLocalized = rules.some((rule) => rule.localized);
+        for (const [index, locale] of locales.entries()) {
+            if (index > 0 && !anyLocalized) {
+                break;
+            }
+            try {
+                const { docs } = await payload.find({
+                    collection: slug,
+                    depth: 0,
+                    draft: drafts,
+                    fallbackLocale: false,
+                    ...(locale ? { locale } : {}),
+                    overrideAccess: false,
+                    pagination: false,
+                    select: select,
+                    user,
+                });
+                result.documents[slug] = docs.length;
+                for (const doc of docs) {
+                    const { findings, checked } = checkDocument({
+                        collection: slug,
+                        doc,
+                        rules,
+                        title: documentTitle(doc, useAsTitle),
+                        ...(locale ? { locale } : {}),
+                        includeUnlocalized: index === 0,
+                    });
+                    result.findings.push(...findings);
+                    for (const check of checked) {
+                        result.checked[check] = (result.checked[check] ?? 0) + 1;
+                    }
+                }
+            }
+            catch (error) {
+                result.problems.push(`${slug}: ${error instanceof Error ? error.message : String(error)}`);
+                break;
+            }
+        }
+    }
+    result.checks = CHECK_IDS.filter((check) => ran.has(check));
+    return result;
+}

package/dist/styles/widget.css

@@ -0,0 +1,173 @@
+/* Laid out like Payload's collection cards: a section heading, then the content. */
+/* The accent is the blue the editor assistant and visual editing use. */
+.content-health {
+  --content-health-accent: #2563eb;
+  display: flex;
+  flex-direction: column;
+  gap: var(--base);
+  width: 100%;
+  /* Payload spaces widgets 12px apart; its collection groups sit one --base apart. */
+  padding-top: calc(var(--base) - 12px);
+}
+
+.content-health__heading {
+  margin: 0;
+}
+
+.content-health__panel {
+  display: flex;
+  flex-direction: column;
+  gap: calc(var(--base) * 1.25);
+  padding: calc(var(--base) * 1.25);
+  border: 1px solid var(--theme-elevation-150);
+  border-radius: var(--style-radius-m);
+  background: var(--theme-elevation-0);
+}
+
+.content-health__overview {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--base) * 1.25);
+}
+
+.content-health__overall {
+  margin: 0;
+  font-size: 1.15rem;
+  font-weight: 500;
+}
+
+.content-health__summary {
+  margin: calc(var(--base) * 0.25) 0 0;
+  color: var(--theme-elevation-600);
+}
+
+/* Rings */
+.content-health__ring {
+  flex: none;
+  width: 3.75rem;
+  height: 3.75rem;
+}
+
+.content-health__ring--large {
+  width: 7.5rem;
+  height: 7.5rem;
+}
+
+.content-health__ring-track {
+  stroke: var(--theme-elevation-150);
+}
+
+.content-health__ring-ok {
+  stroke: var(--content-health-accent);
+}
+
+html[data-theme="dark"] .content-health {
+  --content-health-accent: #60a5fa;
+}
+
+.content-health__ring-value {
+  fill: var(--theme-text);
+  /* viewBox units: scales with the ring. */
+  font-size: 24px;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+}
+
+/* One tile per check, as many columns as fit. */
+.content-health__tiles {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr));
+  gap: 12px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.content-health__tile {
+  display: flex;
+  flex-direction: column;
+  gap: calc(var(--base) * 0.75);
+  padding: var(--base);
+  /* Same as Payload's collection cards. */
+  border: 1px solid var(--theme-elevation-150);
+  border-radius: var(--style-radius-m);
+  background: var(--theme-elevation-50);
+}
+
+.content-health__tile-head {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--base) * 0.75);
+}
+
+.content-health__tile-title {
+  margin: 0;
+  font-size: 1rem;
+  line-height: 1.3;
+}
+
+.content-health__tile-status {
+  margin: calc(var(--base) * 0.15) 0 0;
+  color: var(--theme-elevation-600);
+  font-variant-numeric: tabular-nums;
+}
+
+.content-health__rows {
+  display: flex;
+  flex-direction: column;
+  gap: calc(var(--base) * 0.3);
+  margin: 0;
+  padding: calc(var(--base) * 0.6) 0 0;
+  border-top: 1px solid var(--theme-elevation-100);
+  list-style: none;
+}
+
+.content-health__row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: calc(var(--base) * 0.3);
+}
+
+.content-health__locale {
+  display: inline-flex;
+  align-items: baseline;
+  gap: calc(var(--base) * 0.2);
+}
+
+.content-health__pill {
+  padding: 0 calc(var(--base) * 0.3);
+  border-radius: var(--style-radius-s);
+  background: var(--theme-elevation-150);
+  color: var(--theme-elevation-800);
+  font-size: 0.75em;
+  text-decoration: none;
+  text-transform: uppercase;
+}
+
+.content-health__pill:hover {
+  background: var(--theme-elevation-250);
+}
+
+.content-health__detail,
+.content-health__more {
+  color: var(--theme-elevation-500);
+  font-size: 0.9em;
+}
+
+.content-health__problems {
+  color: var(--theme-error-600);
+  font-size: 0.9em;
+}
+
+.content-health__problems p,
+.content-health__problems ul {
+  margin: 0;
+}
+
+@media (max-width: 768px) {
+  .content-health__ring--large {
+    width: 5.5rem;
+    height: 5.5rem;
+  }
+}