@visns-studio/visns-components 6.34.0 → 6.35.0

package/src/components/emailCampaigns/CampaignReport.jsx

@@ -0,0 +1,98 @@
+import React from 'react';
+
+import StatStrip, { Stat } from '../layout/StatStrip';
+import styles from '../styles/EmailCampaigns.module.scss';
+import { formatWhen } from './emailCampaignApi';
+
+/**
+ * How a sent campaign did: every figure is the server's (EmailCampaignReport),
+ * rates over DELIVERED and counted by person.
+ *
+ * Opens are labelled as an estimate on purpose. Apple Mail opens every message
+ * it downloads, and many clients block the tracking image, so an open rate is a
+ * trend rather than a count. Clicks are the reliable signal and lead the links
+ * table.
+ */
+const ACTIVITY_WORDS = {
+    opened: 'opened it',
+    clicked: 'clicked',
+    bounced: 'bounced',
+    complained: 'marked it as spam',
+};
+
+const CampaignReport = ({ report }) => {
+    const percent = (value) => (value === null || value === undefined ? '-' : `${value}%`);
+
+    return (
+        <section className={styles.report}>
+            <StatStrip minWidth="8rem">
+                <Stat label="Sent to" value={report.recipients ?? '-'} />
+                <Stat label="Delivered" value={report.delivered} />
+                <Stat label="Opened" value={percent(report.open_rate)} note={`${report.opened} people`} />
+                <Stat label="Clicked" value={percent(report.click_rate)} note={`${report.clicked} people`} tone="accent" />
+                <Stat label="Bounced" value={report.bounced} tone={report.bounced > 0 ? 'warn' : undefined} />
+                <Stat label="Unsubscribed" value={report.unsubscribed} />
+                <Stat label="Spam reports" value={report.complained} tone={report.complained > 0 ? "danger" : undefined} />
+            </StatStrip>
+
+            <p className={styles.hint}>
+                Open rates are an estimate: some mail apps open every message automatically and others block the
+                tracking. Clicks are the reliable measure. Figures arrive from Resend as people read, so they keep
+                moving for a few days.
+            </p>
+
+            <div className={styles.reportGrid}>
+                <div className={styles.card}>
+                    <h3 className={styles.cardTitle}>Clicks by link</h3>
+                    {report.links?.length ? (
+                        <table className={styles.table}>
+                            <thead>
+                                <tr>
+                                    <th>Link</th>
+                                    <th className={styles.num}>People</th>
+                                    <th className={styles.num}>Clicks</th>
+                                </tr>
+                            </thead>
+                            <tbody>
+                                {report.links.map((link) => (
+                                    <tr key={link.url}>
+                                        <td className={styles.linkCell}>
+                                            <a href={link.url} target="_blank" rel="noreferrer noopener">
+                                                {link.url}
+                                            </a>
+                                        </td>
+                                        <td className={styles.num}>{link.people}</td>
+                                        <td className={styles.num}>{link.clicks}</td>
+                                    </tr>
+                                ))}
+                            </tbody>
+                        </table>
+                    ) : (
+                        <p className={styles.quiet}>Nobody has clicked a link yet.</p>
+                    )}
+                </div>
+
+                <div className={styles.card}>
+                    <h3 className={styles.cardTitle}>Recent activity</h3>
+                    {report.activity?.length ? (
+                        <ul className={styles.activity}>
+                            {report.activity.map((event, index) => (
+                                <li key={`${event.email}-${event.at}-${index}`}>
+                                    <strong>{event.email}</strong> {ACTIVITY_WORDS[event.type] || event.type}
+                                    {event.type === 'clicked' && event.link ? (
+                                        <span className={styles.quiet}> {event.link}</span>
+                                    ) : null}
+                                    <span className={styles.activityWhen}>{formatWhen(event.at)}</span>
+                                </li>
+                            ))}
+                        </ul>
+                    ) : (
+                        <p className={styles.quiet}>Nothing yet. Activity appears here as people open and click.</p>
+                    )}
+                </div>
+            </div>
+        </section>
+    );
+};
+
+export default CampaignReport;

package/src/components/emailCampaigns/EmailCampaigns.jsx

@@ -0,0 +1,422 @@
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { ChevronRight, Mail, Plus, Trash2 } from 'lucide-react';
+import { toast } from 'react-toastify';
+
+import PageHeader from '../layout/PageHeader';
+import TabStrip from '../navigation/TabStrip';
+import StandardModal from '../generic/StandardModal';
+import { showConfirmDialog } from '../generic/ConfirmationDialog';
+import styles from '../styles/EmailCampaigns.module.scss';
+import CampaignEditor from './CampaignEditor';
+import EmailLists from './EmailLists';
+import { api, formatWhen, resolveEmailCampaignEndpoints, STATUS_LABELS } from './emailCampaignApi';
+
+/**
+ * Email campaigns: newsletters and announcements sent as Resend Broadcasts.
+ *
+ * The package module (visns-packages `email_campaigns`) owns the lists, the
+ * rendering, the sending and the numbers; this screen is the editor and the
+ * reports. Three tabs — Campaigns, Lists, Templates — and a campaign or list
+ * opens over them, with its id in the address bar (`?campaign=12`, `?list=4`)
+ * so a refresh or a shared link lands on the same thing.
+ *
+ * @param {string}  base       the module's base URI (`email_campaigns.uris.base`)
+ * @param {boolean} canManage  the `manage` permission: create, edit, send
+ * @param {string}  pageTitle
+ */
+const readParam = (key) => {
+    if (typeof window === 'undefined') return null;
+
+    return new URLSearchParams(window.location.search).get(key);
+};
+
+const writeParams = (params) => {
+    if (typeof window === 'undefined') return;
+
+    const search = new URLSearchParams(window.location.search);
+
+    Object.entries(params).forEach(([key, value]) => {
+        if (value === null || value === undefined || value === '') {
+            search.delete(key);
+        } else {
+            search.set(key, String(value));
+        }
+    });
+
+    const query = search.toString();
+    window.history.replaceState(window.history.state, '', `${window.location.pathname}${query ? `?${query}` : ''}${window.location.hash}`);
+};
+
+const EmailCampaigns = ({ base = '/ajax/email-campaigns', canManage = false, pageTitle = 'Email campaigns' }) => {
+    const routes = useMemo(() => resolveEmailCampaignEndpoints(base), [base]);
+
+    const [data, setData] = useState(null);
+    const [failed, setFailed] = useState('');
+    const [tab, setTab] = useState(() => readParam('tab') || 'campaigns');
+    const [campaignId, setCampaignId] = useState(() => Number(readParam('campaign')) || null);
+    const [listId, setListId] = useState(() => Number(readParam('list')) || null);
+    const [creating, setCreating] = useState(false);
+
+    const load = useCallback(async () => {
+        const result = await api(routes.index);
+
+        if (result.ok) {
+            setData(result.data);
+            setFailed('');
+        } else {
+            setFailed(result.message || 'Email campaigns could not be loaded.');
+        }
+    }, [routes]);
+
+    useEffect(() => {
+        load();
+    }, [load]);
+
+    // While a list is copying, check back every 15 seconds so the row moves.
+    useEffect(() => {
+        if (!data?.lists?.some((list) => list.syncing)) return undefined;
+
+        const timer = setInterval(load, 15000);
+
+        return () => clearInterval(timer);
+    }, [data, load]);
+
+    const openCampaign = (id) => {
+        setCampaignId(id || null);
+        writeParams({ campaign: id || null });
+    };
+
+    const openList = (id) => {
+        setListId(id || null);
+        writeParams({ list: id || null });
+    };
+
+    const changeTab = (key) => {
+        setTab(key);
+        writeParams({ tab: key === 'campaigns' ? null : key });
+    };
+
+    const settings = data?.settings;
+    const lists = data?.lists || [];
+    const campaign = campaignId ? data?.campaigns?.find((entry) => entry.id === campaignId) : null;
+
+    if (failed && !data) {
+        return <p className={styles.state}>{failed}</p>;
+    }
+
+    return (
+        <div className={styles.page}>
+            <PageHeader
+                align="center"
+                gutter
+                actions={
+                    canManage && !campaignId ? (
+                        <button
+                            type="button"
+                            className={styles.buttonPrimary}
+                            title="Start a new email campaign"
+                            onClick={() => setCreating(true)}
+                        >
+                            <Plus size={14} aria-hidden="true" />
+                            New campaign
+                        </button>
+                    ) : null
+                }
+            >
+                {/* The same breadcrumb shape every record page wears: the
+                    section, then the campaign that is open. */}
+                <nav aria-label="Breadcrumb">
+                    <h1 className={styles.trail}>
+                        {campaignId ? (
+                            <>
+                                <button
+                                    type="button"
+                                    className={styles.trailParent}
+                                    title="Back to all campaigns"
+                                    onClick={() => openCampaign(null)}
+                                >
+                                    {pageTitle}
+                                </button>
+                                <ChevronRight className={styles.trailChevron} strokeWidth={2} size={16} aria-hidden="true" />
+                                <span aria-current="page">{campaign?.name || 'Campaign'}</span>
+                            </>
+                        ) : (
+                            <span>{pageTitle}</span>
+                        )}
+                    </h1>
+                </nav>
+            </PageHeader>
+
+            {settings && !settings.connected && (
+                <div className={`${styles.notice} ${styles.notice_warn}`}>
+                    <p>
+                        Not connected to Resend yet: set RESEND_KEY. You can build lists and campaigns, but nothing
+                        can be copied or sent until it is.
+                    </p>
+                </div>
+            )}
+
+            {settings && settings.connected && !settings.webhook && (
+                <div className={`${styles.notice} ${styles.notice_warn}`}>
+                    <p>
+                        Resend's webhook is not set up (RESEND_WEBHOOK_SECRET), so campaigns will send but opens, clicks
+                        and unsubscribes will not be reported here.
+                    </p>
+                </div>
+            )}
+
+            {!data ? (
+                <p className={styles.state}>Loading…</p>
+            ) : campaignId ? (
+                <CampaignEditor
+                    key={campaignId}
+                    id={campaignId}
+                    routes={routes}
+                    canManage={canManage}
+                    settings={settings}
+                    lists={lists}
+                    onChanged={load}
+                    onBack={(nextId) => openCampaign(nextId || null)}
+                />
+            ) : (
+                <>
+                    <TabStrip
+                        ariaLabel="Email campaign sections"
+                        active={tab}
+                        onChange={changeTab}
+                        tabs={[
+                            { key: 'campaigns', label: 'Campaigns', badge: data.campaigns.length || undefined },
+                            { key: 'lists', label: 'Lists', badge: lists.length || undefined },
+                            { key: 'templates', label: 'Templates' },
+                        ]}
+                    />
+
+                    {tab === 'lists' ? (
+                        <EmailLists
+                            lists={lists}
+                            routes={routes}
+                            canManage={canManage}
+                            settings={settings}
+                            onChanged={load}
+                            openListId={listId}
+                            onOpenList={openList}
+                        />
+                    ) : tab === 'templates' ? (
+                        <Templates routes={routes} canManage={canManage} />
+                    ) : (
+                        <CampaignList campaigns={data.campaigns} onOpen={openCampaign} />
+                    )}
+                </>
+            )}
+
+            {creating && (
+                <NewCampaignDialog
+                    routes={routes}
+                    lists={lists}
+                    onClose={() => setCreating(false)}
+                    onCreated={(created) => {
+                        setCreating(false);
+                        load();
+                        openCampaign(created.id);
+                    }}
+                />
+            )}
+        </div>
+    );
+};
+
+const CampaignList = ({ campaigns, onOpen }) =>
+    campaigns.length === 0 ? (
+        <div className={styles.empty}>
+            <Mail size={28} aria-hidden="true" />
+            <p>No campaigns yet. Press New campaign to write the first one.</p>
+        </div>
+    ) : (
+        <table className={styles.table}>
+            <thead>
+                <tr>
+                    <th>Campaign</th>
+                    <th>Status</th>
+                    <th>List</th>
+                    <th>When</th>
+                    <th className={styles.num}>Sent to</th>
+                    <th className={styles.num}>Opened</th>
+                    <th className={styles.num}>Clicked</th>
+                </tr>
+            </thead>
+            <tbody>
+                {campaigns.map((campaign) => {
+                    const status = STATUS_LABELS[campaign.status] || { label: campaign.status, tone: 'quiet' };
+
+                    return (
+                        <tr key={campaign.id} className={styles.clickRow} onClick={() => onOpen(campaign.id)}>
+                            <td>
+                                <button type="button" className={styles.rowLink} title={`Open ${campaign.name}`}>
+                                    {campaign.name}
+                                </button>
+                                {campaign.subject && <div className={styles.quiet}>{campaign.subject}</div>}
+                            </td>
+                            <td>
+                                <span className={`${styles.pill} ${styles[`tone_${status.tone}`]}`}>{status.label}</span>
+                            </td>
+                            <td>{campaign.list?.name || '-'}</td>
+                            <td>
+                                {formatWhen(campaign.sent_at || campaign.scheduled_at) || (
+                                    <span className={styles.quiet}>Edited {formatWhen(campaign.updated_at)}</span>
+                                )}
+                            </td>
+                            <td className={styles.num}>{campaign.recipients ?? '-'}</td>
+                            <td className={styles.num}>{campaign.open_rate === null || campaign.open_rate === undefined ? '-' : `${campaign.open_rate}%`}</td>
+                            <td className={styles.num}>{campaign.click_rate === null || campaign.click_rate === undefined ? '-' : `${campaign.click_rate}%`}</td>
+                        </tr>
+                    );
+                })}
+            </tbody>
+        </table>
+    );
+
+const NewCampaignDialog = ({ routes, lists, onClose, onCreated }) => {
+    const [name, setName] = useState('');
+    const [listId, setListId] = useState('');
+    const [templates, setTemplates] = useState([]);
+    const [templateId, setTemplateId] = useState('');
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState('');
+
+    useEffect(() => {
+        api(routes.templates).then((result) => setTemplates(result.data?.templates || []));
+    }, [routes]);
+
+    const create = async () => {
+        setBusy(true);
+        const result = await api(routes.campaigns, 'POST', {
+            name: name.trim(),
+            list_id: listId ? Number(listId) : null,
+            template_id: templateId ? Number(templateId) : null,
+        });
+        setBusy(false);
+
+        if (result.ok && result.data?.campaign) {
+            onCreated(result.data.campaign);
+        } else {
+            setError(result.message || 'The campaign could not be created.');
+        }
+    };
+
+    return (
+        <StandardModal isOpen onClose={onClose} title="New campaign" size="small" showHeader>
+            <div className={styles.dialog}>
+                {error && <p className={styles.fieldError}>{error}</p>}
+                <label className={styles.field}>
+                    <span className={styles.fieldLabel}>Name</span>
+                    <input
+                        className={styles.input}
+                        value={name}
+                        maxLength={191}
+                        placeholder="September newsletter"
+                        autoFocus
+                        onChange={(event) => setName(event.target.value)}
+                    />
+                </label>
+                <label className={styles.field}>
+                    <span className={styles.fieldLabel}>Send to</span>
+                    <select className={styles.select} value={listId} onChange={(event) => setListId(event.target.value)}>
+                        <option value="">Choose later</option>
+                        {lists.map((list) => (
+                            <option key={list.id} value={list.id}>
+                                {list.name}
+                            </option>
+                        ))}
+                    </select>
+                </label>
+                <label className={styles.field}>
+                    <span className={styles.fieldLabel}>Start from</span>
+                    <select className={styles.select} value={templateId} onChange={(event) => setTemplateId(event.target.value)}>
+                        <option value="">A simple starter layout</option>
+                        {templates.map((template) => (
+                            <option key={template.id} value={template.id}>
+                                {template.name}
+                            </option>
+                        ))}
+                    </select>
+                </label>
+                <div className={styles.dialogActions}>
+                    <button type="button" className={styles.linkButton} onClick={onClose}>
+                        Cancel
+                    </button>
+                    <button type="button" className={styles.buttonPrimary} disabled={busy || name.trim() === ''} onClick={create}>
+                        Create and edit
+                    </button>
+                </div>
+            </div>
+        </StandardModal>
+    );
+};
+
+const Templates = ({ routes, canManage }) => {
+    const [templates, setTemplates] = useState(null);
+
+    const load = useCallback(() => api(routes.templates).then((result) => setTemplates(result.data?.templates || [])), [routes]);
+
+    useEffect(() => {
+        load();
+    }, [load]);
+
+    const remove = (template) =>
+        showConfirmDialog({
+            title: 'Delete this template?',
+            message: 'Campaigns already made from it are not affected.',
+            confirmLabel: 'Delete',
+            cancelLabel: 'Keep it',
+            onConfirm: async () => {
+                const result = await api(routes.template(template.id), 'DELETE');
+                result.ok ? load() : toast.error(result.message || 'It could not be deleted.');
+            },
+        });
+
+    if (templates === null) return <p className={styles.state}>Loading…</p>;
+
+    return (
+        <div className={styles.tabBody}>
+            <p className={styles.quiet}>Save any campaign's content as a template from the campaign itself, then start new ones from it.</p>
+            {templates.length === 0 ? (
+                <p className={styles.state}>No templates yet.</p>
+            ) : (
+                <table className={styles.table}>
+                    <thead>
+                        <tr>
+                            <th>Template</th>
+                            <th className={styles.num}>Blocks</th>
+                            <th>Updated</th>
+                            <th aria-label="Actions" />
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {templates.map((template) => (
+                            <tr key={template.id}>
+                                <td>{template.name}</td>
+                                <td className={styles.num}>{template.blocks}</td>
+                                <td>{formatWhen(template.updated_at)}</td>
+                                <td className={styles.num}>
+                                    {canManage && (
+                                        <button
+                                            type="button"
+                                            className={`${styles.iconAction} ${styles.iconDanger}`}
+                                            title={`Delete the ${template.name} template`}
+                                            aria-label={`Delete ${template.name}`}
+                                            onClick={() => remove(template)}
+                                        >
+                                            <Trash2 size={14} aria-hidden="true" />
+                                        </button>
+                                    )}
+                                </td>
+                            </tr>
+                        ))}
+                    </tbody>
+                </table>
+            )}
+        </div>
+    );
+};
+
+export default EmailCampaigns;