@simmalugnt-se/payload-content-health 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.2.1
+
+- The work list at `/admin/content-health` requires Admin access. Payload leaves custom Admin views
+  public, so a visitor who was not signed in saw the list, filled with what anonymous access could
+  read. Now they are sent to the login and back, and a signed-in user without Admin access to
+  Payload's unauthorized page.
+
+## 0.2.0
+
+- Work list at `/admin/content-health`, linked from the nav: every finding, filterable by check,
+  collection and locale, with the filters in the address. The widget's "N more" opens it filtered on
+  that check.
+- Links from the list and the widget open the document in the finding's locale with the field
+  brought into view: tabs and collapsed rows opened, the field scrolled to, focused and highlighted
+  (`?field=<path>`, read by a bridge in each checked collection's edit view).
+- "Fix with the assistant" on rows in collections `@simmalugnt-se/payload-editor-assistant` works
+  in: the same link with a ready prompt (`?ask=`), in Admin's language. The assistant takes the field
+  as its selection from a `content-health:select` event.
+- Widget rows put the document on its own line and each locale below it: one per line when it
+  carries a detail (length, word count, heading levels), otherwise side by side.
+- New peer dependencies: `@payloadcms/next`, `@payloadcms/ui`, `next` and `react-dom`.
+
 ## 0.1.0
 
 - First release: `contentHealthPlugin` with checks for missing alt text on images and for meta

package/README.md

@@ -1,10 +1,11 @@
 # @simmalugnt-se/payload-content-health
 
-Deterministic content checks for Payload, shown as a dashboard widget: images without alt text,
-missing or badly sized meta titles and descriptions, and pages without a share image. No AI; every
-finding points at one field of one document, in one locale when the field is localized.
+Deterministic content checks for Payload, shown as a dashboard widget and a work list: images
+without alt text, missing or badly sized meta titles and descriptions, pages without a share image,
+heading structure and thin content. No AI; every finding points at one field of one document, in one
+locale when the field is localized, and opens that field in Admin.
 
-Requires Payload `>=3.90.2 <4` and React 19. The widget uses Payload's modular dashboard
+Requires Payload `>=3.90.2 <4`, Next 16 and React 19. The widget uses Payload's modular dashboard
 (`admin.dashboard.widgets`), which Payload still marks as experimental.
 
 ## Setup
@@ -97,7 +98,36 @@ The plugin registers the widget `content-health`. When the project sets no
 widget. Payload keeps each editor's own layout as a preference once they edit the dashboard; they add
 the widget from the dashboard's edit mode, and can limit it to some checks in its settings.
 
-Pass `addToDefaultLayout: false` to only register the widget.
+Pass `addToDefaultLayout: false` to only register the widget. When a check has more documents than
+fit in its tile, "N more" opens the work list filtered on that check.
+
+## Work list
+
+`/admin/content-health` (linked at the top of the nav) lists every finding, filterable by check,
+collection and locale. The filters are kept in the address, e.g.
+`/admin/content-health?check=seo.title-missing&locale=sv`. The view scans once per visit.
+
+Each row opens the document in the finding's locale with the field brought into view: tabs and
+collapsed rows are opened, and the field is scrolled to, focused and highlighted. A finding in a row
+or block the unsaved form no longer has opens the nearest enclosing field instead.
+
+### With the editor assistant
+
+With `@simmalugnt-se/payload-editor-assistant` (0.5.0 or later), rows in the collections the
+assistant works in also get "Fix with the assistant": the same link with a ready prompt that the
+assistant puts in its message box. The editor sends it. To write a missing alt text, the assistant
+needs to see the image: allow `media.view` on the media collection (0.6.0 or later). The packages
+do not import each other; they share these names:
+
+| Name                                         | Direction               | Meaning                                  |
+| -------------------------------------------- | ----------------------- | ---------------------------------------- |
+| `?field=<path>`                              | link → this plugin      | Form path to bring into view             |
+| `?ask=<prompt>`                              | link → assistant        | Prompt to put in the message box         |
+| `content-health:select` (`detail: { path }`) | this plugin → assistant | The field brought into view is selected  |
+| `config.admin.custom.editorAssistant`        | assistant → this plugin | `{ collections }` the assistant works in |
+
+Both parameters are removed from the address once read. `editURL(adminRoute, finding, prompt?)` and
+`listURL(adminRoute, filters)` build these links.
 
 ## Running the checks yourself
 
@@ -107,5 +137,6 @@ import { scanContentHealth } from "@simmalugnt-se/payload-content-health";
 const { findings, problems } = await scanContentHealth({ payload, user: req.user });
 ```
 
-Each finding is `{ check, collection, id, title, path, locale?, length?, status? }`. `problems`
+Each finding is `{ check, collection, id, title, path, locale?, length?, heading?, words?, status? }`,
+where `path` is the form path with row indexes (`layout.1.items.0.title`). `problems`
 lists configured checks that could not run, such as a field path that does not exist.

package/dist/admin/ContentHealthFieldBridge.d.ts

@@ -0,0 +1,8 @@
+import "../styles/admin.css";
+/**
+ * Mounted in the edit view of each checked collection. When the address carries `?field=<path>`
+ * (a link from the work list or the widget), it opens the tabs and rows around that field, scrolls
+ * to it, focuses and highlights it, then announces it with `content-health:select` so the editor
+ * assistant takes it as the selection. The parameter is removed from the address once read.
+ */
+export declare function ContentHealthFieldBridge(): import("react").JSX.Element;

package/dist/admin/ContentHealthFieldBridge.js

@@ -0,0 +1,291 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useConfig, useDocumentForm, useDocumentInfo } from "@payloadcms/ui";
+import { useEffect, useRef } from "react";
+import "../styles/admin.css";
+import { FIELD_PARAM, SELECT_EVENT } from "../links.js";
+import { planReveal } from "./reveal-plan.js";
+import { revealTarget } from "./target.js";
+/*
+ * The DOM steps below follow VisualEditingAdminBridge in @simmalugnt-se/payload-visual-editing,
+ * which reveals fields clicked in the preview; keep fixes in step with it.
+ */
+const HIGHLIGHT_CLASS = "content-health-highlight";
+const HIGHLIGHT_MS = 1600;
+/** Tabs and rows render within a few frames. */
+const WAIT_MS = 1000;
+/** Rich text editors are lazy loaded and can take noticeably longer to mount. */
+const FIELD_WAIT_MS = 4000;
+/** Frames an element must keep its position before the layout counts as settled. */
+const STABLE_FRAMES = 3;
+/** Roughly how long a smooth scroll takes. */
+const SCROLL_MS = 600;
+/**
+ * Mounted in the edit view of each checked collection. When the address carries `?field=<path>`
+ * (a link from the work list or the widget), it opens the tabs and rows around that field, scrolls
+ * to it, focuses and highlights it, then announces it with `content-health:select` so the editor
+ * assistant takes it as the selection. The parameter is removed from the address once read.
+ */
+export function ContentHealthFieldBridge() {
+    const form = useDocumentForm();
+    const { config, getEntityConfig } = useConfig();
+    const { collectionSlug } = useDocumentInfo();
+    const anchorRef = useRef(null);
+    const latest = useRef({ form, config, getEntityConfig, collectionSlug });
+    // Kept across effect re-runs: the parameter is gone from the address after the first read.
+    const requested = useRef(undefined);
+    useEffect(() => {
+        latest.current = { form, config, getEntityConfig, collectionSlug };
+    });
+    useEffect(() => {
+        if (requested.current === undefined) {
+            requested.current = takeFieldParam();
+        }
+        const path = requested.current;
+        if (!path) {
+            return;
+        }
+        let cancelled = false;
+        const current = () => !cancelled;
+        void (async () => {
+            const { form, config, getEntityConfig, collectionSlug } = latest.current;
+            const fields = form.getFields();
+            const rootFields = collectionSlug
+                ? (getEntityConfig({ collectionSlug })?.fields ??
+                    [])
+                : [];
+            const lookup = {
+                blockTypeAt: (rowPath) => rowAt(fields, rowPath)?.blockType,
+                blocksBySlug: config.blocksMap,
+            };
+            const target = revealTarget(path, (candidate) => planReveal(rootFields, candidate, lookup));
+            if (!target) {
+                return;
+            }
+            expandRows(target.steps, fields, form.dispatchFields);
+            const scope = await openSteps(target.steps, formRoot(anchorRef.current), current);
+            if (!scope || !current()) {
+                return;
+            }
+            const element = await waitForRendered(() => findTarget(target.path), scope, FIELD_WAIT_MS);
+            if (!element || !current()) {
+                return;
+            }
+            await reveal(element, current);
+            if (current()) {
+                requested.current = null;
+                window.dispatchEvent(new CustomEvent(SELECT_EVENT, { detail: { path: target.path } }));
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    return _jsx("span", { hidden: true, ref: anchorRef });
+}
+/** Reads `?field=` and removes it, so a reload or a save does not jump back to the field. */
+function takeFieldParam() {
+    const url = new URL(window.location.href);
+    const path = url.searchParams.get(FIELD_PARAM);
+    if (path === null) {
+        return null;
+    }
+    url.searchParams.delete(FIELD_PARAM);
+    window.history.replaceState(window.history.state, "", url);
+    return path || null;
+}
+function expandRows(steps, fields, dispatchFields) {
+    for (const step of steps) {
+        if (step.kind !== "row") {
+            continue;
+        }
+        const rows = fields[step.parentPath]?.rows;
+        if (!rows?.[step.index]?.collapsed) {
+            continue;
+        }
+        dispatchFields({
+            type: "SET_ROW_COLLAPSED",
+            path: step.parentPath,
+            updatedRows: rows.map((row, index) => index === step.index ? { ...row, collapsed: false } : row),
+        });
+    }
+}
+function rowAt(fields, rowPath) {
+    const cut = rowPath.lastIndexOf(".");
+    return fields[rowPath.slice(0, cut)]?.rows?.[Number(rowPath.slice(cut + 1))];
+}
+/** The edit form this bridge belongs to, not one in a document drawer. */
+function formRoot(anchor) {
+    const view = anchor?.closest(".collection-edit");
+    return view?.querySelector(".collection-edit__form") ?? document;
+}
+/**
+ * Open the rows and tabs the plan needs, one level at a time, waiting for each to render.
+ * Returns the innermost scope (row or tab content), where the target renders.
+ */
+async function openSteps(steps, root, current) {
+    let scope = root;
+    for (const step of steps) {
+        if (!current()) {
+            return null;
+        }
+        if (step.kind === "row") {
+            const row = await waitForRendered(() => document.getElementById(rowDomId(step)), scope);
+            if (!row) {
+                return null;
+            }
+            scope = row;
+            continue;
+        }
+        const tabsScope = scope;
+        const tabs = await waitForRendered(() => tabsFieldsIn(tabsScope)[step.ordinal] ?? null, tabsScope);
+        const button = tabs?.querySelectorAll(":scope > .tabs-field__tabs-wrap > .tabs-field__tabs > .tabs-field__tab-button")[step.index];
+        if (!tabs || !button) {
+            return null;
+        }
+        // Click even the active tab: Payload restores the editor's last tab from preferences once they
+        // load, unless a tab was clicked first. Links open on page load, when that restore is pending.
+        button.click();
+        const content = await waitFor(() => button.classList.contains("tabs-field__tab-button--active")
+            ? tabs.querySelector(":scope > .tabs-field__content-wrap")
+            : null);
+        if (!content) {
+            return null;
+        }
+        scope = content;
+    }
+    return scope;
+}
+/**
+ * Payload renders a group of fields only once it is within 1000px of the viewport
+ * (`RenderIfInViewport`); until then the group is an empty div. So when the next level is not in
+ * the DOM yet, bring the enclosing scope into view to make Payload render it, then wait.
+ */
+async function waitForRendered(find, scope, timeoutMs = WAIT_MS) {
+    const found = find();
+    if (found) {
+        return found;
+    }
+    if (scope instanceof HTMLElement) {
+        scope.scrollIntoView({ block: "start" });
+    }
+    return waitFor(find, timeoutMs);
+}
+/** Tabs fields at this level of the scope, in DOM order; nested tabs and rows are other scopes. */
+function tabsFieldsIn(scope) {
+    return Array.from(scope.querySelectorAll(".tabs-field")).filter((element) => {
+        const outer = element.parentElement?.closest(".tabs-field, .blocks-field, .array-field");
+        return !outer || !scope.contains(outer);
+    });
+}
+function waitFor(find, timeoutMs = WAIT_MS) {
+    const deadline = performance.now() + timeoutMs;
+    return new Promise((resolve) => {
+        const tick = () => {
+            const found = find();
+            if (found || performance.now() >= deadline) {
+                resolve(found);
+                return;
+            }
+            requestAnimationFrame(tick);
+        };
+        tick();
+    });
+}
+/**
+ * A field or a row. Inputs carry `field-…` ids, rich text and some other fields only
+ * `data-field-path`, block and array rows `…-row-N` ids.
+ */
+function findTarget(path) {
+    const field = document.getElementById(`field-${path.replace(/\./g, "__")}`) ??
+        document.querySelector(`[data-field-path="${CSS.escape(path)}"]`);
+    if (field) {
+        return field;
+    }
+    const segments = path.split(".");
+    const index = segments.pop();
+    return index !== undefined && /^\d+$/.test(index)
+        ? document.getElementById(rowDomId({ parentPath: segments.join("."), index: Number(index) }))
+        : null;
+}
+/** DOM id Payload gives block and array rows: ("layout", 0) → "layout-row-0". */
+function rowDomId(step) {
+    return `${step.parentPath.split(".").join("-")}-row-${step.index}`;
+}
+/**
+ * Scroll to and highlight the target. A field with an input gets focus; a row or a blocks field is
+ * only highlighted, since focusing it would land in whatever input comes first.
+ */
+async function reveal(element, current) {
+    const isRow = /-row-\d+$/.test(element.id);
+    const highlighted = isRow ? element : (element.closest(".field-type") ?? element);
+    const focusable = isRow ? null : focusTarget(element);
+    await scrollWhenSettled(highlighted, current, () => {
+        focusable?.focus({ preventScroll: true });
+        highlighted.classList.remove(HIGHLIGHT_CLASS);
+        // Restart the animation when the same element is revealed twice.
+        void highlighted.offsetWidth;
+        highlighted.classList.add(HIGHLIGHT_CLASS);
+        window.setTimeout(() => highlighted.classList.remove(HIGHLIGHT_CLASS), HIGHLIGHT_MS);
+    });
+}
+function focusTarget(element) {
+    if (isFocusable(element)) {
+        return element;
+    }
+    // A blocks or array field holds other fields' inputs; none of them is the target.
+    if (element.matches(".blocks-field, .array-field") || element.querySelector("[id*='-row-']")) {
+        return null;
+    }
+    return (element.querySelector("input:not([type='hidden']):not([type='file']), textarea, select, [contenteditable='true']") ?? element.querySelector("button:not([disabled])"));
+}
+/**
+ * Scroll `element` to the middle of the form, robust to the form changing under the scroll:
+ * Payload renders field groups as they come near the viewport and textareas grow to fit their
+ * text, which pushes the target down. Start once its position is stable, and scroll again if it
+ * has moved out of view by the time the scroll is done. `onScroll` runs as the scroll starts.
+ */
+async function scrollWhenSettled(element, current, onScroll) {
+    await layoutSettled(element);
+    if (!current()) {
+        return;
+    }
+    element.scrollIntoView({ behavior: "smooth", block: "center" });
+    onScroll?.();
+    await new Promise((resolve) => window.setTimeout(resolve, SCROLL_MS));
+    await layoutSettled(element);
+    if (current() && !inView(element)) {
+        element.scrollIntoView({ behavior: "smooth", block: "center" });
+    }
+}
+/** Resolves once the element has kept its position for a few frames (or after a timeout). */
+function layoutSettled(element, timeoutMs = WAIT_MS) {
+    const deadline = performance.now() + timeoutMs;
+    let last = Number.NaN;
+    let stable = 0;
+    return new Promise((resolve) => {
+        const tick = () => {
+            const top = element.getBoundingClientRect().top;
+            stable = top === last ? stable + 1 : 0;
+            last = top;
+            if (stable >= STABLE_FRAMES || performance.now() >= deadline) {
+                resolve();
+                return;
+            }
+            requestAnimationFrame(tick);
+        };
+        tick();
+    });
+}
+/** Mostly visible: its middle, or for a tall element any part, is within the middle of the viewport. */
+function inView(element) {
+    const rect = element.getBoundingClientRect();
+    const margin = window.innerHeight * 0.15;
+    return rect.bottom > margin && rect.top < window.innerHeight - margin;
+}
+function isFocusable(element) {
+    return (element instanceof HTMLInputElement ||
+        element instanceof HTMLTextAreaElement ||
+        element instanceof HTMLSelectElement ||
+        element.isContentEditable);
+}

package/dist/admin/ContentHealthNavLink.d.ts

@@ -0,0 +1,3 @@
+import "../styles/admin.css";
+/** The work list in Admin's nav, marked up like Payload's own collection links. */
+export declare function ContentHealthNavLink(): import("react").JSX.Element;

package/dist/admin/ContentHealthNavLink.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Link, useConfig, useTranslation } from "@payloadcms/ui";
+import "../styles/admin.css";
+import { usePathname } from "next/navigation";
+import { formatAdminURL } from "payload/shared";
+import { LIST_COPY, uiLanguage } from "../copy.js";
+import { VIEW_PATH } from "../links.js";
+/** The work list in Admin's nav, marked up like Payload's own collection links. */
+export function ContentHealthNavLink() {
+    const pathname = usePathname();
+    const { config } = useConfig();
+    const { i18n } = useTranslation();
+    const href = formatAdminURL({ adminRoute: config.routes.admin, path: VIEW_PATH });
+    const label = LIST_COPY[uiLanguage(i18n.language)].nav;
+    const active = pathname === href;
+    const content = (_jsxs(_Fragment, { children: [active ? _jsx("div", { className: "nav__link-indicator" }) : null, _jsx("span", { className: "nav__link-label", children: label })] }));
+    return active ? (_jsx("div", { className: "nav__link content-health-nav", id: "nav-content-health", children: content })) : (_jsx(Link, { className: "nav__link content-health-nav", href: href, id: "nav-content-health", prefetch: false, children: content }));
+}

package/dist/admin/reveal-plan.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Work out which tabs must be opened to show a form path. Payload only renders the active tab,
+ * so a field in another tab has no DOM element until its tab button is clicked.
+ * Pure: takes client field config, returns steps for the Admin bridge to perform.
+ */
+export type FieldLike = {
+    type: string;
+    name?: string;
+    label?: unknown;
+    /** Array fields: Payload fills `singular` from the name when the config leaves it out. */
+    labels?: {
+        singular?: unknown;
+    };
+    fields?: FieldLike[];
+    tabs?: Array<{
+        name?: string;
+        fields?: FieldLike[];
+    }>;
+    blocks?: BlockLike[];
+    blockReferences?: Array<BlockLike | string>;
+};
+export type BlockLike = {
+    slug: string;
+    labels?: {
+        singular?: unknown;
+    };
+    fields?: FieldLike[];
+};
+export type RevealStep = 
+/** Click tab `index` of the `ordinal`-th tabs field in the current scope. The tab content becomes the scope. */
+{
+    kind: "tab";
+    ordinal: number;
+    index: number;
+}
+/** Enter a block or array row. The row element becomes the scope. */
+ | {
+    kind: "row";
+    parentPath: string;
+    index: number;
+};
+export type Lookup = {
+    /** Block slug of the row at a form path, e.g. "layout.0" → "hero". */
+    blockTypeAt: (rowPath: string) => string | undefined;
+    /** Blocks declared once in config and referenced by slug. */
+    blocksBySlug?: Record<string, BlockLike | undefined>;
+};
+export declare function planReveal(rootFields: FieldLike[], path: string, lookup: Lookup): RevealStep[] | null;
+/** The field config a form path ends at, e.g. "layout.2.items" → the `items` array field. */
+export declare function fieldAtPath(rootFields: FieldLike[], path: string, lookup: Lookup): FieldLike | null;

package/dist/admin/reveal-plan.js

@@ -0,0 +1,135 @@
+/*
+ * Copied from @simmalugnt-se/payload-visual-editing (src/reveal-plan.ts), which reveals fields
+ * clicked in the preview. The packages do not import each other; keep fixes in step with that copy.
+ */
+/**
+ * Work out which tabs must be opened to show a form path. Payload only renders the active tab,
+ * so a field in another tab has no DOM element until its tab button is clicked.
+ * Pure: takes client field config, returns steps for the Admin bridge to perform.
+ */
+export function planReveal(rootFields, path, lookup) {
+    return walkPath(rootFields, path, lookup)?.steps ?? null;
+}
+/** The field config a form path ends at, e.g. "layout.2.items" → the `items` array field. */
+export function fieldAtPath(rootFields, path, lookup) {
+    return walkPath(rootFields, path, lookup)?.field ?? null;
+}
+function walkPath(rootFields, path, lookup) {
+    const segments = path.split(".");
+    const steps = [];
+    let fields = rootFields;
+    let counter = { value: 0 };
+    let walked = [];
+    let last = null;
+    for (let i = 0; i < segments.length;) {
+        const segment = segments[i] ?? "";
+        const found = findIn(fields, segment, counter);
+        if (!found) {
+            return null;
+        }
+        steps.push(...found.tabs);
+        counter = found.counter;
+        walked = [...walked, segment];
+        i += 1;
+        if (found.kind === "namedTab") {
+            fields = found.fields;
+            counter = { value: 0 };
+            continue;
+        }
+        const field = found.field;
+        last = field;
+        const next = segments[i];
+        if ((field.type === "blocks" || field.type === "array") &&
+            next !== undefined &&
+            /^\d+$/.test(next)) {
+            const parentPath = walked.join(".");
+            steps.push({ kind: "row", parentPath, index: Number(next) });
+            walked = [...walked, next];
+            i += 1;
+            counter = { value: 0 };
+            if (field.type === "array") {
+                fields = field.fields ?? [];
+                continue;
+            }
+            const block = findBlock(field, lookup.blockTypeAt(walked.join(".")), lookup.blocksBySlug);
+            if (!block) {
+                return null;
+            }
+            fields = block.fields ?? [];
+            continue;
+        }
+        if (field.fields) {
+            // Named group: same DOM scope, keep counting tabs.
+            fields = field.fields;
+            continue;
+        }
+        // A leaf; anything after it (e.g. rich text internals) is not a form field.
+        return i === segments.length ? { steps, field } : null;
+    }
+    return { steps, field: last };
+}
+function findIn(fields, name, counter) {
+    for (const field of fields) {
+        if (field.type === "tabs") {
+            const ordinal = counter.value;
+            counter.value += 1;
+            for (const [index, tab] of (field.tabs ?? []).entries()) {
+                const step = { kind: "tab", ordinal, index };
+                if (tab.name === name) {
+                    return {
+                        kind: "namedTab",
+                        fields: tab.fields ?? [],
+                        tabs: [step],
+                        counter: { value: 0 },
+                    };
+                }
+                if (!tab.name) {
+                    const inner = findIn(tab.fields ?? [], name, { value: 0 });
+                    if (inner) {
+                        return { ...inner, tabs: [step, ...inner.tabs] };
+                    }
+                }
+            }
+            continue;
+        }
+        if (field.name === name) {
+            return { kind: "field", field, tabs: [], counter };
+        }
+        if (!field.name && field.fields) {
+            // Row, collapsible or unnamed group: transparent for paths.
+            const inner = findIn(field.fields, name, counter);
+            if (inner) {
+                return inner;
+            }
+            continue;
+        }
+        counter.value += countTabs(field);
+    }
+    return null;
+}
+/** Tabs fields rendered inside a field that is skipped, so later ordinals stay aligned with the DOM. */
+function countTabs(field) {
+    if (field.type === "tabs") {
+        return 1;
+    }
+    if (field.type === "blocks" || field.type === "array" || !field.fields) {
+        return 0;
+    }
+    return field.fields.reduce((sum, child) => sum + countTabs(child), 0);
+}
+function findBlock(field, slug, blocksBySlug) {
+    if (!slug) {
+        return undefined;
+    }
+    const inline = field.blocks?.find((block) => block.slug === slug);
+    if (inline) {
+        return inline;
+    }
+    for (const reference of field.blockReferences ?? []) {
+        const block = typeof reference === "string" ? blocksBySlug?.[reference] : reference;
+        if (block?.slug === slug) {
+            return block;
+        }
+    }
+    return undefined;
+}

package/dist/admin/target.d.ts

@@ -0,0 +1,9 @@
+import type { RevealStep } from "./reveal-plan.ts";
+/**
+ * The path itself when the form has it, otherwise the nearest enclosing field or row that it has:
+ * the finding was made on the saved version, and the unsaved form may have fewer rows.
+ */
+export declare function revealTarget(path: string, plan: (path: string) => RevealStep[] | null): {
+    path: string;
+    steps: RevealStep[];
+} | null;

package/dist/admin/target.js

@@ -0,0 +1,15 @@
+/**
+ * The path itself when the form has it, otherwise the nearest enclosing field or row that it has:
+ * the finding was made on the saved version, and the unsaved form may have fewer rows.
+ */
+export function revealTarget(path, plan) {
+    const segments = path.split(".");
+    for (let length = segments.length; length > 0; length -= 1) {
+        const candidate = segments.slice(0, length).join(".");
+        const steps = plan(candidate);
+        if (steps) {
+            return { path: candidate, steps };
+        }
+    }
+    return null;
+}