"""Reusable visual components for common automation patterns.
Component library providing pre-configured visual components and templates
for efficient workflow creation with drag-and-drop functionality.
Security: Component validation with input sanitization and type safety.
Performance: <50ms component creation, cached templates for reuse.
Type Safety: Complete component library with contracts and validation.
"""
import logging
from datetime import UTC, datetime
from enum import Enum
from typing import Any
from ..core.contracts import require
from ..core.either import Either
from ..core.visual_design import (
CanvasPosition,
ComponentProperties,
ComponentType,
LayerId,
VisualComponent,
create_component_id,
)
logger = logging.getLogger(__name__)
class ComponentCategory(Enum):
"""Visual component categories for organization."""
TRIGGERS = "triggers"
CONDITIONS = "conditions"
ACTIONS = "actions"
UTILITIES = "utilities"
ADVANCED = "advanced"
CUSTOM = "custom"
class ActionCategory(Enum):
"""Action component subcategories."""
FILE_OPERATIONS = "file_operations"
TEXT_PROCESSING = "text_processing"
APPLICATION_CONTROL = "application_control"
SYSTEM_OPERATIONS = "system_operations"
COMMUNICATION = "communication"
AUTOMATION = "automation"
@require(
lambda component_type,
title,
description="",
default_properties=None,
category=ComponentCategory.ACTIONS,
subcategory=None,
icon=None,
color="#007AFF": len(title) > 0
and len(title) <= 100
and component_type is not None
and isinstance(description, str)
and (default_properties is None or isinstance(default_properties, dict))
and isinstance(category, ComponentCategory)
and (subcategory is None or isinstance(subcategory, str))
and (icon is None or isinstance(icon, str))
and isinstance(color, str)
)
def create_component_definition(
component_type: ComponentType,
title: str,
description: str = "",
default_properties: dict[str, Any] | None = None,
category: ComponentCategory = ComponentCategory.ACTIONS,
subcategory: str | None = None,
icon: str | None = None,
color: str = "#007AFF",
) -> dict[str, Any]:
"""Create standardized component definition."""
return {
"component_type": component_type,
"title": title,
"description": description,
"default_properties": default_properties or {},
"category": category,
"subcategory": subcategory,
"icon": icon,
"color": color,
"created_at": datetime.now(UTC).isoformat(),
}
class ComponentLibrary:
"""Visual component library with templates and presets."""
def __init__(self):
self.component_definitions: dict[str, dict[str, Any]] = {}
self.custom_components: dict[str, dict[str, Any]] = {}
self.usage_statistics: dict[str, int] = {}
self.logger = logging.getLogger(__name__)
self._initialize_standard_components()
def _initialize_standard_components(self) -> None:
"""Initialize standard component library."""
# Trigger Components
self.component_definitions.update(
{
"trigger_hotkey": create_component_definition(
ComponentType.TRIGGER,
"Hotkey Trigger",
"Trigger macro execution with keyboard shortcut",
{
"hotkey": "⌘⇧Space",
"modifiers": ["cmd", "shift"],
"key": "space",
"global": True,
},
ComponentCategory.TRIGGERS,
icon="keyboard",
),
"trigger_file_watch": create_component_definition(
ComponentType.TRIGGER,
"File Watcher",
"Monitor file or folder for changes",
{
"path": "/Users/username/Desktop",
"watch_type": "created",
"file_filter": "*",
"recursive": False,
},
ComponentCategory.TRIGGERS,
icon="folder",
),
"trigger_app_launch": create_component_definition(
ComponentType.TRIGGER,
"Application Launch",
"Trigger when specific application launches",
{
"bundle_id": "com.apple.finder",
"app_name": "Finder",
"trigger_type": "launch",
},
ComponentCategory.TRIGGERS,
icon="app",
),
"trigger_time_based": create_component_definition(
ComponentType.TRIGGER,
"Time-based Trigger",
"Execute at specific time or interval",
{
"schedule_type": "daily",
"time": "09:00",
"days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
],
"timezone": "local",
},
ComponentCategory.TRIGGERS,
icon="clock",
),
},
)
# Condition Components
self.component_definitions.update(
{
"condition_text_contains": create_component_definition(
ComponentType.CONDITION,
"Text Contains",
"Check if text contains specific string",
{
"text_source": "%Variable%Text%",
"search_text": "",
"case_sensitive": False,
"match_type": "contains",
},
ComponentCategory.CONDITIONS,
icon="text",
color="#FF6B35",
),
"condition_file_exists": create_component_definition(
ComponentType.CONDITION,
"File Exists",
"Check if file or folder exists",
{"file_path": "", "check_type": "exists", "follow_aliases": True},
ComponentCategory.CONDITIONS,
icon="document",
color="#FF6B35",
),
"condition_app_running": create_component_definition(
ComponentType.CONDITION,
"Application Running",
"Check if application is currently running",
{"bundle_id": "", "app_name": "", "check_type": "is_running"},
ComponentCategory.CONDITIONS,
icon="app",
color="#FF6B35",
),
"condition_variable_value": create_component_definition(
ComponentType.CONDITION,
"Variable Value",
"Compare variable value against condition",
{
"variable_name": "",
"comparison": "equals",
"compare_value": "",
"data_type": "text",
},
ComponentCategory.CONDITIONS,
icon="variable",
color="#FF6B35",
),
},
)
# Action Components - File Operations
self.component_definitions.update(
{
"action_copy_file": create_component_definition(
ComponentType.ACTION,
"Copy File",
"Copy file or folder to destination",
{
"source_path": "",
"destination_path": "",
"overwrite": False,
"preserve_attributes": True,
},
ComponentCategory.ACTIONS,
ActionCategory.FILE_OPERATIONS.value,
icon="doc.on.doc",
color="#34C759",
),
"action_move_file": create_component_definition(
ComponentType.ACTION,
"Move File",
"Move file or folder to destination",
{
"source_path": "",
"destination_path": "",
"overwrite": False,
"create_folders": True,
},
ComponentCategory.ACTIONS,
ActionCategory.FILE_OPERATIONS.value,
icon="folder",
color="#34C759",
),
"action_delete_file": create_component_definition(
ComponentType.ACTION,
"Delete File",
"Delete file or folder (move to trash)",
{"file_path": "", "confirm_deletion": True, "secure_delete": False},
ComponentCategory.ACTIONS,
ActionCategory.FILE_OPERATIONS.value,
icon="trash",
color="#FF3B30",
),
},
)
# Action Components - Text Processing
self.component_definitions.update(
{
"action_set_variable": create_component_definition(
ComponentType.ACTION,
"Set Variable",
"Set or update variable value",
{
"variable_name": "",
"variable_value": "",
"data_type": "text",
"scope": "global",
},
ComponentCategory.ACTIONS,
ActionCategory.TEXT_PROCESSING.value,
icon="textformat.abc",
color="#007AFF",
),
"action_text_processing": create_component_definition(
ComponentType.ACTION,
"Process Text",
"Transform text with various operations",
{
"input_text": "",
"operation": "uppercase",
"parameters": {},
"output_variable": "ProcessedText",
},
ComponentCategory.ACTIONS,
ActionCategory.TEXT_PROCESSING.value,
icon="textformat",
color="#007AFF",
),
"action_find_replace": create_component_definition(
ComponentType.ACTION,
"Find & Replace",
"Find and replace text with regex support",
{
"input_text": "",
"find_text": "",
"replace_text": "",
"use_regex": False,
"case_sensitive": False,
"replace_all": True,
},
ComponentCategory.ACTIONS,
ActionCategory.TEXT_PROCESSING.value,
icon="magnifyingglass",
color="#007AFF",
),
},
)
# Action Components - Application Control
self.component_definitions.update(
{
"action_launch_app": create_component_definition(
ComponentType.ACTION,
"Launch Application",
"Launch or activate application",
{
"bundle_id": "",
"app_name": "",
"bring_to_front": True,
"wait_for_launch": True,
},
ComponentCategory.ACTIONS,
ActionCategory.APPLICATION_CONTROL.value,
icon="app.badge.play",
color="#FF9500",
),
"action_quit_app": create_component_definition(
ComponentType.ACTION,
"Quit Application",
"Quit specific application",
{
"bundle_id": "",
"app_name": "",
"force_quit": False,
"save_documents": True,
},
ComponentCategory.ACTIONS,
ActionCategory.APPLICATION_CONTROL.value,
icon="app.badge.xmark",
color="#FF3B30",
),
"action_menu_select": create_component_definition(
ComponentType.ACTION,
"Select Menu Item",
"Select menu item from application menu",
{"app_name": "", "menu_path": [], "wait_for_completion": True},
ComponentCategory.ACTIONS,
ActionCategory.APPLICATION_CONTROL.value,
icon="menubar.rectangle",
color="#FF9500",
),
},
)
# Action Components - Communication
self.component_definitions.update(
{
"action_send_email": create_component_definition(
ComponentType.ACTION,
"Send Email",
"Send email message",
{
"to_addresses": [],
"cc_addresses": [],
"bcc_addresses": [],
"subject": "",
"body": "",
"attachments": [],
"send_immediately": False,
},
ComponentCategory.ACTIONS,
ActionCategory.COMMUNICATION.value,
icon="envelope",
color="#007AFF",
),
"action_notification": create_component_definition(
ComponentType.ACTION,
"Show Notification",
"Display system notification",
{
"title": "",
"message": "",
"sound": "default",
"duration": 5.0,
"action_button": None,
},
ComponentCategory.ACTIONS,
ActionCategory.COMMUNICATION.value,
icon="bell",
color="#5856D6",
),
"action_speak_text": create_component_definition(
ComponentType.ACTION,
"Speak Text",
"Use text-to-speech to speak text",
{
"text": "",
"voice": "system_default",
"rate": 200,
"wait_for_completion": True,
},
ComponentCategory.ACTIONS,
ActionCategory.COMMUNICATION.value,
icon="speaker.wave.2",
color="#5856D6",
),
},
)
# Utility Components
self.component_definitions.update(
{
"utility_delay": create_component_definition(
ComponentType.ACTION,
"Delay",
"Pause execution for specified duration",
{
"delay_seconds": 1.0,
"delay_type": "fixed",
"random_range": {"min": 0.5, "max": 2.0},
},
ComponentCategory.UTILITIES,
icon="timer",
color="#8E8E93",
),
"utility_comment": create_component_definition(
ComponentType.COMMENT,
"Comment",
"Add documentation comment to workflow",
{
"comment_text": "",
"font_size": 12,
"background_color": "#FFFACD",
},
ComponentCategory.UTILITIES,
icon="text.bubble",
color="#8E8E93",
),
"utility_group": create_component_definition(
ComponentType.GROUP,
"Group",
"Group related components together",
{
"group_name": "Group",
"collapsed": False,
"background_color": "#F2F2F7",
"border_style": "solid",
},
ComponentCategory.UTILITIES,
icon="rectangle.3.group",
color="#8E8E93",
),
},
)
def get_component_definition(self, component_key: str) -> dict[str, Any] | None:
"""Get component definition by key."""
return self.component_definitions.get(
component_key,
) or self.custom_components.get(component_key)
def list_components_by_category(
self,
category: ComponentCategory,
) -> list[dict[str, Any]]:
"""List all components in specified category."""
components = []
for key, definition in self.component_definitions.items():
if definition["category"] == category:
components.append({"key": key, **definition})
for key, definition in self.custom_components.items():
if definition["category"] == category:
components.append({"key": key, **definition})
return sorted(components, key=lambda x: x["title"])
def search_components(self, query: str) -> list[dict[str, Any]]:
"""Search components by title, description, or category."""
query_lower = query.lower()
results = []
all_components = {**self.component_definitions, **self.custom_components}
for key, definition in all_components.items():
if (
query_lower in definition["title"].lower()
or query_lower in definition["description"].lower()
or query_lower in definition["category"].value.lower()
or (
definition.get("subcategory")
and query_lower in definition["subcategory"].lower()
)
):
results.append(
{
"key": key,
"relevance_score": self._calculate_relevance(
query_lower,
definition,
),
**definition,
},
)
return sorted(results, key=lambda x: x["relevance_score"], reverse=True)
def create_component_instance(
self,
component_key: str,
position: CanvasPosition,
layer_id: LayerId,
custom_properties: dict[str, Any] | None = None,
) -> Either[Exception, VisualComponent]:
"""Create component instance from library definition."""
try:
definition = self.get_component_definition(component_key)
if not definition:
return Either.left(
ValueError(f"Component definition '{component_key}' not found"),
)
# Merge default properties with custom properties
properties_dict = definition["default_properties"].copy()
if custom_properties:
properties_dict.update(custom_properties)
# Create component properties
component_properties = ComponentProperties(
title=definition["title"],
description=definition["description"],
properties=properties_dict,
)
# Create visual component
component = VisualComponent(
component_id=create_component_id(),
component_type=definition["component_type"],
position=position,
properties=component_properties,
layer_id=layer_id,
)
# Track usage
self.usage_statistics[component_key] = (
self.usage_statistics.get(component_key, 0) + 1
)
self.logger.info(f"Created component instance: {component_key}")
return Either.right(component)
except Exception as e:
self.logger.error(f"Failed to create component instance: {e}")
return Either.left(e)
def add_custom_component(
self,
key: str,
component_definition: dict[str, Any],
) -> Either[Exception, bool]:
"""Add custom component definition to library."""
try:
# Validate component definition
required_fields = ["component_type", "title", "description", "category"]
for field in required_fields:
if field not in component_definition:
return Either.left(ValueError(f"Missing required field: {field}"))
# Ensure component type is valid
if not isinstance(component_definition["component_type"], ComponentType):
return Either.left(ValueError("Invalid component_type"))
# Add creation timestamp
component_definition["created_at"] = datetime.now(UTC).isoformat()
component_definition["custom"] = True
self.custom_components[key] = component_definition
self.logger.info(f"Added custom component: {key}")
return Either.right(True)
except Exception as e:
self.logger.error(f"Failed to add custom component: {e}")
return Either.left(e)
def get_popular_components(self, limit: int = 10) -> list[dict[str, Any]]:
"""Get most popular components based on usage statistics."""
popular = sorted(
self.usage_statistics.items(),
key=lambda x: x[1],
reverse=True,
)[:limit]
results = []
for component_key, usage_count in popular:
definition = self.get_component_definition(component_key)
if definition:
results.append(
{
"key": component_key,
"usage_count": usage_count,
**definition,
},
)
return results
def _calculate_relevance(self, query: str, definition: dict[str, Any]) -> float:
"""Calculate relevance score for search results."""
score = 0.0
# Title match (highest weight)
if query in definition["title"].lower():
score += 3.0
if definition["title"].lower().startswith(query):
score += 2.0
# Description match
if query in definition["description"].lower():
score += 1.0
# Category match
if query in definition["category"].value.lower():
score += 0.5
# Subcategory match
if definition.get("subcategory") and query in definition["subcategory"].lower():
score += 0.5
# Usage popularity bonus
usage_count = self.usage_statistics.get(definition.get("key", ""), 0)
score += min(usage_count * 0.1, 1.0)
return score
def get_library_statistics(self) -> dict[str, Any]:
"""Get component library statistics."""
category_counts = {}
for definition in {
**self.component_definitions,
**self.custom_components,
}.values():
category = definition["category"].value
category_counts[category] = category_counts.get(category, 0) + 1
return {
"total_components": len(self.component_definitions)
+ len(self.custom_components),
"standard_components": len(self.component_definitions),
"custom_components": len(self.custom_components),
"category_breakdown": category_counts,
"total_usage": sum(self.usage_statistics.values()),
"most_used_component": max(
self.usage_statistics.items(),
key=lambda x: x[1],
)[0]
if self.usage_statistics
else None,
}
# Global component library instance
_component_library: ComponentLibrary | None = None
def get_component_library() -> ComponentLibrary:
"""Get or create global component library instance."""
global _component_library
if _component_library is None:
_component_library = ComponentLibrary()
return _component_library
