/**
* The frame's parts: the header bar, the page heading, the page tabs, the
* mark and the one "New campaign". The look comes from the design system in
* src/admin/styles.
*
* Mailpuff sits inside the WordPress admin: WordPress's own menu carries the sections
* (Home, Campaigns, Subscribers, Settings), its bar the way
* around the site, and its command palette (⌘K) the search. Every Mailpuff
* page starts with the same quiet header (`AppBar`, 2026-10-24): the puffin
* on the left; Create and Help on the right, nothing else. A page's own
* actions sit at the right of its heading (`PageActions`).
*/
import { useState } from '@wordpress/element';
import { applyFilters } from '@wordpress/hooks';
import { __ } from '@wordpress/i18n';
import {
ArrowLeft,
ArrowUpRight,
ChevronDown,
CircleHelp,
ClipboardPen,
ListFilter,
Mail,
Plus,
Tag,
Upload,
UserPlus,
} from 'lucide-react';
import { cn, ui } from '../kit';
import { useNewCampaign } from '../hooks/use-campaigns';
import AddContactDialog from '../components/AddContactDialog';
import { listArgs } from '../lib/contact-filter';
import { locationUrl, readLocation } from './nav';
import { openWpCommands } from './wp-commands';
import mark from '../../../assets/brand/mark.json';
/** Where "Get support" goes: Mailpuff's WordPress.org forum. */
const SUPPORT_URL = 'https://wordpress.org/support/plugin/mailpuff/';
/**
* Mailpuff's puffin in one colour: the head and beak, with the face cut out.
* The shared geometry also powers the WordPress menu and exported SVGs; see
* docs/branding.md.
*
* @param {Object} props
* @param {string} props.className Size and colour.
*/
export function Mark( { className } ) {
return (
);
}
/**
* "New campaign": the primary action of Campaigns. On Home it is secondary,
* because "Next up" holds that page's one primary action. Other pages have
* their own (Add subscriber).
*
* @param {Object} props
* @param {string} props.variant primary (default) or secondary.
* @return {Element} The button.
*/
export function NewCampaignButton( { variant = 'primary' } ) {
const creating = useNewCampaign();
return (
{ __( 'New campaign', 'mailpuff' ) }
);
}
/**
* The section's pages, as tabs under the heading.
*
* @param {Object} props
* @param {Array} props.pages `{ id, label }`.
* @param {string} props.current The open page.
* @param {Function} props.onChange Called with a page id.
*/
export function PageTabs( { pages, current, onChange } ) {
return (
);
}
const HEADING =
'm-0 text-[28px] leading-9 font-semibold tracking-[-0.025em] text-foreground';
/**
* The page's heading: the section's name, or, while a view is open, the
* item's name under a way back to the section. A list narrowed to one
* thing (a tag or a segment on Subscribers) reads "Subscribers › Tutorials",
* the section's name leading back to the whole list, with a short fact
* beside it ("598 can be emailed").
*
* @param {Object} props
* @param {string} props.title The section's name.
* @param {string} props.drill The open item's name, or ''.
* @param {?Object} props.narrowed `{ title, meta?, back }`, or null.
* @param {Function} props.onBack Leaves the view.
* @param {*} props.actions Optional controls on the same line.
*/
export function PageHeading( { title, drill, narrowed, onBack, actions } ) {
let heading = (
{ drill || title }
);
if ( ! drill && narrowed ) {
heading = (
›
{ narrowed.title }
{ narrowed.meta && (
{ narrowed.meta }
) }
);
}
return (
{ drill && (
) }
{ heading }
{ actions }
);
}
/**
* Whether a click should stay in this page: a plain left click.
*
* @param {MouseEvent} event Click.
* @return {boolean} True to handle it here.
*/
const plainClick = ( event ) =>
event.button === 0 &&
! event.metaKey &&
! event.ctrlKey &&
! event.shiftKey &&
! event.altKey;
/**
* The menu items, grouped: a hairline goes between groups.
*
* @param {Array} items `{ id, label, group?, icon?, shortcut?, onSelect }`.
* @return {Array} Items and separators.
*/
function menuItems( items ) {
const out = [];
items.forEach( ( item, i ) => {
if (
i > 0 &&
( item.group || '' ) !== ( items[ i - 1 ].group || '' )
) {
out.push( );
}
out.push(
{ item.label }
);
} );
return out;
}
/**
* The key that opens WordPress's command palette here.
*
* @return {string} ⌘K on a Mac, Ctrl+K elsewhere.
*/
function paletteKey() {
const platform =
( typeof navigator !== 'undefined' &&
( navigator.userAgentData?.platform || navigator.platform ) ) ||
'';
return /mac|iphone|ipad/i.test( platform ) ? '⌘K' : 'Ctrl+K';
}
/**
* The header on every Mailpuff page: the puffin (to Home) on the left;
* Create and Help on the right. Create is a quiet button, so each page keeps
* one primary action, in its heading.
*
* Add-ons add their own items through the `mailpuff.createItems` and
* `mailpuff.helpItems` filters: `{ id, label, group?, icon?, shortcut?,
* onSelect }`, given `{ navigate }`. Items of one `group` sit together.
*
* @param {Object} props
* @param {Function} props.navigate The frame's navigate.
* @return {Element} The header.
*/
export function AppBar( { navigate } ) {
const creating = useNewCampaign();
const [ adding, setAdding ] = useState( false );
const icon = 'size-4 text-muted-foreground';
// New tag and New segment are dialogs of Subscribers (`do=new-tag`,
// `do=new-segment`), opened over the list on screen when it is open.
const onSubscribers = ( action ) => () => {
const here = readLocation( window.location.search );
const list =
here.tab === 'contacts' && ! here.view ? listArgs( here.args ) : {};
navigate( {
tab: 'contacts',
view: '',
args: { ...list, do: action },
} );
};
const create = applyFilters(
'mailpuff.createItems',
[
{
id: 'campaign',
group: 'campaigns',
label: __( 'New campaign', 'mailpuff' ),
icon: ,
onSelect: creating.start,
},
{
id: 'subscriber',
group: 'subscribers',
label: __( 'Add subscriber', 'mailpuff' ),
icon: ,
onSelect: () => setAdding( true ),
},
{
id: 'import',
group: 'subscribers',
label: __( 'Import subscribers', 'mailpuff' ),
icon: ,
onSelect: () =>
navigate( { tab: 'contacts', view: 'import', args: {} } ),
},
{
id: 'form',
group: 'forms',
label: __( 'New form', 'mailpuff' ),
icon: ,
onSelect: () =>
navigate( {
tab: 'forms',
view: '',
args: { do: 'new' },
} ),
},
{
id: 'tag',
group: 'subscribers',
label: __( 'New tag', 'mailpuff' ),
icon: ,
onSelect: onSubscribers( 'new-tag' ),
},
{
id: 'segment',
group: 'subscribers',
label: __( 'New segment', 'mailpuff' ),
icon: ,
onSelect: onSubscribers( 'new-segment' ),
},
],
{ navigate }
);
const help = applyFilters(
'mailpuff.helpItems',
[
{
id: 'help',
label: __( 'Help and FAQ', 'mailpuff' ),
onSelect: () => navigate( { tab: 'help', view: '', args: {} } ),
},
{
id: 'start',
label: __( 'Getting started', 'mailpuff' ),
onSelect: () =>
navigate( { tab: 'welcome', view: '', args: {} } ),
},
{
id: 'agent',
label: __( 'Connect an AI agent', 'mailpuff' ),
onSelect: () =>
navigate( {
tab: 'settings',
sub: 'mcp',
view: '',
args: {},
} ),
},
{
id: 'commands',
label: __( 'Search and commands', 'mailpuff' ),
shortcut: paletteKey(),
onSelect: openWpCommands,
},
{
id: 'support',
group: 'outside',
label: __( 'Get support', 'mailpuff' ),
shortcut: (
),
onSelect: () =>
window.open( SUPPORT_URL, '_blank', 'noopener' ),
},
],
{ navigate }
);
const homeUrl = locationUrl( {
tab: 'home',
sub: '',
view: '',
args: {},
} );
return (
// A div, not : inside WordPress's main region a banner
// landmark is out of place.