payload-nested-docs-page-tree 1.5.0 → 1.6.0

package/README.md

@@ -5,6 +5,7 @@ Page management tools for Payload admin, built on [`@payloadcms/plugin-nested-do
 - **Page tree UI** with hierarchy and page URL paths.
 - **Intuitive drag and drop** to reorder siblings or move pages between parents.
 - **Status badges** for published pages, drafts, and drafts with unpublished changes.
+- **Localized status badges** to see each language's publication status and open the page editor in that language with one click.
 - **Live and preview links** from badges, with separate destinations for changed pages.
 - **Customizable badges** with label and color overrides for light and dark themes.
 - **Homepage icon** to identify the root `home` page.
@@ -14,7 +15,7 @@ Page management tools for Payload admin, built on [`@payloadcms/plugin-nested-do
 
 **Coming soon:** custom badges for any cell.
 
-[Page tree](#page-tree-ui) · [Drag and drop](#drag-and-drop) · [Badges](#badges) · [Live and preview links](#live-and-preview-links) · [Homepage icon](#homepage-icon) · [Diagnostics](#diagnostics) · [Full setup](#setup) · [Configuration](#configuration)
+[Page tree](#page-tree-ui) · [Drag and drop](#drag-and-drop) · [Badges](#badges) · [Localized status](#locale-status-badges) · [Live and preview links](#live-and-preview-links) · [Homepage icon](#homepage-icon) · [Diagnostics](#diagnostics) · [Full setup](#setup) · [Configuration](#configuration)
 
 ## Page tree UI
 
@@ -107,6 +108,81 @@ See [the playground deploy hook](dev/lib/rebuild.ts) for a complete example. The
 
 Override any labels or colors with `badges`. Unspecified values use Payload defaults; custom colors adapt to light and dark themes.
 
+### Locale status badges
+
+![Localized page status badges for English, French, and German, with French selected](assets/localized-status.png)
+
+See each page's publication status across languages directly in the page tree. Each language has its own color-coded badge showing whether the page is published, a draft, or has unpublished changes. Click a language badge to open that page's editor in the selected language, in the same tab.
+
+The active language also shows its status label, such as **FR · Published** or **FR · Changed**. Other languages show their codes, such as **EN** and **DE**, with their own status colors. Badges line up across rows so editors can quickly scan for translations that need attention.
+
+Set `badges.locales: true` to show one badge for each available locale:
+
+```ts
+nestedDocsPageTreePlugin({
+  collections: ['pages'],
+  badges: {
+    locales: true,
+    // Existing colors and labels apply independently to each status.
+    labels: { changed: 'Unpublished edits' },
+  },
+})
+```
+
+For an editor using French, the badges appear side by side: **EN** | **FR · Unpublished edits** | **DE**.
+
+Locale codes display in uppercase and follow the order in Payload's localization configuration, respecting `filterAvailableLocales`. Existing badge label and color overrides apply to each locale's status.
+
+Badge links support keyboard navigation, include the language and status in their accessible names, and respect your configured admin route. Hidden badges preserve their aligned slots and cannot be clicked. Locale badges link to the editor independently of `badgesLinks`, which controls live and preview links on single status badges.
+
+This requires Payload's native localized status, configured separately:
+
+```ts
+// Main Payload config
+experimental: { localizeStatus: true },
+localization: {
+  defaultLocale: 'en',
+  locales: ['en', 'fr', 'de'],
+},
+
+// Target collection
+versions: {
+  drafts: { localizeStatus: true },
+},
+```
+
+Localized status is experimental in the supported Payload versions. Follow [Payload's status-localization and migration guidance](https://payloadcms.com/docs/configuration/localization#status-localization) before enabling it for existing data. The plugin does not enable it or migrate your database. Collections without localized status, or with `badges.locales` omitted, retain the existing single badge.
+
+Statuses are read from the latest draft and current document, with locale fallback disabled:
+
+| Latest locale status | Current locale status | Badge |
+| --- | --- | --- |
+| Published | Any | Published |
+| Draft | Published | Unpublished edits |
+| Draft | Draft or missing | Draft |
+| Missing or unsupported | Any | Unknown (neutral) |
+
+The plugin batches the two status reads across the tree result, respects read permissions, and does not fetch content separately for every badge.
+
+#### Custom appearance
+
+The plugin keeps the status calculation and layout reusable. Use these styling hooks to apply a project-specific appearance, such as seasonal colors and status icons:
+
+- `.pages-hierarchy-locale-statuses`: the badge group.
+- `.pages-hierarchy-locale-status-badge`: a badge, with `data-locale`, `data-status`, and `data-active`.
+- `.pages-hierarchy-locale-status-badge__code`, `__separator`, and `__label`: the visible pieces.
+
+For example, local admin CSS can assign a season color:
+
+```css
+.pages-hierarchy-locale-statuses .pages-hierarchy-locale-status-badge[data-locale='summer'] {
+  background: #fff0a8;
+  color: #594600;
+}
+```
+
+A reskin can hide `__code` and `__separator` and add a status icon using the badge's `::before` and `data-status`, keeping the active status label and accessible name. The default plugin supplies no icons.
+
 ### Live and preview links
 
 
@@ -114,25 +190,50 @@ https://github.com/user-attachments/assets/e5fdb350-4740-4d80-9811-8c23deaf8701
 
 Enable `badgesLinks` as shown in [Setup](#setup).
 
-Published badges open live; draft-only badges open preview. For drafts with a published version, choose:
+Published badges open live with a right-side link icon; draft-only badges open preview with a right-side eye icon. Because drafts with a published version has two (live and draft) states, choose:
 
 | Value | Behavior |
 | --- | --- |
-| `'live'` | Badge opens live |
-| `'preview'` | Badge opens preview |
-| `'both'` (default) | Body opens live; right-side icon opens preview |
+| `'live'` | Whole badge, including the right-side link icon, opens live |
+| `'preview'` | Whole badge, including the right-side eye icon, opens preview |
+| `'both'` (default) | Body with link icon opens live; eye icon after a separator opens preview |
 
-- **Live:** Uses the published document's last breadcrumb URL and `liveURL`. Breadcrumbs must match your frontend routes. Omit `liveURL` for preview links only.
+- **Live:** A string `liveURL` is the base URL for the published document's last breadcrumb path. Alternatively, pass a sync or async callback returning the final URL for tenant domains or localized routes. Omit `liveURL` for preview links only.
 - **Preview:** Uses the collection's [`admin.preview`](https://payloadcms.com/docs/admin/preview) callback. Your frontend must serve draft content.
 
-All links open in new tabs. Omit `badgesLinks` to keep badges unlinked, even with preview configured.
+All live and preview links open in new tabs. Unlinked badges have no icon. Omit `badgesLinks` to keep single status badges unlinked, even with preview configured. Locale badges still link to the editor.
+
+`badgesLinks.showIcons` defaults to `true`: live links use Payload's chain-link `LinkIcon`, and preview links use `EyeIcon`. Set it to `false` to hide inline badge icons; in `'both'` mode, the separate preview action still shows `ExternalLinkIcon` after the separator.
+
+For example, with a `tenant` relationship on pages and a `domain` field on tenants:
+
+```ts
+badgesLinks: {
+  liveURL: async ({ doc, locale, path, req }) => {
+    if (!path || (typeof doc.tenant !== 'string' && typeof doc.tenant !== 'number')) {
+      return null
+    }
+
+    const tenant = await req.payload.findByID({
+      collection: 'tenants',
+      id: doc.tenant,
+      overrideAccess: false,
+      req,
+    })
+
+    return new URL(`${locale ? `/${locale}` : ''}${path}`, `https://${tenant.domain}`).href
+  },
+},
+```
+
+The callback receives `{ collectionSlug, doc, locale, path, req }`. `doc` is the readable published document at depth `0`, so relationships contain IDs. `locale` is the selected admin locale, or `undefined` without localization. `path` is the last published breadcrumb URL from `breadcrumbsFieldSlug`, or `undefined` when unavailable. The callback can build its own route without breadcrumbs. It runs only when a live destination is needed and a readable published document exists, and stays on the server. The `PageTreeLiveURL` type is exported for standalone callbacks.
 
 <details>
 <summary>URL resolution and unavailable links</summary>
 
-Live links use `breadcrumbsFieldSlug` and the published path, unaffected by draft slug or parent changes. Preview receives the latest saved draft, locale, request, and user token. Unsaved changes and `admin.livePreview.url` are not used.
+String live links use `breadcrumbsFieldSlug` and the published path, unaffected by draft slug or parent changes. Callback results are used as final URLs without appending the breadcrumb path. Relative callback URLs resolve against the CMS request URL; return an absolute URL for a separate frontend. Only HTTP and HTTPS links are accepted. Preview receives the latest saved draft, locale, request, and user token. Unsaved changes and `admin.livePreview.url` are not used.
 
-Missing breadcrumbs, missing or invalid URLs, or a failing preview callback disable only that link. In `'both'` mode, no live URL leaves the body as text; no preview URL hides the icon. Single-link modes never switch destinations. The selected mode is independent of the badge label.
+Missing breadcrumbs for string live URLs, missing or invalid URLs, or a failing live or preview callback disable only that link. Return `null`, `undefined`, or an empty string from the live callback to leave the live destination unlinked. In `'both'` mode, no live URL leaves the body as text; no preview URL hides the icon. Single-link modes never switch destinations. The selected mode is independent of the badge label.
 
 </details>
 
@@ -208,6 +309,7 @@ export const plugins = [
     },
 
     badgesLinks: { // Omit to disable links; preview uses collection admin.preview.
+      showIcons: true, // Default; false hides inline icons and keeps the split preview action.
       draftHasPublishedVersion: 'both', // 'live' | 'preview' | 'both'
       liveURL: 'https://www.example.com', // Base URL for the published breadcrumb path.
     },
@@ -218,7 +320,7 @@ export const plugins = [
 ]
 ```
 
-Only `collections` is required in the page-tree config. Omit `badges` for default styling and `badgesLinks` to disable links. Preview links require the collection's `admin.preview` callback.
+Only `collections` is required in the page-tree config. Omit `badges` for default styling and `badgesLinks` to disable live and preview links. Preview links require the collection's `admin.preview` callback.
 
 Each target collection needs parent, breadcrumbs, and `admin.useAsTitle` fields stored at the document's top level. Presentational tabs, rows, collapsibles, and unnamed groups are supported; fields inside named tabs or groups are not.
 
@@ -238,7 +340,7 @@ pnpm exec payload generate:importmap
 | `defaultLimit` | `100` | List page size |
 | `hideBreadcrumbs` | `true` | Hide the read-only breadcrumbs field |
 | `homeIndicator` | `{ collections: ['pages'] }` | Collections showing a home icon; `false` disables it |
-| `badges` | Payload defaults | Status label and color overrides |
+| `badges` | Payload defaults | Status labels, colors, and optional locale badges |
 | `badgesLinks` | Disabled | Live and preview links |
 | `publishOnMove` | `false` | Publish moves for pages without pending edits |
 | `diagnostics` | `false` | Structured operation logs |
@@ -258,6 +360,18 @@ pnpm dev
 
 Open [localhost:3000/admin](http://localhost:3000/admin). The playground creates `admin@email.com` / `password` on startup. Use **seed the database** on the dashboard to add sample pages.
 
+The Seed button populates three collections: **Pages** and **Tabbed Pages** use shared publication status; **Localized Pages** uses independent English/French/German status (`en`, `fr`, `de`, in that order). All three use the same 30-page tree, titles, slugs, and ordering in every language. Localized Pages includes mixed published, changed, and draft statuses for testing. Restart the playground after changing locale configuration, then click **seed the database** to populate all three languages. **Reseeding replaces all content and version history in these three playground collections**, removing stale pages and restoring the shared demo hierarchy. Users are preserved.
+
+For a fresh in-memory playground database on Windows:
+
+```powershell
+$env:PAYLOAD_TEST_DATABASE = 'true'
+pnpm.cmd dev
+```
+
+Without that flag, normal development uses `DATABASE_URL` from `dev/.env`. The two status modes can coexist in either database setup; no migration is needed for the new Localized Pages collection.
+
+
 ```bash
 pnpm generate:types
 pnpm generate:importmap
@@ -275,3 +389,26 @@ pnpm add /path/payload-nested-docs-page-tree-*.tgz
 ```
 
 </details>
+
+### Locale badge visibility
+
+With localized status badges enabled, the optional top-level
+`localeBadgeVisibility: ({ doc, locale, req }) => boolean` callback decides which
+badges are visible. It runs only on the server, against the latest draft with all
+locale values and the current user's read access. Returning false hides the badge
+from both sight and assistive technology while preserving its aligned slot,
+including when that locale is selected. Publication status is unchanged.
+
+Without a callback, all locale badges remain visible. When configured, the existing
+batched draft query reads the document content needed by the callback; no per-row
+queries are added. The callback and document content are not passed to the client.
+Project-specific inheritance or detachment rules belong in the consuming app.
+
+The optional top-level
+`localeBadgeStatus: ({ doc, publishedDoc, locale, req, status }) => status`
+callback overrides the displayed status. It receives the latest draft, the current
+document (when readable), and the default computed status. Both documents contain
+all locales. Check the current document's locale status before treating its content
+as published. This callback loads content in the same two access-controlled batched
+queries; no document content or callbacks are passed to the client. It never writes
+publication state. Without it, the plugin's normal status behavior is unchanged.

package/dist/components/PageTreeListView.client.js

@@ -10,9 +10,9 @@ import { buildInsertDropTargets, getDropTargetParentDoc } from '../utilities/dro
 import { CANCEL_DRAG_MESSAGE, getDropValidation } from '../utilities/moveValidation.js';
 import { buildDocSlugPath, buildPageTreeDocs, buildProspectiveDocSlugPath, getDocDisplayLabel, getVisibleTreeDocs } from '../utilities/pageTree.js';
 import { pageTreeCollisionDetectionStrategy } from '../utilities/pageTreeCollision.js';
-import { PageTreeStatusBadge } from './PageTreeStatusBadge.js';
 import { PageTreeProvider, PageTreeRowDndProvider } from './PageTreeContext.js';
 import styles from './PageTreeListView.module.css';
+import { PageTreeStatusBadge } from './PageTreeStatusBadge.js';
 import { PageTreeTitleCell } from './PageTreeTitleCell.js';
 const SILENT_MOVE_MESSAGES = new Set([
     CANCEL_DRAG_MESSAGE
@@ -194,7 +194,8 @@ function sliceColumnState(columnState, docs, renderedCellIndexByDocID) {
 function getSelectableRowData(doc) {
     const record = doc;
     return {
-        id: String(doc.id ?? doc.__pageTreeID),
+        // Payload's selection Map preserves numeric IDs despite SelectRow's string-only type.
+        id: doc.id ?? doc.__pageTreeID,
         _isLocked: Boolean(record._isLocked),
         _userEditing: record._userEditing
     };
@@ -388,10 +389,11 @@ function getDropTargetValidation(args) {
     };
 }
 function renderStatusBadge(args) {
-    const { badgeConfig, badgesLinks, doc, index } = args;
+    const { badgeConfig, badgesLinks, collectionSlug, doc, index } = args;
     return /*#__PURE__*/ _jsx(PageTreeStatusBadge, {
         badgeConfig: badgeConfig,
         badgesLinks: badgesLinks,
+        collectionSlug: collectionSlug,
         doc: doc
     }, doc.__pageTreeID ?? index);
 }
@@ -425,7 +427,7 @@ function ParentMoveToggle({ collectionSlug, enabled, onToggle }) {
     return toggle;
 }
 function buildTableColumns(args) {
-    const { badgeConfig, badgesLinks, columnState, docs, enableRowSelections, homeIndicatorEnabled, orderableFieldName, parentFieldSlug, t, useAsTitle } = args;
+    const { badgeConfig, badgesLinks, collectionSlug, columnState, docs, enableRowSelections, homeIndicatorEnabled, orderableFieldName, parentFieldSlug, t, useAsTitle } = args;
     const columnsToUse = columnState.map((column)=>{
         if (column.accessor === useAsTitle) {
             return {
@@ -444,6 +446,7 @@ function buildTableColumns(args) {
                 renderedCells: docs.map((doc, index)=>renderStatusBadge({
                         badgeConfig,
                         badgesLinks,
+                        collectionSlug,
                         doc,
                         index,
                         t
@@ -892,6 +895,7 @@ export default function PageTreeListViewClient({ allDocs, badgeConfig, badgesLin
     const tableColumns = React.useMemo(()=>buildTableColumns({
             badgeConfig,
             badgesLinks,
+            collectionSlug: props.collectionSlug,
             columnState: paginatedColumnState,
             docs: displayedPaginatedDocs,
             enableRowSelections: props.enableRowSelections,
@@ -908,6 +912,7 @@ export default function PageTreeListViewClient({ allDocs, badgeConfig, badgesLin
         homeIndicatorEnabled,
         orderableFieldName,
         parentFieldSlug,
+        props.collectionSlug,
         props.enableRowSelections,
         i18n.t,
         useAsTitle