FluentSMTP

The FluentSMTP UI/UX redesign aims to bring the WordPress admin interface into alignment with the shared Fluent design system (used by FluentCart and FluentAuth).

Key Changes:

• Tech Stack Upgrade: Migrating from Vue 2 + Element UI 2 + Laravel Mix to Vue 3 + Element Plus + Tailwind 3 + Vite.
• Design System: Implementing shared tokens for colors, spacing, radii, and fonts to ensure visual consistency across Fluent products.
• Information Architecture: Moving from a legacy layout to a fixed top app bar for destinations, with all configuration moved behind a Settings sidebar.
• Theme Support: Native support for both light and dark modes using CSS variables.

Important Constraints:

• No API Changes: The request layer remains on admin-ajax.php using window.FluentMail.$get/$post. Endpoint names, payloads, and nonces are preserved.
• No Feature Changes: The redesign focuses on skin and IA, not new capabilities.
• Menu Location: The plugin remains at Settings → FluentSMTP (options-general.php?page=fluent-mail).

The redesigned FluentSMTP UI moves from a flat horizontal menu to a top bar with a settings sidebar.

Top Bar Destinations:

• Dashboard
• Email Logs
• Settings

Top Bar Actions (Right-hand):

• Send Test Email: Primary action button.
• Documentation: Link to /documentation.
• Theme Switch: Dark/Light mode toggle.

Settings Sidebar (260px): All configuration items are grouped in the sidebar. Crucially, path values must remain unchanged to prevent breaking external links (e.g., Slack OAuth flows).

Implementation Note: Set meta.active on each route so the top bar can highlight the 'Settings' destination while any child route in the sidebar is active.

FluentSMTP uses the --fsm- prefix for semantic CSS variables. Create resources/admin/styles/_theme.scss to define two-value (light/dark) structures for all UI chrome.

Variable Groups:

• Surfaces: --fsm-body-bg, --fsm-surface, --fsm-surface-sunk, --fsm-surface-raised
• Borders: --fsm-border, --fsm-border-strong
• Text: --fsm-heading, --fsm-text, --fsm-text-mid, --fsm-text-light, --fsm-link
• Accent: --fsm-accent, --fsm-accent-contrast, --fsm-accent-wash
• Shadows: --fsm-card-line, --fsm-shadow-card, --fsm-shadow-lift, --fsm-shadow-pop
• Status: --fsm-{danger,warning,success}-{wash,bg,line,fg}, --fsm-neutral-{bg,fg}

Scoping: To ensure Element Plus components (which teleport to <body>) inherit these styles, scope the selectors to the <body> tag using the specific WordPress settings page class:

body.settings_page_fluent-mail { /* light tokens */ }

.fluent_theme_dark body.settings_page_fluent-mail, 
body.settings_page_fluent-mail.fluent_theme_dark { /* dark tokens */ }

/* Example semantic variable structure */
body.settings_page_fluent-mail {
  --fsm-body-bg: #F3F5FA;
  --fsm-surface: #FFFFFF;
  /* ... */
}

.fluent_theme_dark body.settings_page_fluent-mail {
  --fsm-body-bg: #11171D;
  --fsm-surface: #1C2732;
  /* ... */
}

The FluentSMTP admin interface has undergone a major architectural shift from Vue 2/Element UI to Vue 3/Element Plus.

Key architectural decisions include:

• Options API: The project uses the Vue 3 Options API throughout instead of <script setup> or the Composition API. This was done to maintain compatibility with existing mixins and helpers (like $get, $post, $t, and ucFirst) that are attached to the component instance.
• Global Helpers: Helpers are provided via an app.mixin lever, ensuring that component script blocks do not need to change how they access core functionality.
• Asset Loading: The build process uses two separate Vite builds (boot and app) to handle different script requirements (e.g., plain <script> tags for the admin menu vs. modern modules for the app).
• Styling: The design system uses a tokenized approach with Tailwind CSS and PostCSS. Component styles are extracted into a single stylesheet to ensure proper loading order and CSS cascade behavior.

The redesign replaces legacy Element UI patterns with a new design system based on tokens and specific layout patterns.

Dashboard

• Layout: Uses a minmax(0,1fr) 380px grid.
• Stats: Headline numbers (Sent, Failed, Active Connections, Active Senders) must use stat tiles with the --fsm-tile-* token ramp.
• Quick Overview: Uses .fsm_aside_block (dashed-rule separated subjects) instead of floated lists.

Email Logs

• Status Display: Replace full-row background tinting (e.g., .row_type_failed) with the .fls_tag pattern (one-word status chips: is_success, is_failed, is_blocked, or is_neutral).
• Table Style: Drop border from el-table; the table should sit flush inside its card container.

Connections

• Layout: Use the card + flush-table pattern.
• Icons: Replace size="mini" icon buttons with Element Plus icon components at size="small".
• Header: Replace inline-styled float headers with .fsm_card_head.

Connection Wizard

• Provider Picker: Replace hardcoded SCSS color overrides (e.g., .con_gmail) with a single token-based selected state rule.
• Provider Partials: Convert el-form-item stacks to use the .fsm_row pattern (label + description on the left, control pinned to the right).

The Vite configuration should use vite-plugin-static-copy to move images and libraries into the assets directory and utilize unplugin-vue-components and unplugin-auto-import with ElementPlusResolver to handle Element Plus components automatically.

Note: For imperative components like el-notification, el-loading, or el-message-box, you must still import their CSS manually in your app.scss.

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { viteStaticCopy } from 'vite-plugin-static-copy';
import path from 'path';

export default defineConfig({
    base: '',
    plugins: [
        vue(),
        viteStaticCopy({
            targets: [
                { src: 'resources/images', dest: '' },
                { src: 'resources/libs',   dest: '' },
            ]
        }),
    ],
    css: { preprocessorOptions: { scss: { api: 'modern' } } },
    resolve: { alias: { '@': path.resolve(__dirname, 'resources/admin') } },
    // ... build config
});

To maintain compatibility with existing PHP enqueue handlers (fluentMailMix()) and asset URLs, the Vite build must reproduce the exact output file paths used by the previous Laravel Mix setup.

Required Output Paths:

• assets/admin/js/boot.js
• assets/admin/js/fluent-mail-admin-app.js
• assets/admin/css/fluent-mail-admin.css
• assets/images/... (copied from resources/images)
• assets/libs/... (copied from resources/libs)

Key Constraints:

• Do not use dynamic imports: Avoid code splitting to prevent the need for a manifest-to-PHP bridge. The app should be a single bundle.
• Asset Naming: Use rollupOptions.output to ensure entryFileNames and assetFileNames do not include hashes, preserving the hard-coded PHP paths.

// vite.config.mjs snippet for path preservation
export default defineConfig({
    build: {
        outDir: 'assets',
        emptyOutDir: true,
        manifest: false,
        cssCodeSplit: false,
        rollupOptions: {
            input: {
                'admin/js/boot': 'resources/admin/boot.js',
                'admin/js/fluent-mail-admin-app': 'resources/admin/start.js',
                'admin/css/fluent-mail-admin': 'resources/scss/fluent-mail-admin.scss',
            },
            output: {
                entryFileNames: '[name].js',
                assetFileNames: '[name][extname]',
                chunkFileNames: 'admin/js/chunks/[name].js',
            },
        },
    },
});

New shell components must be placed under resources/admin/. Do not move this directory to src/, as the build.sh script is configured to exclude resources/* from the final zip package.

resources/admin/
  App.vue                     # Rewrite of Application.vue (app bar + nav + theme switch)
  Bits/ThemeSwitch.vue       # Copied from fluent-security
  Bits/icons.js               # Curated @element-plus/icons-vue re-exports
  styles/
    _theme.scss              # Light + dark token declarations
    _layout.scss             # App bar, settings shell, cards, rows, tags
    tokens/
      color.js
      spacing.js
      borderRadius.js
      fontSize.js

resources/admin/
  App.vue                     ← rewrite of Application.vue: app bar + nav + theme switch
  Bits/ThemeSwitch.vue       ← copied from fluent-security
  Bits/icons.js               ← curated @element-plus/icons-vue re-exports
  styles/
    _theme.scss               ← light + dark token declarations
    _layout.scss              ← app bar, settings shell, cards, rows, tags
    tokens/{color,spacing,borderRadius,fontSize}.js