Funnel Analysis Library

A comprehensive Angular library for building funnel analysis dashboards with performance visualization and metrics analysis.

Installation

From NPM (once published)

npm install funnel-analysis-lib

Local Development (from this workspace)

# Build the library
npm run build:lib:prod

# The library will be available at dist/funnel-analysis-lib

Usage

Import Components

import { SymphiqFunnelAnalysisDashboardComponent } from 'symphiq-components';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, SymphiqFunnelAnalysisDashboardComponent],
  template: `
    <symphiq-funnel-analysis-dashboard
      [funnelAnalysis]="performanceData"
      [viewMode]="viewMode"
      [embedded]="false">
    </symphiq-funnel-analysis-dashboard>
  `
})
export class AppComponent {
  performanceData = { /* your performance data */ };
  viewMode = ViewModeEnum.LIGHT;
}

Component Inputs

| Input | Type | Default | Description | |-------|------|---------|-------------| | funnelAnalysis | FunnelAnalysisInterface | - | The funnel analysis data to display | | viewMode | ViewModeEnum | LIGHT | Theme mode (LIGHT or DARK) | | requestedByUser | UserInterface | undefined | Optional user context | | embedded | boolean | false | Enable embedded mode for use within existing page layouts | | scrollContainerId | string | undefined | ID of the external scroll container element (only used when embedded is true) |

Embedded Mode

When using the dashboard within an existing page that has its own header, toolbar, or scrolling container, set embedded="true":

@Component({
  selector: 'app-my-page',
  template: `
    <div class="my-page-header">
      <!-- Your existing header -->
    </div>
    <div id="mainContentArea" class="my-page-content" style="overflow-y: auto; height: calc(100vh - 64px);">
      <symphiq-funnel-analysis-dashboard
        [funnelAnalysis]="data"
        [embedded]="true"
        [scrollContainerId]="'mainContentArea'">
      </symphiq-funnel-analysis-dashboard>
    </div>
  `
})

Embedded mode:

• Disables the fixed scroll progress bar at the top of the viewport
• Disables the full-page animated background bubbles
• Listens to scroll events on the specified container (via scrollContainerId) instead of the internal dashboard container
• Uses absolute positioning for backgrounds instead of fixed positioning

Note: When embedded is true and you have a custom scrolling container outside the dashboard component, you should provide the scrollContainerId input with the ID of that container element. If scrollContainerId is not provided, the component will fall back to using its internal container for scroll tracking.

Ionic Framework Support

The component automatically detects and supports Ionic <ion-content> elements:

@Component({
  template: `
    <ion-content id="mainContent">
      <symphiq-funnel-analysis-dashboard
        [funnelAnalysis]="data"
        [embedded]="true"
        [scrollContainerId]="'mainContent'">
      </symphiq-funnel-analysis-dashboard>
    </ion-content>
  `
})

When an ion-content element is detected, the component will automatically call getScrollElement() to attach the scroll listener to the correct internal scrollable element within the shadow DOM.

Preview Component

The library includes a compact preview component for displaying funnel analysis summaries:

import { SymphiqFunnelAnalysisPreviewComponent } from 'symphiq-components';
import { ViewModeEnum } from 'symphiq-components';

@Component({
  selector: 'app-dashboard',
  standalone: true,
  imports: [SymphiqFunnelAnalysisPreviewComponent],
  template: `
    <symphiq-funnel-analysis-preview
      [funnelAnalysis]="performanceData"
      [viewMode]="viewMode"
      (onViewAnalysis)="handleViewFullAnalysis()">
    </symphiq-funnel-analysis-preview>
  `
})
export class DashboardComponent {
  performanceData = { /* your performance data */ };
  viewMode = ViewModeEnum.DARK;

  handleViewFullAnalysis() {
    // Navigate to full analysis view
  }
}

Preview Component Inputs

| Input | Type | Default | Description | |-------|------|---------|-------------| | funnelAnalysis | FunnelAnalysisInterface | - | The funnel analysis data to display | | viewMode | ViewModeEnum | LIGHT | Theme mode (LIGHT or DARK) |

Preview Component Outputs

| Output | Type | Description | |--------|------|-------------| | onViewAnalysis | void | Emitted when the "View Full Analysis" button is clicked |

Import Models and Interfaces

import { 
  PerformanceOverviewStructuredV3Interface,
  GradeEnum,
  MetricStatusEnum 
} from 'funnel-analysis-lib';

const assessment: PerformanceOverviewStructuredV3Interface = {
  // your data structure
};

Import Services

import { ModalService, FunnelOrderService } from 'funnel-analysis-lib';

@Injectable()
export class MyService {
  constructor(
    private modalService: ModalService,
    private funnelOrderService: FunnelOrderService
  ) {}
}

Features

• Dashboard Component: Main visualization component for funnel analysis
• Metric Cards: Individual metric display components
• Insight Cards: Actionable insights from funnel data
• Breakdown Sections: Detailed breakdowns by various dimensions (device, channel, etc.)
• Overall Assessment: Summary assessment of funnel health
• Modal Management: Built-in modal service for notifications and dialogs
• Funnel Ordering: Service for organizing and prioritizing funnel items

Styling

The library uses Tailwind CSS v4 for all styling and includes a pre-compiled stylesheet with all necessary classes, including responsive breakpoints and animations.

Required Setup

IMPORTANT: You must import the library's stylesheet in your Angular application:

Option 1: Import in angular.json (Recommended)

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "src/styles.css",
              "node_modules/@eric-emg/symphiq-components/styles.css"
            ]
          }
        }
      }
    }
  }
}

Option 2: Import in your global styles.css

/* In your src/styles.css */
@import '@eric-emg/symphiq-components/styles.css';

What's Included

The pre-compiled styles.css includes:

• ✅ All Tailwind utility classes used by the components
• ✅ All responsive breakpoints (sm, md, lg, xl, 2xl)
• ✅ All hover, focus, and active state variants
• ✅ Custom animations and keyframes
• ✅ Component-specific styles

Mobile Responsiveness

All components are fully responsive out of the box. The compiled stylesheet includes all necessary responsive classes for mobile, tablet, and desktop viewports (320px and up).

You do NOT need to:

• Configure Tailwind to scan the library files
• Add the library path to your tailwind.config.js content array
• Install Tailwind CSS in your project (unless you're using it for your own styles)

Using Tailwind 4 in Your App

If your application also uses Tailwind CSS v4, the library's styles will work seamlessly alongside your own Tailwind setup. The pre-compiled stylesheet is self-contained and won't conflict with your Tailwind configuration.

Custom Colors

The library uses a custom color palette. These colors are defined as CSS variables in the compiled stylesheet and will work automatically when you import it.

Troubleshooting

Components Not Responsive on Mobile

If components don't scale properly on mobile devices:

1. Verify stylesheet import: Ensure you've imported @eric-emg/symphiq-components/styles.css in your angular.json or global styles
2. Check viewport meta tag: Ensure your index.html has:

   <meta name="viewport" content="width=device-width, initial-scale=1">

3. Verify package version: Make sure you're using the latest version with responsive classes included
4. Clear build cache: Try deleting node_modules/.cache and rebuilding your application

Styles Not Applying

If the components render without styles:

1. Confirm the stylesheet is imported (see Required Setup above)
2. Check browser console for 404 errors loading the stylesheet
3. Verify the package is installed: npm list @eric-emg/symphiq-components
4. Try clearing your browser cache and rebuilding

Building the Library

# Build for production
npm run build:lib:prod

# Build for development
npm run build:lib

# Build everything (library + demo)
npm run build:all

Testing

# Run library tests
ng test funnel-analysis-lib

# Run library tests with watch mode
ng test funnel-analysis-lib --watch

Development

To develop and test the library:

1. Start the demo application which imports the library:

npm start

2. The demo app will hot-reload when you make changes to both the library and demo app

Publishing to NPM

1. Update the version in projects/funnel-analysis-lib/package.json
2. Build the library:

npm run build:lib:prod

3. Publish from the dist folder:

cd dist/funnel-analysis-lib
npm publish

License

MIT