@sociallane/elements 1.0.0

package/packages/core/includes/class-widgets-loader.php

@@ -0,0 +1,195 @@
+<?php
+/**
+ * Widgets Loader
+ *
+ * Registers Elementor categories and auto-loads widgets and elements.
+ *
+ * @package SocialLane_Elements
+ */
+
+namespace SocialLane\Elements;
+
+use Elementor\Elements_Manager;
+use Elementor\Widgets_Manager;
+
+// Prevent direct access
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Widgets Loader Class
+ */
+class Widgets_Loader {
+
+	/**
+	 * @var Widget_Manager|null
+	 */
+	private $widget_manager;
+
+	/**
+	 * @param Widget_Manager|null $widget_manager Optional. When set, only enabled widgets are registered.
+	 */
+	public function __construct( ?Widget_Manager $widget_manager = null ) {
+		$this->widget_manager = $widget_manager;
+	}
+
+	/**
+	 * Register custom Elementor categories
+	 *
+	 * @param Elements_Manager $elements_manager Elementor elements manager
+	 */
+	public function register_categories( Elements_Manager $elements_manager ): void {
+		$elements_manager->add_category(
+			'sociallane-elements',
+			[
+				'title' => esc_html__( 'Elements', 'sociallane-elements' ),
+				'icon'  => 'eicon-cube',
+			]
+		);
+
+		$elements_manager->add_category(
+			'sociallane-heroes',
+			[
+				'title' => esc_html__( 'Heroes', 'sociallane-elements' ),
+				'icon'  => 'eicon-star',
+			]
+		);
+
+		$elements_manager->add_category(
+			'sociallane-content',
+			[
+				'title' => esc_html__( 'Content', 'sociallane-elements' ),
+				'icon'  => 'eicon-document-file',
+			]
+		);
+
+		$elements_manager->add_category(
+			'sociallane-cards',
+			[
+				'title' => esc_html__( 'Cards & Grids', 'sociallane-elements' ),
+				'icon'  => 'eicon-gallery-grid',
+			]
+		);
+
+		$elements_manager->add_category(
+			'sociallane-forms',
+			[
+				'title' => esc_html__( 'Forms & CTAs', 'sociallane-elements' ),
+				'icon'  => 'eicon-envelope',
+			]
+		);
+
+		$elements_manager->add_category(
+			'sociallane-navigation',
+			[
+				'title' => esc_html__( 'Navigation', 'sociallane-elements' ),
+				'icon'  => 'eicon-nav-menu',
+			]
+		);
+	}
+
+	/**
+	 * Register widgets and elements.
+	 * Elements are always registered; widgets are gated by widgets.json or Widget_Manager when present.
+	 * Widgets are discovered from packages/widgets/ (and fallback to widgets/ if packages not used).
+	 *
+	 * @param Widgets_Manager $widgets_manager Elementor widgets manager
+	 */
+	public function register_widgets( Widgets_Manager $widgets_manager ): void {
+		$widget_slugs = $this->get_allowed_widget_slugs();
+
+		$this->register_from_directory(
+			$widgets_manager,
+			SOCIALLANE_ELEMENTS_PATH . 'elements',
+			null
+		);
+
+		$widgets_dir = SOCIALLANE_ELEMENTS_PATH . 'packages/widgets';
+		if ( ! is_dir( $widgets_dir ) ) {
+			$widgets_dir = SOCIALLANE_ELEMENTS_PATH . 'widgets';
+		}
+		$this->register_from_directory(
+			$widgets_manager,
+			$widgets_dir,
+			$widget_slugs
+		);
+	}
+
+	/**
+	 * Get the list of widget slugs to register.
+	 * Uses widgets.json if present, otherwise Widget_Manager enabled list.
+	 *
+	 * @return array|null Array of slugs to register, or null for all available
+	 */
+	private function get_allowed_widget_slugs(): ?array {
+		$config_path = SOCIALLANE_ELEMENTS_PATH . 'widgets.json';
+		if ( file_exists( $config_path ) ) {
+			$content = file_get_contents( $config_path );
+			if ( $content !== false ) {
+				$data = json_decode( $content, true );
+				if ( is_array( $data ) && isset( $data['widgets'] ) && is_array( $data['widgets'] ) ) {
+					return $data['widgets'];
+				}
+			}
+		}
+		return $this->widget_manager ? $this->widget_manager->get_enabled_widgets() : null;
+	}
+
+	/**
+	 * Register widgets/elements from a directory.
+	 *
+	 * @param Widgets_Manager $widgets_manager Elementor widgets manager
+	 * @param string          $dir            Directory path (elements or widgets)
+	 * @param array|null      $allowed_slugs  If set, only these slugs are registered (null = all)
+	 */
+	private function register_from_directory( Widgets_Manager $widgets_manager, string $dir, ?array $allowed_slugs ): void {
+		if ( ! is_dir( $dir ) ) {
+			return;
+		}
+
+		$items = glob( $dir . '/*', GLOB_ONLYDIR );
+		foreach ( $items as $item_dir ) {
+			$slug = basename( $item_dir );
+			if ( $allowed_slugs !== null && ! in_array( $slug, $allowed_slugs, true ) ) {
+				continue;
+			}
+
+			$file = $item_dir . '/' . $slug . '.php';
+			if ( ! file_exists( $file ) ) {
+				continue;
+			}
+
+			require_once $file;
+
+			$class = $this->filename_to_class( $slug );
+			$fqcn  = 'SocialLane\\Elements\\' . $class;
+
+			if ( class_exists( $fqcn ) ) {
+				try {
+					$widgets_manager->register( new $fqcn() );
+				} catch ( \Throwable $e ) {
+					if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
+						// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
+						error_log( sprintf( 'SocialLane Elements: Failed to register widget %s: %s', $slug, $e->getMessage() ) );
+					}
+				}
+			}
+		}
+	}
+
+	/**
+	 * Convert kebab-case filename to PascalCase class name
+	 *
+	 * @param string $slug Directory/filename slug
+	 * @return string Class name
+	 */
+	private function filename_to_class( string $slug ): string {
+		$slug = trim( $slug );
+		if ( $slug === '' ) {
+			return '';
+		}
+		$parts = explode( '-', $slug );
+		return implode( '_', array_map( 'ucfirst', array_filter( $parts ) ) );
+	}
+}

package/packages/core/includes/helpers.php

@@ -0,0 +1,407 @@
+<?php
+/**
+ * Shared helper functions for SocialLane Elements
+ *
+ * @package SocialLane_Elements
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Prepare image data for the image element.
+ *
+ * Takes Elementor image control output and returns a normalized array
+ * suitable for elements/image/templates/render.php.
+ *
+ * @param array $image_settings Elementor image control: ['id' => int, 'url' => string]
+ * @param array $options        Optional overrides: alt, sizes, loading, class, image_size
+ * @return array Image data with src, alt, srcset, sizes, width, height, loading, class
+ */
+function sociallane_prepare_image_data( array $image_settings, array $options = [] ): array {
+	$id     = (int) ( $image_settings['id'] ?? 0 );
+	$src    = $image_settings['url'] ?? '';
+	$sizes  = $options['sizes'] ?? '(max-width: 768px) 100vw, 50vw';
+	$loading = $options['loading'] ?? 'lazy';
+	$class  = $options['class'] ?? '';
+	$image_size = $options['image_size'] ?? 'full';
+	$alt    = $options['alt'] ?? '';
+
+	$image = [
+		'src'     => $src,
+		'alt'     => $alt,
+		'id'      => $id,
+		'srcset'  => '',
+		'sizes'   => $sizes,
+		'width'   => '',
+		'height'  => '',
+		'loading' => $loading,
+		'class'   => $class,
+	];
+
+	if ( $id ) {
+		$image_meta = wp_get_attachment_metadata( $id );
+		if ( $image_meta ) {
+			$image['width']  = $image_meta['width'] ?? '';
+			$image['height'] = $image_meta['height'] ?? '';
+			$image['srcset'] = wp_get_attachment_image_srcset( $id, $image_size ) ?: '';
+		}
+	}
+
+	return $image;
+}
+
+/**
+ * Prepare button data for the button element.
+ *
+ * @param string $text    Button label (empty returns null)
+ * @param array  $url     Elementor URL array: url, is_external, nofollow
+ * @param array  $options Optional: variant, size, color, icon, icon_position, class, preset
+ * @return array|null Button data for element or null if text empty
+ */
+function sociallane_prepare_button_data( string $text, array $url, array $options = [] ): ?array {
+	$text = trim( $text );
+	if ( $text === '' ) {
+		return null;
+	}
+
+	$url = is_array( $url ) ? $url : [];
+
+	// Preset can be a key like 'primary' that maps to variant+size
+	if ( ! empty( $options['preset'] ) && function_exists( 'sociallane_parse_button_preset' ) ) {
+		$parsed = sociallane_parse_button_preset( $options['preset'] );
+		$options['variant'] = $options['variant'] ?? $parsed['variant'];
+		$options['size']    = $options['size'] ?? $parsed['size'];
+	}
+
+	$variant = $options['variant'] ?? 'primary';
+	$size    = $options['size'] ?? 'md';
+	$color   = $options['color'] ?? 'default';
+	$icon    = $options['icon'] ?? [];
+	$icon_position = $options['icon_position'] ?? 'right';
+	$extra_class   = $options['class'] ?? '';
+
+	$href        = esc_url( $url['url'] ?? '#' );
+	$is_external = ! empty( $url['is_external'] );
+	$nofollow    = ! empty( $url['nofollow'] );
+
+	$attrs = [];
+	if ( $is_external ) {
+		$attrs[] = 'target="_blank"';
+		$attrs[] = 'rel="noopener noreferrer"';
+	}
+	if ( $nofollow ) {
+		$attrs[] = 'rel="nofollow"';
+	}
+
+	$data = [
+		'text'    => esc_html( $text ),
+		'url'     => $href,
+		'variant' => $variant,
+		'size'    => $size,
+		'attrs'   => implode( ' ', $attrs ),
+	];
+
+	if ( $color !== 'default' ) {
+		$data['color'] = $color;
+	}
+	if ( $extra_class !== '' ) {
+		$data['class'] = $extra_class;
+	}
+	if ( ! empty( $icon['value'] ) ) {
+		$data['icon']          = $icon;
+		$data['icon_position'] = $icon_position;
+	}
+
+	return $data;
+}
+
+/**
+ * Check if an Elementor show_* switcher is enabled.
+ *
+ * @param array  $settings Raw Elementor settings
+ * @param string $key      Setting key (e.g. 'show_eyebrow')
+ * @param string $default  Default when unset ('yes' or 'no')
+ * @return bool
+ */
+function sociallane_show_field( array $settings, string $key, string $default = 'yes' ): bool {
+	return ( $settings[ $key ] ?? $default ) === 'yes';
+}
+
+/**
+ * Conditionally sanitize text for display; returns empty string if not shown.
+ *
+ * @param bool   $show     Whether to show the field
+ * @param array  $settings Raw Elementor settings
+ * @param string $key      Setting key (e.g. 'eyebrow')
+ * @return string
+ */
+function sociallane_sanitize_text( bool $show, array $settings, string $key ): string {
+	return $show ? ( esc_html( $settings[ $key ] ?? '' ) ) : '';
+}
+
+/**
+ * Validate heading tag to allowed values (h1, h2, h3).
+ *
+ * @param array  $settings Raw Elementor settings
+ * @param string $key      Setting key (default 'headline_tag')
+ * @param string $default  Fallback when invalid (default 'h2')
+ * @return string Valid tag name
+ */
+function sociallane_validate_heading_tag( array $settings, string $key = 'headline_tag', string $default = 'h2' ): string {
+	$tag = $settings[ $key ] ?? $default;
+	return in_array( $tag, [ 'h1', 'h2', 'h3' ], true ) ? $tag : $default;
+}
+
+/**
+ * Get content/media order classes for split layouts.
+ *
+ * @param array  $settings Raw Elementor settings
+ * @param string $key      Setting key (default 'content_position')
+ * @return array ['content_order' => string, 'media_order' => string]
+ */
+function sociallane_content_order( array $settings, string $key = 'content_position' ): array {
+	$position = $settings[ $key ] ?? 'left';
+	$content_on_right = $position === 'right';
+	return [
+		'content_order' => $content_on_right ? 'lg:order-2' : 'lg:order-1',
+		'media_order'   => $content_on_right ? 'lg:order-1' : 'lg:order-2',
+	];
+}
+
+/**
+ * Build animation view data for templates.
+ *
+ * @param array $settings Raw Elementor settings.
+ * @param array $opts     Optional: 'headline' => true, 'stagger' => true.
+ * @return array Animation data for $view['animation'].
+ */
+function sociallane_animation_view_data( array $settings, array $opts = [] ): array {
+	$data = [
+		'enabled'  => sociallane_show_field( $settings, 'enable_animation' ),
+		'type'     => $settings['animation_type'] ?? 'fade-up',
+		'delay'    => $settings['animation_delay'] ?? 0,
+		'duration' => $settings['animation_duration'] ?? 0.6,
+	];
+	if ( ! empty( $opts['headline'] ) ) {
+		$data['headline_split'] = $settings['headline_animation'] ?? 'none';
+	}
+	if ( ! empty( $opts['stagger'] ) ) {
+		$data['stagger_enabled'] = sociallane_show_field( $settings, 'stagger_animation' );
+		$data['stagger_delay']   = $settings['stagger_delay'] ?? 0.1;
+	}
+	return $data;
+}
+
+/**
+ * Build data-sl-reveal attributes from animation settings.
+ *
+ * @param array  $settings Raw Elementor settings.
+ * @param string $prefix   Optional prefix for setting keys.
+ * @return string HTML attribute string (e.g. data-sl-reveal="fade-up" data-sl-delay="0.2") or empty.
+ */
+function sociallane_animation_attrs( array $settings, string $prefix = '' ): string {
+	if ( ( $settings[ $prefix . 'enable_animation' ] ?? '' ) !== 'yes' ) {
+		return '';
+	}
+	$type = $settings[ $prefix . 'animation_type' ] ?? 'fade-up';
+	if ( $type === 'none' ) {
+		return '';
+	}
+	$attrs = sprintf( 'data-sl-reveal="%s"', esc_attr( $type ) );
+	if ( isset( $settings[ $prefix . 'animation_delay' ] ) && $settings[ $prefix . 'animation_delay' ] !== '' ) {
+		$attrs .= sprintf( ' data-sl-delay="%s"', esc_attr( (string) $settings[ $prefix . 'animation_delay' ] ) );
+	}
+	if ( isset( $settings[ $prefix . 'animation_duration' ] ) && $settings[ $prefix . 'animation_duration' ] !== '' ) {
+		$attrs .= sprintf( ' data-sl-duration="%s"', esc_attr( (string) $settings[ $prefix . 'animation_duration' ] ) );
+	}
+	return $attrs;
+}
+
+/**
+ * Build data-sl-reveal attributes from animation view data.
+ *
+ * Returns empty so the container (section/header/footer) is never animated.
+ * Only the heading (data-sl-split) and staggered children (data-sl-stagger) animate.
+ *
+ * @param array $anim View animation data from sociallane_animation_view_data().
+ * @return string HTML attributes or empty.
+ */
+function sociallane_section_animation_attrs( array $anim ): string {
+	return '';
+}
+
+/**
+ * Build data-sl-split attribute for headline from animation view data.
+ *
+ * @param array $anim View animation data.
+ * @return string HTML attribute or empty.
+ */
+function sociallane_headline_animation_attrs( array $anim ): string {
+	if ( empty( $anim['enabled'] ) || empty( $anim['headline_split'] ) || $anim['headline_split'] === 'none' ) {
+		return '';
+	}
+	return sprintf( 'data-sl-split="%s"', esc_attr( $anim['headline_split'] ) );
+}
+
+/**
+ * Build data-sl-stagger attribute from animation view data.
+ *
+ * @param array $anim View animation data.
+ * @return string HTML attribute or empty.
+ */
+function sociallane_stagger_attrs( array $anim ): string {
+	if ( empty( $anim['enabled'] ) || empty( $anim['stagger_enabled'] ) ) {
+		return '';
+	}
+	return sprintf( 'data-sl-stagger="%s"', esc_attr( (string) ( $anim['stagger_delay'] ?? 0.1 ) ) );
+}
+
+/**
+ * Prepare link URL and attributes from Elementor URL control data.
+ *
+ * Use in repeaters or anywhere you need link href + target/rel attributes.
+ *
+ * @param array $url_settings Elementor URL control: url, is_external, nofollow
+ * @return array{url: string, attrs: string} Escaped URL and HTML attributes string
+ */
+function sociallane_prepare_link_attrs( array $url_settings ): array {
+	$url_settings = is_array( $url_settings ) ? $url_settings : [];
+	$href         = esc_url( $url_settings['url'] ?? '#' );
+	$attrs        = [];
+
+	if ( ! empty( $url_settings['is_external'] ) ) {
+		$attrs[] = 'target="_blank"';
+		$attrs[] = 'rel="noopener noreferrer"';
+	}
+	if ( ! empty( $url_settings['nofollow'] ) ) {
+		$attrs[] = 'rel="nofollow"';
+	}
+
+	return [
+		'url'   => $href,
+		'attrs' => implode( ' ', $attrs ),
+	];
+}
+
+/**
+ * Get responsive grid column classes for 2, 3, or 4 columns.
+ *
+ * @param string $columns    Column count: '2', '3', or '4'
+ * @param array  $breakpoints Optional overrides: '2' => '...', '3' => '...', '4' => '...'
+ * @return string Tailwind grid-cols classes
+ */
+function sociallane_grid_cols( string $columns, array $breakpoints = [] ): string {
+	$defaults = [
+		'2' => 'grid-cols-1 sm:grid-cols-2',
+		'3' => 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
+		'4' => 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
+	];
+	$map     = array_merge( $defaults, $breakpoints );
+	$columns = (string) $columns;
+	if ( isset( $map[ $columns ] ) && is_string( $map[ $columns ] ) ) {
+		return $map[ $columns ];
+	}
+	return $defaults['4'];
+}
+
+/**
+ * Get alignment classes for text, justify, and flex items.
+ *
+ * @param string $alignment One of: left, center, right
+ * @return array{text: string, justify: string, items: string}
+ */
+function sociallane_align_classes( string $alignment ): array {
+	$valid      = [ 'left', 'center', 'right' ];
+	$alignment  = in_array( $alignment, $valid, true ) ? $alignment : 'left';
+	$text_map   = [ 'left' => 'text-left', 'center' => 'text-center', 'right' => 'text-right' ];
+	$justify_map = [ 'left' => 'justify-start', 'center' => 'justify-center', 'right' => 'justify-end' ];
+	$items_map  = [ 'left' => 'items-start', 'center' => 'items-center', 'right' => 'items-end' ];
+
+	return [
+		'text'    => $text_map[ $alignment ],
+		'justify' => $justify_map[ $alignment ],
+		'items'   => $items_map[ $alignment ],
+	];
+}
+
+/**
+ * Validate that a value is in an allowed list; return default if not.
+ *
+ * @param mixed $value   The value to validate
+ * @param array $allowed Allowed values
+ * @param mixed $default Fallback when invalid
+ * @return mixed Valid value or default
+ */
+function sociallane_validate_option( $value, array $allowed, $default ) {
+	return in_array( $value, $allowed, true ) ? $value : $default;
+}
+
+/**
+ * Extract multiple fields with show/hide logic and sanitization in one call.
+ *
+ * For each field key (e.g. 'headline'), returns show_headline (bool) and headline (string).
+ * Config keys: show_key, default_show, sanitize (esc_html|wp_kses_post|none).
+ *
+ * @param array $settings Raw Elementor settings
+ * @param array $fields   Field config: [ 'headline' => [], 'subtitle' => [ 'default_show' => 'no' ], ... ]
+ * @return array Flat array with show_* and field keys
+ */
+function sociallane_extract_fields( array $settings, array $fields ): array {
+	$result = [];
+	foreach ( $fields as $key => $config ) {
+		$config       = is_array( $config ) ? $config : [];
+		$show_key     = $config['show_key'] ?? "show_{$key}";
+		$default_show = $config['default_show'] ?? 'yes';
+		$sanitize     = $config['sanitize'] ?? 'esc_html';
+
+		$show  = ( $settings[ $show_key ] ?? $default_show ) === 'yes';
+		$value = $settings[ $key ] ?? '';
+
+		$result[ "show_{$key}" ] = $show;
+
+		if ( $sanitize === 'esc_html' ) {
+			$result[ $key ] = $show ? esc_html( $value ) : '';
+		} elseif ( $sanitize === 'wp_kses_post' ) {
+			$result[ $key ] = $show ? wp_kses_post( $value ) : '';
+		} else {
+			$result[ $key ] = $show ? $value : '';
+		}
+	}
+	return $result;
+}
+
+/**
+ * Prepare avatar/small image data for testimonials and profile images.
+ *
+ * @param array  $image_settings Elementor image control output
+ * @param string $fallback_alt   Alt text when image control has none
+ * @return array Image data (same structure as sociallane_prepare_image_data)
+ */
+function sociallane_prepare_avatar( array $image_settings, string $fallback_alt = '' ): array {
+	return sociallane_prepare_image_data( $image_settings, [
+		'alt'        => $fallback_alt,
+		'sizes'      => '96px',
+		'loading'    => 'lazy',
+		'image_size' => 'thumbnail',
+	] );
+}
+
+/**
+ * Process repeater items with a transform callback.
+ *
+ * @param array    $items     Raw repeater items from Elementor settings
+ * @param callable $transform Function( array $item, int $index ): array|null
+ * @return array Processed items (null return from transform skips the item)
+ */
+function sociallane_process_repeater( array $items, callable $transform ): array {
+	$result = [];
+	foreach ( $items as $index => $item ) {
+		$processed = $transform( $item, $index );
+		if ( $processed !== null ) {
+			$result[] = $processed;
+		}
+	}
+	return $result;
+}