_icons

rendering.plugins.directives._icons

Shared SVG icon utilities for directive rendering.

Provides inline SVG icons from Bengal's icon library for use in cards, buttons, and other directives without requiring the full icon directive.

Performance:

Icons are lazily loaded on first access and cached
Rendered output is LRU cached by (name, size, css_class, aria_label)
Regex patterns are pre-compiled at module load

Usage:

from bengal.rendering.plugins.directives._icons import render_svg_icon

icon_html = render_svg_icon("terminal", size=20)

For directives that want warnings on missing icons:

from bengal.rendering.plugins.directives._icons import (
    render_svg_icon,
    icon_exists,
    warn_missing_icon,
)

icon_html = render_svg_icon(icon_name, size=20)
if not icon_html:
    warn_missing_icon(icon_name, directive="dropdown", context="My Dropdown Title")

Functions

_get_icons_directory

Get the icons directory from the default theme.

0 Path

def _get_icons_directory() -> Path

Get the icons directory from the default theme.

Returns

Path

_load_icon

Load an icon SVG by name (with caching).

1 str | None

def _load_icon(name: str) -> str | None

Load an icon SVG by name (with caching).

Parameters 1

Name	Type	Default	Description
`name`	`str`	—	Icon name (without .svg extension)

Returns

str | None —

SVG content string, or None if not found

get_icon_svg

Get raw SVG content for an icon.

1 str | None

def get_icon_svg(name: str) -> str | None

Get raw SVG content for an icon.

Parameters 1

Name	Type	Default	Description
`name`	`str`	—	Icon name (e.g., "terminal", "search", "info")

Returns

str | None —

Raw SVG string, or None if not found

_escape_attr

Escape HTML attribute value.

1 str

def _escape_attr(value: str) -> str

Escape HTML attribute value.

Parameters 1

Name	Type	Default	Description
`value`	`str`	—

Returns

str

render_svg_icon

Render an SVG icon for use in directives. Uses LRU caching to avoid repeated regex processing for …

4 str

def render_svg_icon(name: str, size: int = 20, css_class: str = '', aria_label: str = '') -> str

Render an SVG icon for use in directives.

Uses LRU caching to avoid repeated regex processing for identical icon render calls. Typical hit rate >95% for navigation icons.

Applies ICON_MAP to resolve semantic names (e.g., "alert" -> "warning") before loading the icon file.

Parameters 4

Name	Type	Default	Description
`name`	`str`	—	Icon name (e.g., "terminal", "search", "info", "alert")
`size`	`int`	`20`	Icon size in pixels (default: 20)
`css_class`	`str`	`''`	Additional CSS classes
`aria_label`	`str`	`''`	Accessibility label

Returns

str —

Inline SVG HTML string, or empty string if icon not found

render_icon

Render an icon by name, preferring Phosphor SVG icons. This function maps common icon names to Pho…

2 str

def render_icon(name: str, size: int = 20) -> str

Render an icon by name, preferring Phosphor SVG icons.

This function maps common icon names to Phosphor icons and always attempts to render SVG first. Only returns empty string if icon not found.

Parameters 2

Name	Type	Default	Description
`name`	`str`	—	Icon name (semantic name like "book", "rocket", etc.)
`size`	`int`	`20`	Icon size in pixels

Returns

str —

HTML for icon (SVG only, empty string if not found)

clear_icon_cache

Clear both the raw icon cache and the render cache. Useful for testing or when icons are modified …

0 None

def clear_icon_cache() -> None

Clear both the raw icon cache and the render cache.

Useful for testing or when icons are modified during development.

icon_exists

Check if an icon exists in the icon library. This checks both direct icon names and mapped names f…

1 bool

def icon_exists(name: str) -> bool

Check if an icon exists in the icon library.

This checks both direct icon names and mapped names from ICON_MAP.

Parameters 1

Name	Type	Default	Description
`name`	`str`	—	Icon name to check

Returns

bool —

True if icon exists, False otherwise

warn_missing_icon

Log a warning for a missing icon with helpful context. This centralizes icon warning logic so all …

3 None

def warn_missing_icon(icon_name: str, directive: str = '', context: str = '') -> None

Log a warning for a missing icon with helpful context.

This centralizes icon warning logic so all directives can use it without duplicating code.

Parameters 3

Name	Type	Default	Description
`icon_name`	`str`	—	The icon name that was not found
`directive`	`str`	`''`	Name of the directive using the icon (e.g., "dropdown", "card")
`context`	`str`	`''`	Additional context like element title for locating the issue

get_available_icons

Get list of all available icon names. Returns both the raw icon file names and the semantic aliase…

0 list[str]

def get_available_icons() -> list[str]

Get list of all available icon names.

Returns both the raw icon file names and the semantic aliases from ICON_MAP.

Returns

list[str] —

Sorted list of available icon names