Advanced Features

/**
 * Create layered icon compositions with multiple elements
 * @param assembler Function that receives a callback to add layer elements
 * @param params Optional styling parameters for the layer container
 * @returns Layer object with combined visual elements
 */
function layer(
  assembler: (addLayerCallback: (layerToAdd: Icon | Text | Icon[] | Text[]) => void) => void,
  params?: LayerParams
): Layer;

interface LayerParams {
  /** CSS classes to apply to the layer container */
  classes?: string | string[];
}

interface Layer extends FontawesomeObject {
  readonly type: "layer";
}

import { layer, icon, text, library } from "@fortawesome/fontawesome-svg-core";
import { faCircle, faHome, faUser } from "@fortawesome/free-solid-svg-icons";

library.add(faCircle, faHome, faUser);

// Create a layered icon with background circle
const layeredIcon = layer((add) => {
  add(icon({ prefix: 'fas', iconName: 'circle' }, {
    classes: ['text-blue-500'],
    transform: { size: 2 }
  }));
  
  add(icon({ prefix: 'fas', iconName: 'home' }, {
    classes: ['text-white'],
    transform: { size: 0.8 }
  }));
});

// Render the layer
document.body.innerHTML = layeredIcon.html[0];

// Icon with text label
const iconWithLabel = layer((add) => {
  // Background circle
  add(icon('circle', {
    classes: ['text-gray-200'],
    transform: { size: 3 }
  }));
  
  // Main icon
  add(icon('user', {
    classes: ['text-blue-600'],
    transform: { size: 1.2 }
  }));
  
  // Text label
  add(text('Admin', {
    classes: ['text-xs', 'font-bold'],
    transform: { y: 25 }
  }));
}, {
  classes: ['inline-block', 'text-center']
});

/**
 * Create styled text elements that integrate with Font Awesome layouts
 * @param content Text content to render
 * @param params Optional styling and transformation parameters
 * @returns Text object with FontAwesome styling
 */
function text(content: string, params?: TextParams): Text;

interface TextParams extends Params {
  /** Transform operations for positioning and sizing */
  transform?: Transform;
}

interface Text extends FontawesomeObject {
  readonly type: "text";
}

import { text } from "@fortawesome/fontawesome-svg-core";

// Basic text with styling
const styledText = text('Hello World', {
  classes: ['text-lg', 'font-bold', 'text-blue-600'],
  attributes: { 'data-text': 'greeting' }
});

// Text with transformation
const transformedText = text('Rotated Text', {
  transform: {
    rotate: 45,
    size: 1.5,
    y: -10
  },
  classes: ['text-red-500']
});

// Combine text with icons in layers
const textWithIcon = layer((add) => {
  add(icon('star', {
    classes: ['text-yellow-400'],
    transform: { size: 2 }
  }));
  
  add(text('5.0', {
    classes: ['text-white', 'font-bold', 'text-sm'],
    transform: { y: 2 }
  }));
});

/**
 * Create counter/badge elements with automatic number formatting
 * @param content Numeric content (string or number)
 * @param params Optional styling parameters
 * @returns Counter object styled as a badge
 */
function counter(content: string | number, params?: CounterParams): Counter;

interface CounterParams extends Params {
  // Inherits title, titleId, classes, attributes, styles from Params
}

interface Counter extends FontawesomeObject {
  readonly type: "counter";
}

import { counter, icon, layer } from "@fortawesome/fontawesome-svg-core";

// Basic counter
const simpleCounter = counter('5', {
  classes: ['bg-red-500', 'text-white', 'rounded-full', 'text-xs']
});

// Counter with icon
const notificationBadge = layer((add) => {
  add(icon('bell', {
    classes: ['text-gray-600'],
    transform: { size: 1.5 }
  }));
  
  add(counter(12, {
    classes: ['absolute', 'top-0', 'right-0', 'bg-red-500', 'text-white', 'rounded-full', 'text-xs', 'px-1'],
    transform: { x: 8, y: -8 }
  }));
});

// Counters automatically handle large numbers
const largeCounter = counter(1234, {
  classes: ['bg-blue-500', 'text-white', 'px-2', 'py-1', 'rounded']
});

// Counter with custom formatting
const formattedCounter = counter('99+', {
  classes: ['bg-green-500', 'text-white', 'rounded-full', 'text-xs']
});

/**
 * Transform interface for advanced icon modifications
 */
interface Transform {
  /** Scale factor (1.0 = normal size, 2.0 = double size) */
  size?: number;
  /** Horizontal offset in icon coordinate units */
  x?: number;
  /** Vertical offset in icon coordinate units */
  y?: number;
  /** Rotation angle in degrees (0-360) */
  rotate?: number;
  /** Flip horizontally */
  flipX?: boolean;
  /** Flip vertically */
  flipY?: boolean;
}

// Multi-step transformation
const complexIcon = icon('arrow-right', {
  transform: {
    size: 1.5,    // 50% larger
    rotate: 45,   // 45 degree rotation
    x: 10,        // 10 units right
    y: -5,        // 5 units up
    flipX: false,
    flipY: false
  },
  classes: ['text-blue-500']
});

// Animation-ready transforms
const spinningIcon = icon('spinner', {
  transform: { rotate: 0 }, // Will be animated via CSS
  classes: ['animate-spin']
});

// Precisely positioned layer elements
const preciseLayer = layer((add) => {
  // Background
  add(icon('square', {
    classes: ['text-gray-200'],
    transform: { size: 2 }
  }));
  
  // Top-left icon
  add(icon('home', {
    classes: ['text-blue-500'],
    transform: { size: 0.6, x: -8, y: -8 }
  }));
  
  // Top-right icon
  add(icon('user', {
    classes: ['text-green-500'],
    transform: { size: 0.6, x: 8, y: -8 }
  }));
  
  // Center text
  add(text('APP', {
    classes: ['text-white', 'font-bold', 'text-xs'],
    transform: { y: 5 }
  }));
});

/**
 * Parse utilities for icon and transform specifications
 */
const parse: {
  /** Parse transform strings into Transform objects */
  transform(transformString: string): Transform;
  /** Parse icon strings into IconLookup objects */
  icon(parseIconString: string | { prefix: IconPrefix, iconName: IconName } | [string | IconPrefix, string | IconName]): IconLookup;
};

import { parse } from "@fortawesome/fontawesome-svg-core";

// Parse CSS-like transform strings
const transform1 = parse.transform("rotate-90 grow-2 left-4 up-3");
// Results in: { rotate: 90, size: 2, x: -4, y: -3 }

const transform2 = parse.transform("flip-h flip-v shrink-6");
// Results in: { flipX: true, flipY: true, size: 0.25 }

// Use parsed transform
const transformedIcon = icon('home', { transform: transform1 });

// Parse various icon specification formats
const icon1 = parse.icon("fas fa-home");
// Results in: { prefix: 'fas', iconName: 'home' }

const icon2 = parse.icon(["fas", "user"]);
// Results in: { prefix: 'fas', iconName: 'user' }

const icon3 = parse.icon({ prefix: 'fab', iconName: 'github' });
// Results in: { prefix: 'fab', iconName: 'github' }

/**
 * Convert FontAwesome objects to HTML strings
 * @param content FontAwesome object or abstract element
 * @returns HTML string representation
 */
function toHtml(content: any): string;
function toHtml(abstractNodes: AbstractElement): string;

import { toHtml, icon, layer, text } from "@fortawesome/fontawesome-svg-core";

// Convert icon to HTML
const homeIcon = icon('home');
const htmlString = toHtml(homeIcon);

// Convert layer to HTML
const complexLayer = layer((add) => {
  add(icon('circle', { classes: ['text-blue-500'] }));
  add(text('Click Me', { classes: ['text-white'] }));
});
const layerHtml = toHtml(complexLayer);

// Use in templates or server-side rendering
document.getElementById('icon-container').innerHTML = htmlString;

function createNotification(iconName: IconName, count: number, message: string) {
  return layer((add) => {
    // Icon background
    add(icon('circle', {
      classes: ['text-blue-100'],
      transform: { size: 3 }
    }));
    
    // Main icon
    add(icon(iconName, {
      classes: ['text-blue-600'],
      transform: { size: 1.2 }
    }));
    
    // Count badge
    if (count > 0) {
      add(counter(count, {
        classes: ['absolute', 'top-0', 'right-0', 'bg-red-500', 'text-white', 'rounded-full', 'text-xs'],
        transform: { x: 12, y: -12 }
      }));
    }
    
    // Message text
    add(text(message, {
      classes: ['text-sm', 'text-gray-700'],
      transform: { y: 35 }
    }));
  }, {
    classes: ['relative', 'inline-block', 'text-center']
  });
}

// Usage
const emailNotification = createNotification('envelope', 3, 'New Messages');

function createStatusIndicator(status: 'online' | 'offline' | 'busy') {
  const statusConfig = {
    online: { color: 'text-green-500', icon: 'circle' },
    offline: { color: 'text-gray-400', icon: 'circle' },
    busy: { color: 'text-red-500', icon: 'minus-circle' }
  };
  
  const config = statusConfig[status];
  
  return layer((add) => {
    add(icon('user', {
      classes: ['text-gray-600'],
      transform: { size: 2 }
    }));
    
    add(icon(config.icon, {
      classes: [config.color],
      transform: { size: 0.5, x: 8, y: 8 }
    }));
  });
}

function createInteractiveButton(iconName: IconName, label: string, isActive: boolean) {
  return layer((add) => {
    // Button background
    add(icon('square', {
      classes: [isActive ? 'text-blue-500' : 'text-gray-300'],
      transform: { size: 3 }
    }));
    
    // Button icon
    add(icon(iconName, {
      classes: [isActive ? 'text-white' : 'text-gray-600'],
      transform: { size: 1.2 }
    }));
    
    // Button label
    add(text(label, {
      classes: ['text-sm', isActive ? 'text-blue-600' : 'text-gray-500'],
      transform: { y: 30 }
    }));
  }, {
    classes: ['cursor-pointer', 'hover:opacity-80', 'transition-opacity']
  });
}