with BEM-style classes. Optionally wraps the icon in a tooltip span
* (via cmplz_tc_help_tip()) or in a copy-shortcode widget when both $copy_id
* and $copy_text are supplied.
*
* All user-supplied values that are written into HTML attributes are escaped
* with esc_attr() before output.
*
* Available icon names:
* bullet, circle, check, warning, error, times, circle-check, circle-times,
* chevron-up, chevron-down, chevron-right, chevron-left, plus, minus, sync,
* sync-error, shortcode, file, file-disabled, file-download, calendar,
* calendar-error, help, copy
*
* @since 1.0.0
* @access public
*
* @see cmplz_tc_help_tip() Wraps the icon in a tooltip when $tooltip is set.
*
* @param string $icon_name Key identifying the icon. Must be one of the
* keys listed above.
* @param string $status Controls the fill colour via a CSS custom
* property. Accepted values:
* - 'default' (empty, inherits colour)
* - 'success' (var(--rsp-green))
* - 'warning' (var(--rsp-yellow))
* - 'error' (var(--rsp-red))
* - 'disabled' (var(--rsp-grey-400))
* Default: 'default'.
* @param string $tooltip Optional tooltip string. When non-empty the
* icon is wrapped with cmplz_tc_help_tip().
* Default: ''.
* @param int $size Height of the SVG in pixels. Default: 15.
* @param string|false $copy_id HTML id attribute for the copy-shortcode text
* span. Requires $copy_text to also be set.
* Default: false (no copy widget).
* @param string|false $copy_text The text content placed inside the copy-
* shortcode span identified by $copy_id.
* Default: false (no copy widget).
* @return string HTML string containing the wrapped SVG icon,
* ready for direct output. The caller is
* responsible for escaping the return value if
* needed in a wider HTML context.
*/
function cmplz_tc_icon( $icon_name, $status = 'default', $tooltip = '', $size = 15, $copy_id = false, $copy_text = false ) {
// Possible statuses: default, success, warning, error, disabled.
$status_and_color = array(
'default' => '',
'success' => 'var(--rsp-green)',
'warning' => 'var(--rsp-yellow)',
'error' => 'var(--rsp-red)',
'disabled' => 'var(--rsp-grey-400)',
);
$color = $status_and_color[ $status ];
$icons = array(
'bullet' => '',
'circle' => '',
'check' => '',
'warning' => '',
'error' => '',
'times' => '',
'circle-check' => '',
'circle-times' => '',
'chevron-up' => '',
'chevron-down' => '',
'chevron-right' => '',
'chevron-left' => '',
'plus' => '',
'minus' => '',
'sync' => '',
'sync-error' => '',
'shortcode' => '',
'file' => '',
'file-disabled' => '',
'file-download' => '',
'calendar' => '',
'calendar-error' => '',
'help' => '',
'copy' => '',
);
// Build the base icon wrapper with status and icon-name modifier classes.
$icon_html = '
' . $icons[ $icon_name ] . '
';
if ( ! empty( $tooltip ) ) {
// Wrap with a tooltip span when a tooltip string is provided.
$icon_html = cmplz_tc_help_tip( $tooltip, $icon_html );
}
if ( ! empty( $copy_id ) && ! empty( $copy_text ) ) {
// Wrap with a copy-shortcode widget when both id and text are provided.
$icon_html = '' . $copy_text . '
' . $icon_html . '
';
}
return $icon_html;
}
/**
* Render an icon wrapped in a tooltip span.
*
* Outputs a element that carries the tooltip text as a custom
* `cmplz-tooltip` attribute, which the admin JS picks up to display a
* floating tooltip on hover. When no $content is provided the standard
* question-mark help icon is used as the visual trigger. Uses output
* buffering to produce clean HTML without extra whitespace.
*
* @since 1.0.0
* @access public
*
* @see cmplz_tc_icon() Generates the default help icon used as fallback content.
*
* @param string $str The tooltip text displayed on hover. Escaped
* with esc_attr() before being written into the
* HTML attribute.
* @param string|false $content HTML to use as the visible trigger element.
* When false, falls back to the 'help' icon via
* cmplz_tc_icon( 'help' ). Default: false.
* @return string HTML string containing the tooltip-wrapped
* trigger element.
*/
function cmplz_tc_help_tip( $str, $content = false ) {
$content = ! $content ? cmplz_tc_icon( 'help' ) : $content;
ob_start();
?>