chore(ui): move unpublish actions into document controls dropdown (#15417)

### What / Why

This PR updates and fixes aspects of the `unpublish` UI:

1. **Button location**: The **unpublish** button update in
[v3.72.0](https://github.com/payloadcms/payload/releases/tag/v3.72.0)
was reported as too prominent by the community. We have moved it into
the additional document actions dropdown.
2. **Bug**: The `Unpublish in [locale]` option should only be displayed
when `localizeStatus` is enabled.
3. **Performance**: In the `unpublish` component, several variables were
recalculating on every render, causing unnecessary load and causing
ESLint warnings.

### Where

1. In `DocumentControls`, the `unpublish` button has been moved from the
top level into the additional document actions dropdown.
2. Within the `unpublish` button component, the conditional logic for
`canUnpublishCurrentLocale` has been corrected so it will only show when
`localizeStatus` is enabled.
3. Lastly, the variables `canUnpublish` and `canUnpublishCurrentLocale`
have been wrapped in `useMemo` to prevent excessive recalculating


#### Fixes #15291

<img width="1013" height="409" alt="Screenshot 2026-01-29 at 11 51
47 AM"
src="https://github.com/user-attachments/assets/a630406d-e444-4ecd-ab69-ba84f85d4b3e"
/>

---------

Co-authored-by: Patrik Kozak <35232443+PatrikKozak@users.noreply.github.com>

Author: JessRynkar

packages/ui/src/elements/DocumentControls/index.tsx

@@ -277,15 +277,11 @@ export const DocumentControls: React.FC<{
                     {(unsavedDraftWithValidations ||
                       !autosaveEnabled ||
                       (autosaveEnabled && showSaveDraftButton)) && (
-                      <RenderCustomComponent
-                        CustomComponent={CustomSaveDraftButton}
-                        Fallback={<SaveDraftButton />}
-                      />
-                    )}
-                    <RenderCustomComponent
-                      CustomComponent={CustomUnpublishButton}
-                      Fallback={<UnpublishButton />}
-                    />
+                        <RenderCustomComponent
+                          CustomComponent={CustomSaveDraftButton}
+                          Fallback={<SaveDraftButton />}
+                        />
+                      )}
                     <RenderCustomComponent
                       CustomComponent={CustomPublishButton}
                       Fallback={<PublishButton />}
@@ -403,6 +399,10 @@ export const DocumentControls: React.FC<{
                     useAsTitle={collectionConfig?.admin?.useAsTitle}
                   />
                 )}
+                <RenderCustomComponent
+                  CustomComponent={CustomUnpublishButton}
+                  Fallback={<UnpublishButton />}
+                />
                 {EditMenuItems}
               </PopupList.ButtonGroup>
             </Popup>

packages/ui/src/elements/UnpublishButton/index.tsx

@@ -10,7 +10,6 @@ import React, { useCallback, useEffect, useState } from 'react'
 import { toast } from 'sonner'
 
 import { useForm } from '../../forms/Form/context.js'
-import { FormSubmit } from '../../forms/Submit/index.js'
 import { useConfig } from '../../providers/Config/index.js'
 import { useDocumentInfo } from '../../providers/DocumentInfo/index.js'
 import { useLocale } from '../../providers/Locale/index.js'
@@ -41,7 +40,6 @@ export function UnpublishButton({
   const { reset: resetForm } = useForm()
   const { code: localeCode, label: localeLabel } = useLocale()
   const [unpublishAll, setUnpublishAll] = useState(false)
-
   const unPublishModalSlug = `confirm-un-publish-${id}`
 
   const {
@@ -63,7 +61,7 @@ export function UnpublishButton({
 
   const unpublish = useCallback(
     (unpublishAll?: boolean) => {
-      ;(async () => {
+      ; (async () => {
         let url
         let method
 
@@ -161,50 +159,57 @@ export function UnpublishButton({
     setHasLocalizedFields(hasLocalizedField)
   }, [entityConfig?.fields])
 
-  const canUnpublish = hasPublishPermission && hasPublishedDoc && !isTrashed
-  const canUnpublishCurrentLocale = hasLocalizedFields && canUnpublish
+  const canUnpublish = React.useMemo(
+    () => hasPublishPermission && hasPublishedDoc && !isTrashed,
+    [hasPublishPermission, hasPublishedDoc, isTrashed],
+  )
+
+  const canUnpublishCurrentLocale = React.useMemo(() => {
+    if (!canUnpublish || !hasLocalizedFields) { return false }
+
+    const drafts = entityConfig?.versions?.drafts
+    const hasDraftsConfig = typeof drafts === 'object' && drafts !== null
+    const localizeStatusConfigured = hasDraftsConfig && drafts.localizeStatus === true
+    const experimentalLocalizeStatus =
+      config.experimental &&
+      'localizeStatus' in config.experimental &&
+      config.experimental.localizeStatus === true
+
+    return localizeStatusConfigured && experimentalLocalizeStatus
+  }, [canUnpublish, hasLocalizedFields, entityConfig?.versions?.drafts, config.experimental])
+
+
+  const label = getTranslation(localeLabel, i18n)
 
   return (
     <React.Fragment>
       {canUnpublish && (
         <>
-          <FormSubmit
-            buttonId="action-unpublish"
-            disabled={!canUnpublish}
-            enableSubMenu={canUnpublishCurrentLocale}
+          {canUnpublish && <PopupList.Button
+            id="action-unpublish"
             onClick={() => {
               setUnpublishAll(true)
               toggleModal(unPublishModalSlug)
             }}
-            size="medium"
-            SubMenuPopupContent={
-              canUnpublishCurrentLocale
-                ? ({ close }) => {
-                    return (
-                      <PopupList.ButtonGroup>
-                        <PopupList.Button
-                          id="action-unpublish-locale"
-                          onClick={() => {
-                            setUnpublishAll(false)
-                            toggleModal(unPublishModalSlug)
-                            close()
-                          }}
-                        >
-                          {t('version:unpublishIn', { locale: getTranslation(localeLabel, i18n) })}
-                        </PopupList.Button>
-                      </PopupList.ButtonGroup>
-                    )
-                  }
-                : undefined
-            }
-            type="button"
           >
             {labelProp || t('version:unpublish')}
-          </FormSubmit>
+          </PopupList.Button >}
+          {
+            canUnpublishCurrentLocale && <PopupList.Button
+              id="action-unpublish-locale"
+              onClick={() => {
+                setUnpublishAll(false)
+                toggleModal(unPublishModalSlug)
+                close()
+              }}
+            >
+              {labelProp ? labelProp + ` [${label}]` : t('version:unpublishIn', { locale: label })}
+            </PopupList.Button>
+          }
           <ConfirmationModal
             body={
               !unpublishAll
-                ? t('version:aboutToUnpublishIn', { locale: getTranslation(localeLabel, i18n) })
+                ? t('version:aboutToUnpublishIn', { locale: label })
                 : t('version:aboutToUnpublish')
             }
             confirmingLabel={t('version:unpublishing')}
@@ -214,6 +219,6 @@ export function UnpublishButton({
           />
         </>
       )}
-    </React.Fragment>
+    </React.Fragment >
   )
 }

test/localization/e2e.spec.ts

@@ -766,6 +766,28 @@ describe('Localization', () => {
       expect(isActuallyVisible).toBe(true)
     })
 
+    describe('unpublish button', () => {
+      test('should show unpublish in specific locale when localizeStatus is enabled', async () => {
+        await page.goto(urlAllFieldsLocalized.create)
+        await page.locator('#field-text').fill('EN Published')
+        await saveDocAndAssert(page, '#publish-locale')
+        await openDocControls(page)
+
+        await expect(page.locator('#action-unpublish')).toBeVisible()
+        await expect(page.locator('#action-unpublish-locale')).toBeVisible()
+      })
+
+      test('should not show unpublish in specific locale when localizeStatus is not enabled', async () => {
+        await page.goto(urlPostsWithDrafts.create)
+        await page.locator('#field-title').fill('EN Published')
+        await saveDocAndAssert(page, '#publish-locale')
+        await openDocControls(page)
+
+        await expect(page.locator('#action-unpublish')).toBeVisible()
+        await expect(page.locator('#action-unpublish-locale')).toHaveCount(0)
+      })
+    })
+
     test('should show locale in slate rich text field label', async () => {
       await page.goto(urlAllFieldsLocalized.create)
 

test/versions/e2e.spec.ts

@@ -50,6 +50,7 @@ import {
 import { AdminUrlUtil } from '../helpers/adminUrlUtil.js'
 import { assertNetworkRequests } from '../helpers/e2e/assertNetworkRequests.js'
 import { navigateToDiffVersionView as _navigateToDiffVersionView } from '../helpers/e2e/navigateToDiffVersionView.js'
+import { openDocControls } from '../helpers/e2e/openDocControls.js'
 import { waitForAutoSaveToRunAndComplete } from '../helpers/e2e/waitForAutoSaveToRunAndComplete.js'
 import { initPayloadE2ENoConfig } from '../helpers/initPayloadE2ENoConfig.js'
 import { reInitializeDB } from '../helpers/reInitializeDB.js'
@@ -794,6 +795,7 @@ describe('Versions', () => {
       await page.goto(disablePublishURL.edit(String(publishedDoc.id)))
 
       // Verify unpublish button is hidden when user doesn't have publish permission
+      await openDocControls(page)
       await expect(page.locator('#action-unpublish')).not.toBeAttached()
     })
 
@@ -806,6 +808,7 @@ describe('Versions', () => {
         },
       })
       await page.goto(errorOnUnpublishURL.edit(String(publishedDoc.id)))
+      await openDocControls(page)
       await page.locator('#action-unpublish').click()
       await page.locator('[id^="confirm-un-publish-"] #confirm-action').click()
       await expect(
@@ -825,6 +828,7 @@ describe('Versions', () => {
       const customUnpublishURL = new AdminUrlUtil(serverURL, draftWithCustomUnpublishSlug)
       await page.goto(customUnpublishURL.edit(String(publishedDoc.id)))
 
+      await openDocControls(page)
       await expect(page.getByRole('button', { name: 'Custom Unpublish' })).toBeVisible()
 
       await payload.delete({
@@ -1037,7 +1041,7 @@ describe('Versions', () => {
         await saveDocAndAssert(page, '#action-save-draft')
 
         await expect(page.locator('.doc-controls__status .status__value')).toContainText('Draft')
-
+        await openDocControls(page)
         await expect(page.locator('#action-unpublish')).toBeHidden()
       })
 
@@ -1055,7 +1059,7 @@ describe('Versions', () => {
         await expect(page.locator('.doc-controls__status .status__value')).toContainText(
           'Published',
         )
-
+        await openDocControls(page)
         await expect(page.locator('#action-unpublish')).toBeVisible()
       })
 
@@ -1072,6 +1076,7 @@ describe('Versions', () => {
         await saveDocAndAssert(page, '#action-save-draft')
 
         await expect(page.locator('.doc-controls__status .status__value')).toContainText('Draft')
+        await openDocControls(page)
         await expect(page.locator('#action-unpublish')).toBeHidden()
       })
     })