PHPFlasher Theme System

Overview

The PHPFlasher theme system allows for consistent, customizable notification designs across your application. Themes define both the visual appearance (using CSS/SCSS) and the HTML structure (using template functions) of notifications.

Core Concepts

Theme Structure

Each theme consists of:

1. SCSS file: Defines the styling for the notification
2. TypeScript file: Contains the render function that generates HTML
3. Index file: Registers the theme with PHPFlasher

Theme Registration

Themes are registered using the addTheme method:

flasher.addTheme('themeName', myTheme);

Using Themes

Themes can be used in two ways:

1. Direct Usage: Using the theme as a plugin

   flasher.use('theme.material').success('Operation completed');
   

2. Default Theme: Setting a theme as the default

   // Make material theme the default
   const defaultTheme = 'theme.material';
   flasher.defaultPlugin = defaultTheme;
   

Theme Components

CSS Variables

PHPFlasher uses CSS variables to maintain consistent styling across themes. The main variables are:

:root {
  /* State Colors */
  --fl-success: #10b981;
  --fl-info: #3b82f6;
  --fl-warning: #f59e0b;
  --fl-error: #ef4444;

  /* Base colors */
  --fl-bg-light: #ffffff;
  --fl-bg-dark: rgb(15, 23, 42);
  --fl-text-light: rgb(75, 85, 99);
  --fl-text-dark: #ffffff;

  /* Appearance */
  --fl-font: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
  --fl-border-radius: 4px;
  --fl-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

Layout Components

1. Wrapper (fl-wrapper): Controls positioning and stacking of notifications
2. Container (fl-container): Base for individual notifications
3. Progress Bar (fl-progress-bar): Shows time remaining before auto-dismiss
4. Icons: Type-specific icons for visual recognition

SASS Mixins

PHPFlasher provides several mixins to help with theme creation:

1. variants: Apply styles to each notification type

   @include variants using($type) {
     background-color: var(--#{$type}-color);
   }
   

2. close-button: Standard close button styling

   @include close-button;
   

3. rtl-support: Right-to-left language support

   @include rtl-support;
   

4. progress-bar: Add a progress bar with type-specific colors

   @include progress-bar(0.125em);
   

5. dark-mode: Dark mode styling support

   @include dark-mode {
     background-color: var(--fl-bg-dark);
     color: var(--fl-text-dark);
   }
   

Creating Custom Themes

Basic Theme Structure

// my-theme.ts
import './my-theme.scss'
import type { Envelope } from '@flasher/flasher/dist/types'

export const myTheme = {
  render: (envelope: Envelope): string => {
    const { type, title, message } = envelope
    
    return `
      <div class="fl-my-theme fl-${type}">
        <div class="fl-content">
          <strong>${title || type}</strong>
          <p>${message}</p>
          <button class="fl-close">&times;</button>
        </div>
        <div class="fl-progress-bar">
          <div class="fl-progress"></div>
        </div>
      </div>
    `
  },
  
  // Optional: CSS stylesheets to load
  styles: ['path/to/additional-styles.css']
}

SCSS Template

// my-theme.scss
@use '../mixins' as *;

.fl-my-theme {
  padding: 1rem;
  background-color: white;
  border-radius: 4px;
  box-shadow: var(--fl-shadow);
  
  .fl-content {
    display: flex;
    align-items: center;
  }
  
  // Use built-in mixins for common functionality
  @include close-button;
  @include rtl-support;
  @include progress-bar;
  
  // Type-specific styling
  @include variants using($type) {
    border-left: 3px solid var(--#{$type}-color);
  }
  
  // Dark mode support
  @include dark-mode {
    background-color: var(--fl-bg-dark);
    color: var(--fl-text-dark);
  }
}

Theme Registration

// Register your custom theme
import { myTheme } from './my-theme';
flasher.addTheme('custom', myTheme);

// Use your theme
flasher.use('theme.custom').success('This uses my custom theme!');

Included Themes

PHPFlasher comes with several built-in themes:

• flasher: Default bordered notification with colored accents (default)
• material: Google Material Design inspired notifications
• bootstrap: Bootstrap-styled notifications
• tailwind: Tailwind CSS styled notifications
• And many more…

Accessibility Features

PHPFlasher themes include several accessibility features:

1. ARIA roles: Appropriate roles (alert or status) based on type
2. ARIA live regions: Assertive for critical messages, polite for others
3. Reduced motion: Respects user preferences for reduced animations
4. RTL support: Right-to-left language direction support
5. Keyboard interaction: Close buttons are keyboard accessible

Best Practices

1. Use semantic HTML in your theme’s render function
2. Leverage CSS variables for consistent styling
3. Include proper ARIA attributes for accessibility
4. Use the provided mixins to ensure consistent behavior
5. Test in both light and dark modes using the dark mode mixin