Icon Rendering

/**
 * Renders an icon to a FontAwesome object with HTML, abstract, and node representations
 * @param icon - Icon name string or icon lookup object
 * @param params - Optional styling and transformation parameters
 * @returns Icon object with multiple output formats
 */
function icon(icon: IconName | IconLookup, params?: IconParams): Icon;

interface IconParams {
  /** Accessible title for the icon */
  title?: string;
  /** ID for the title element */
  titleId?: string;
  /** CSS class names to add to the icon */
  classes?: string | string[];
  /** HTML attributes to add to the SVG element */
  attributes?: { [key: string]: number | string };
  /** CSS styles to apply to the icon */
  styles?: { [key: string]: string };
  /** Transform operations (scale, translate, rotate, flip) */
  transform?: Transform;
  /** Symbol ID for reusable icon definitions */
  symbol?: string | boolean;
  /** Icon to use as a mask over this icon */
  mask?: IconLookup;
  /** ID for the mask element */
  maskId?: string;
}

interface Icon extends FontawesomeObject, IconDefinition {
  readonly type: "icon";
}

interface FontawesomeObject {
  /** Abstract DOM representation for framework integration */
  readonly abstract: AbstractElement[];
  /** HTML string representations ready for insertion */
  readonly html: string[];
  /** HTMLCollection of DOM nodes */
  readonly node: HTMLCollection;
}

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

// Add icons to library first
library.add(faHome, faUser, faHeart);

// Basic icon rendering
const homeIcon = icon('home');
const userIcon = icon({ prefix: 'fas', iconName: 'user' });

// Render with custom classes and title
const styledIcon = icon('heart', {
  title: 'Favorite',
  classes: ['text-red-500', 'hover:text-red-700'],
  attributes: { 'data-testid': 'heart-icon' }
});

// Use the rendered icon
document.body.innerHTML = homeIcon.html[0];

// Access abstract representation for framework integration
console.log(homeIcon.abstract);
// [{ tag: 'svg', attributes: {...}, children: [...] }]

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

// Scaled and rotated icon
const largeRotatedIcon = icon('home', {
  transform: {
    size: 2.0,      // 2x larger
    rotate: 45,     // 45 degrees
    x: 10,          // 10 units right
    y: -5           // 5 units up
  }
});

// Flipped icon
const flippedIcon = icon('arrow-right', {
  transform: {
    flipX: true,    // Horizontally flipped
    flipY: false
  }
});

// Mask parameter in IconParams
interface IconParams {
  /** Icon to use as a mask over this icon */
  mask?: IconLookup;
  /** ID for the mask element */
  maskId?: string;
}

// Icon with circular mask
const maskedIcon = icon('user', {
  mask: { prefix: 'fas', iconName: 'circle' },
  classes: ['text-blue-500']
});

// Custom mask with ID
const customMaskedIcon = icon('heart', {
  mask: { prefix: 'fas', iconName: 'square' },
  maskId: 'heart-square-mask'
});

// Symbol parameter in IconParams  
interface IconParams {
  /** Symbol ID for reusable icon definitions */
  symbol?: string | boolean;
}

// Create a symbol definition
const symbolIcon = icon('home', {
  symbol: 'home-symbol',
  classes: ['icon-base']
});

// Boolean symbol generates automatic ID
const autoSymbolIcon = icon('user', {
  symbol: true
});

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

const homeIcon = icon('home');

// Get HTML string
const htmlString = toHtml(homeIcon);
// '<svg class="svg-inline--fa fa-home" ...></svg>'

// Direct from icon object  
const directHtml = homeIcon.html[0];

// Both methods produce the same result
console.log(htmlString === directHtml); // true

/**
 * Union type for different ways to specify icons
 */
type IconProp = IconName | [IconPrefix, IconName] | IconLookup;

// Size specifications for consistent scaling
type SizeProp = "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "1x" | "2x" | "3x" | "4x" | "5x" | "6x" | "7x" | "8x" | "9x" | "10x";

// Flip options
type FlipProp = "horizontal" | "vertical" | "both";  

// Pull directions for floating
type PullProp = "left" | "right";

// Standard rotation angles
type RotateProp = 90 | 180 | 270;