---
title: "Icons and Logos"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Icons and Logos}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Built-in Icons

cardargus includes several SVG icons for common use cases:

```{r icons, eval=FALSE}
library(cardargus)

# House icon (default for fields with with_icon = TRUE)
icon_house(width = 50, height = 56)

# Building icon
icon_building(width = 50, height = 56)

# Construction icon
icon_construction(width = 50, height = 56)

# Map pin icon
icon_map_pin(width = 50, height = 56)

# Money icon
icon_money(width = 50, height = 56)
```

## Using icons in fields

Icons can be added to fields in three ways:

1. **TRUE**: Uses the default house icon
2. **Built-in icon function**: e.g., `icon_building()`
3. **File path**: Any SVG file on your system

```{r field-icons, eval=FALSE}
fields <- list(
  # Default house icon
  list(
    list(label = "Project", value = "Housing Complex", with_icon = TRUE)
  ),
  # Built-in building icon
  list(
    list(label = "Building", value = "Tower A", 
         with_icon = icon_building())
  ),
  # Construction icon
  list(
    list(label = "Status", value = "Under Construction",
         with_icon = icon_construction())
  ),
  # Custom SVG file path
  list(
    list(label = "Custom", value = "My Item",
         with_icon = "/path/to/my_icon.svg")
  )
)

card <- svg_card(
  title = "PROJECT",
  badges_data = list(),
  fields = fields,
  bg_color = "#3498db"
)
```

## Customizing icons

All icons accept customization parameters:

```{r custom-icons, eval=FALSE}
# Custom colors
icon <- icon_house(
  width = 60,
  height = 70,
  stroke_color = "#e74c3c",  # Red outline
  stroke_width = 3,
  fill = "#ffebee"           # Light red fill
)

# Building with custom size
building <- icon_building(
  width = 40,
  height = 48,
  stroke_color = "#2c3e50",
  fill = "#ecf0f1"
)
```

## Bundled Logos

The package includes several SVG logos ready to use:

```{r bundled, eval=FALSE}
# List all bundled SVGs
list_bundled_svgs()
#> [1] "gov_pe3.svg" "morar_bem.svg" "seduh.svg" "tree.svg" "example_card.svg"

# Get full path to a logo
path <- get_svg_path("morar_bem.svg")

# Get the SVGs directory
svgs_dir()
```

## Using logos in cards

Logos can be file paths or SVG strings:

```{r logos-cards, eval=FALSE}
card <- svg_card(
  title = "FAR",
  badges_data = list(
    list(label = "Units", value = "192", color = "white")
  ),
  fields = list(...),
  bg_color = "#fab255",
  
  # Top-right logos (bundled or custom paths)
  logos = c(
    get_svg_path("morar_bem.svg"),
    get_svg_path("seduh.svg"),
    "/path/to/my_custom_logo.svg"  # Any local file
  ),
  logos_height = 40,
  
  # Bottom-left logos
  bottom_logos = c(
    get_svg_path("gov_pe3.svg")
  ),
  bottom_logos_height = 35
)
```

## Loading external SVGs

Use `load_svg_for_embed()` to load and resize external SVG files:
 
```{r external, eval=FALSE}
# Load and resize an external SVG
logo_data <- load_svg_for_embed(
  svg_path = "path/to/my_logo.svg",
  target_height = 50
)

# The result contains:
# - svg_content: The processed SVG string
# - width: Calculated width (maintains aspect ratio)
# - height: The target height
```

## Creating logo rows

For advanced positioning, use the logo row functions:

```{r logo-rows, eval=FALSE}
# Top-right logo row
logo_row <- create_logo_row(
  logos = c("logo1.svg", "logo2.svg"),
  target_height = 40,
  spacing = 15,
  card_width = 500,
  x_offset = 20,
  y_offset = 20
)

# Bottom-left logo row
bottom_row <- create_bottom_logo_row(
  logos = c("logo3.svg"),
  target_height = 30,
  spacing = 10,
  x_offset = 20,
  card_height = 400,
  y_offset = 20
)
```

## Custom SVG logos

You can use any SVG string as a logo:

```{r custom-svg, eval=FALSE}
# Create a simple custom logo
my_logo <- '<svg width="50" height="50" viewBox="0 0 50 50">
  <circle cx="25" cy="25" r="20" fill="#3498db"/>
  <text x="25" y="30" text-anchor="middle" fill="white" font-size="16">AB</text>
</svg>'

# Use in a card
card <- svg_card(
  title = "PROJECT",
  logos = list(my_logo),
  logos_height = 40,
  ...
)
```

## Summary: How to use icons and logos

| Element | How to specify |
|---------|----------------|
| Default icon | `with_icon = TRUE` |
| Built-in icon | `with_icon = icon_house()` |
| Custom SVG file | `with_icon = "/path/to/file.svg"` |
| Bundled logo | `logos = c(get_svg_path("name.svg"))` |
| Custom logo file | `logos = c("/path/to/logo.svg")` |
| SVG string | `logos = list('<svg>...</svg>')` |