Skip to content

TypeScript Modules

This page documents the modular TypeScript architecture of the Phenix Design System, providing details on the available modules and how to use them.

Module Organization

The Phenix Design System's TypeScript codebase is organized into a modular structure that promotes maintainability and scalability. The code is organized into four primary module categories:

  1. Core - Base functionality in index.ts
  2. Components - UI component implementations
  3. Features - Utility features and effects
  4. Integration - Third-party system integrations

Core Module (index.ts)

The core module defines the main Phenix() function and the PhenixElements class, which provide the foundation for DOM manipulation, event handling, and element traversal.

Main Structure

typescript
// Core class definition
export class PhenixElements extends Array<HTMLElement | Record<string, any>> {
    // DOM-ready method
    ready(callback: () => void): this { /* ... */ }
    
    // Class manipulation
    addClass(className: any) { /* ... */ }
    removeClass(className: string) { /* ... */ }
    toggleClass(className: string) { /* ... */ }
    
    // DOM traversal
    ancestor(target?) { /* ... */ }
    siblings(target?) { /* ... */ }
    next(target?, all_target?) { /* ... */ }
    prev(target?, all_target?) { /* ... */ }
    child(target?:string) { /* ... */ }
    
    // Styling and attributes
    css(style:object, clearInline?) { /* ... */ }
    setAttributes(attributes:{}) { /* ... */ }
    
    // DOM manipulation
    insert(position?:string, elementsPackage?:any) { /* ... */ }
    
    // Event handling
    on(event, callback, live?, timer?) { /* ... */ }
}

// Main Phenix function
const Phenix = (selector?:any) => {
    // Implementation details
    return new PhenixElements(...elements);
};

Core Methods

The core module provides fundamental DOM manipulation methods:

MethodPurposeExample
ready()Execute code when DOM is readyPhenix(document).ready(() => { /* code */ })
addClass()Add CSS classesPhenix('.element').addClass('active')
removeClass()Remove CSS classesPhenix('.element').removeClass('hidden')
toggleClass()Toggle CSS classesPhenix('.element').toggleClass('active')
ancestor()Get parent elementsPhenix('.child').ancestor('.parent')
siblings()Get sibling elementsPhenix('.item').siblings()
next()Get next siblingPhenix('.item').next()
prev()Get previous siblingPhenix('.item').prev()
css()Set CSS stylesPhenix('.element').css({color: 'red'})
setAttributes()Set HTML attributesPhenix('.element').setAttributes({id: 'main'})
on()Add event listenersPhenix('.button').on('click', function() {})

Component Modules

The components directory contains UI component implementations. Each component is defined as a method on the Phenix.prototype and typically follows a similar pattern of initialization and event handling.

Available Components

ComponentFileDescription
Tabscomponents/tabs.tsTabbed content navigation
Popupcomponents/popup.tsModal popup windows
Mediacomponents/media.tsMedia handling utilities
Timercomponents/timer.tsCountdown timers
Progresscomponents/progress.tsProgress indicators
Menucomponents/menu.tsNavigation menus
Ratingcomponents/rating.tsStar rating interface
DataTablecomponents/datatable.tsEnhanced data tables
Dropdowncomponents/dropdown.tsDropdown menus
Selectcomponents/select.tsEnhanced select inputs
Uploadercomponents/uploader.tsFile upload component

Component Usage Pattern

Most components follow this usage pattern:

typescript
// Initialize a component
Phenix('.element-selector').componentName({
    // Optional configuration options
    option1: 'value1',
    option2: 'value2'
});

Example: Dropdown Component

The dropdown component provides enhanced dropdown functionality:

typescript
// Initialize a dropdown
Phenix('.dropdown-toggle').dropdown({
    // Optional configuration
    animation: "fade",        // Animation type: fade, scale, slide
    duration: 300,            // Animation duration in ms
    placement: "bottom-start" // Dropdown position
});

// Method defined in components/dropdown.ts
PhenixElements.prototype.dropdown = function (options?:{
    toggle?:string,   //====> Toggle Button Class Name : px-toggle
    target?:string,   //====> Target to Toggle (add/remove) Active Class
    active?:string,   //====> Active Class Name : px-active
    hover?:boolean,   //====> Support on Hover Show/Hide
    exclude?:string,  //====> Exclude from on Blank Click only [CSS :not()... Selector]
    position?:string, //====> the position of the target [top or bottom, start or end]
    //====> Hide/Show Toggle Effect [fade, slide] <====//
    effect?:{
        type?:string,
        duration?:number,
        delay?:number,
        display?:string,
    },
}) {
    // Implementation
    return this.forEach((element) => {
        // Component logic...
    });
};

Example: Tabs Component

The tabs component provides tabbed content navigation:

typescript
// Initialize tabs
Phenix('.tabs-element').tabs({
    active: 0,       // Show Tab # on Initial
    navigation: '.tabs-navigation',  // Navigation Selector
    hash_url: true    // Show Tab from URL #ID
});

// Method defined in components/tabs.ts
PhenixElements.prototype.tabs = function (options?:{
    active?:number,     //===> Show Tab # on Initial
    navigation?:string, //===> Navigation Selector
    hash_url?:boolean,  //===> Show Tab from URL #ID
}) {
    // Implementation
    return this;
}

Feature Modules

Feature modules provide utilities and effects that can be used with any element. These are implemented as methods on the Phenix.prototype.

Available Features

FeatureFileDescription
Animationsfeatures/animations.tsElement animations triggered by viewport
Effectsfeatures/effects.tsUI effects like fade and slide
Scroll Effectsfeatures/effects-scroll.tsScroll-based effects
Form Validationfeatures/validation.tsForm input validation rules
Collapsefeatures/collapse.tsCollapsible content sections
Counterfeatures/counter.tsAnimated number counters
Notificationsfeatures/notifications.tsToast notification system
Viewportfeatures/viewport.tsViewport detection utilities
Get Infofeatures/get-info.tsElement information utilities
Connectfeatures/connect.tsAJAX and data connection utilities

Example: Animations Feature

The animations feature adds CSS-based animations that trigger when elements enter the viewport:

typescript
// Add viewport-based animations
Phenix('.animate-element').animations({
    animation: 'fadeIn',     // Animation class name
    duration: 700,           // Animation duration in ms
    delay: 0,                // Delay before animation starts (ms)
    offset: 0,               // Decrease target position by [number]
    into: 0,                 // Increase target position by [number]
    exit: 'fadeOut',         // Exit animation class name
    animateCSS: 'all'        // Load animation CSS (all, specific, or array)
});

Example: Effects Feature

The effects feature provides methods for common UI transitions:

typescript
// Use fade effects
Phenix('.element').fadeIn(300, 0, 'block');  // duration, delay, display
Phenix('.element').fadeOut(300, 0);          // duration, delay
Phenix('.element').fadeToggle(300, 0, 'block'); // duration, delay, display

// Use slide effects
Phenix('.element').slideDown(300, 0, 'block');  // duration, delay, display
Phenix('.element').slideUp(300, 0);             // duration, delay
Phenix('.element').slideToggle(300, 0, 'block'); // duration, delay, display

Integration Modules

Integration modules provide compatibility with third-party systems and libraries. These modules adapt Phenix features to work with specific platforms like WordPress or enhance functionality with libraries like Splide Slider.

Available Integrations

IntegrationFileDescription
WordPressintegration/wordpress.tsWordPress-specific functionality
Blocksintegration/blocks.tsGutenberg blocks front-end scripts
WooCommerceintegration/woocommerce.tsWooCommerce integration
Sliderintegration/slider.tsSplide slider integration

| Utilities | integration/utilities.ts | General utility integrations | | Loader | integration/loader.ts | Page loading system |

Example: WordPress Integration

The WordPress integration module adds WordPress-specific functionality:

typescript
// In integration/wordpress.ts
Phenix(document).ready(() => {
    // WordPress-specific initializations
    
    // Handle WordPress admin bar
    const adminBar = document.getElementById('wpadminbar');
    if (adminBar) {
        document.body.style.paddingTop = adminBar.offsetHeight + 'px';
    }
    
    // Initialize other WordPress-specific features
});

Example: Slider Integration

The slider integration provides a wrapper for the Splide slider library:

typescript
// Initialize a slider
Phenix('.slider-element').slider({
    type: 'loop',        // Slider type: loop, slide, fade
    items: 3,            // Slides per page
    autoplay: true,      // Enable autoplay
    duration: 6000,      // Autoplay interval (ms)
    speed: 700           // Transition speed (ms)
});

// Method defined in integration/slider.ts
PhenixElements.prototype.slider = function (options?:{
    type?:string;
    focus?:any;
    items?:number;
    steps?:number;
    speed?:number;
    start?:number;
    duration?:number;
    autoplay?:boolean;
    controls?:any;
    pagination?:any;
    // Additional options...
}) {
    // Implementation
    return this;
}

Extending Phenix with Custom Modules

You can extend Phenix with your own modules by adding methods to the Phenix.prototype.

Creating a Custom Component

typescript
// Define a custom component
Phenix.prototype.myComponent = function(options = {}) {
    // Default options
    const defaults = {
        option1: 'default',
        option2: true
    };
    
    // Merge options
    const settings = Object.assign({}, defaults, options);
    
    // Return this for chaining
    return this.forEach((element) => {
        // Component implementation logic
        element.classList.add('my-component');
        
        // Add event listeners
        element.addEventListener('click', function() {
            // Handle events
        });
    });
};

// Use your custom component
Phenix('.my-elements').myComponent({
    option1: 'custom',
    option2: false
});

Custom Module Best Practices

  1. Follow the Pattern: Use the same method signature and return pattern as existing modules
  2. Return this: Always return this for method chaining
  3. Use forEach: Process each element individually with this.forEach()
  4. Default Options: Provide sensible defaults and merge with user options
  5. Cleanup: Include cleanup logic to prevent memory leaks

Released under the MIT License.