@sociallane/elements 1.0.0

package/.prettierignore

@@ -0,0 +1,5 @@
+node_modules
+assets/dist
+*.min.js
+*.min.css
+vendor

package/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "plugins": ["prettier-plugin-tailwindcss"],
+  "tailwindStylesheet": "./assets/css/tailwind.css"
+}

package/README.md

@@ -0,0 +1,47 @@
+# SocialLane Elements
+
+WordPress plugin: custom Elementor widgets with Tailwind CSS, GSAP animations, Vite build. SEO and WCAG ready.
+
+## Install in a new instance
+
+```bash
+cd wp-content/plugins
+git clone https://github.com/Mitch00llK/sociallane-elements.git
+cd sociallane-elements
+npm install
+```
+
+`npm run build` runs automatically after `npm install` (postinstall). For a full setup with Node version check and optional minimal widget set, run:
+
+```bash
+npm run setup
+```
+
+Activate the plugin in WordPress → Plugins.
+
+See [docs/install-new-instance.md](docs/install-new-instance.md) for submodule setup and details.
+
+## Requirements
+
+- WordPress
+- Elementor
+- Node.js 18+ (for build)
+- PHP 8.0+
+
+## Build
+
+```bash
+npm install   # runs build automatically (postinstall)
+# or
+npm run build
+```
+
+`npm run build` is **required** — Tailwind scans templates and outputs only the utility classes used.
+
+## Widget selection
+
+Edit `widgets.json` to load only the widgets you need. If `widgets.json` is missing, run `npm run setup` to create it from `widgets.json.minimal` (small set). See [docs/package-installation.md](docs/package-installation.md).
+
+## Cursor (all workspaces)
+
+AGENTS.md and `.cursor` (skills + agents) are available in every workspace after a one-time setup. See [docs/cursor-global-rule.md](docs/cursor-global-rule.md).

package/admin/js/widget-browser.js

@@ -0,0 +1,124 @@
+/**
+ * Widget browser: category tabs, checkbox toggles, select/deselect all.
+ * Used on onboarding step-widgets and admin settings page.
+ *
+ * @package SocialLane_Elements
+ */
+( function () {
+	'use strict';
+
+	function initWidgetBrowser( config ) {
+		var tabs = document.querySelectorAll( config.tabSelector );
+		var grids = document.querySelectorAll( config.gridSelector );
+		var countEl = document.getElementById( config.countId );
+		var cards = document.querySelectorAll( config.cardSelector );
+
+		if ( ! tabs.length || ! grids.length ) {
+			return;
+		}
+
+		tabs.forEach( function ( tab ) {
+			tab.addEventListener( 'click', function () {
+				var cat = tab.getAttribute( 'data-category' );
+				tabs.forEach( function ( t ) {
+					t.classList.remove( 'bg-primary', 'text-white' );
+					t.classList.add( 'bg-neutral-100', 'text-neutral-600' );
+					t.setAttribute( 'aria-selected', 'false' );
+				} );
+				tab.classList.remove( 'bg-neutral-100', 'text-neutral-600' );
+				tab.classList.add( 'bg-primary', 'text-white' );
+				tab.setAttribute( 'aria-selected', 'true' );
+				grids.forEach( function ( g ) {
+					g.classList.toggle( 'hidden', g.getAttribute( 'data-category' ) !== cat );
+				} );
+			} );
+		} );
+
+		function updateCount() {
+			var checked = document.querySelectorAll( config.checkboxSelector + ':checked' );
+			if ( countEl ) {
+				countEl.textContent = checked.length;
+			}
+		}
+
+		cards.forEach( function ( card ) {
+			var cb = card.querySelector( config.checkboxSelector );
+			if ( ! cb ) {
+				return;
+			}
+			cb.addEventListener( 'change', function () {
+				var on = cb.checked;
+				card.classList.toggle( 'border-primary', on );
+				card.classList.toggle( 'bg-primary/5', on );
+				card.classList.toggle( 'border-neutral-200', ! on );
+				var toggle = card.querySelector( config.toggleSelector );
+				if ( toggle ) {
+					var dot = toggle.querySelector( 'span' );
+					toggle.classList.toggle( 'bg-primary', on );
+					toggle.classList.toggle( 'bg-neutral-300', ! on );
+					if ( dot ) {
+						dot.classList.toggle( 'translate-x-5', on );
+						dot.classList.toggle( 'translate-x-1', ! on );
+					}
+				}
+				updateCount();
+			} );
+		} );
+
+		var selectAll = document.getElementById( config.selectAllId );
+		if ( selectAll ) {
+			selectAll.addEventListener( 'click', function () {
+				var activeGrid = document.querySelector( config.gridSelector + ':not(.hidden)' );
+				if ( activeGrid ) {
+					activeGrid.querySelectorAll( config.checkboxSelector ).forEach( function ( cb ) {
+						cb.checked = true;
+						cb.dispatchEvent( new Event( 'change' ) );
+					} );
+				}
+			} );
+		}
+
+		var deselectAll = document.getElementById( config.deselectAllId );
+		if ( deselectAll ) {
+			deselectAll.addEventListener( 'click', function () {
+				var activeGrid = document.querySelector( config.gridSelector + ':not(.hidden)' );
+				if ( activeGrid ) {
+					activeGrid.querySelectorAll( config.checkboxSelector ).forEach( function ( cb ) {
+						cb.checked = false;
+						cb.dispatchEvent( new Event( 'change' ) );
+					} );
+				}
+			} );
+		}
+	}
+
+	document.addEventListener( 'DOMContentLoaded', function () {
+		// Onboarding step-widgets
+		if ( document.querySelector( '.category-tab' ) ) {
+			initWidgetBrowser( {
+				tabSelector:     '.category-tab',
+				gridSelector:    '.widget-grid',
+				countId:         'selected-count',
+				cardSelector:    '.widget-card',
+				checkboxSelector: '.widget-checkbox',
+				toggleSelector:  '.widget-card-toggle',
+				selectAllId:     'select-all-cat',
+				deselectAllId:   'deselect-all-cat',
+			} );
+		}
+
+		// Admin settings page
+		if ( document.querySelector( '.settings-category-tab' ) ) {
+			initWidgetBrowser( {
+				tabSelector:     '.settings-category-tab',
+				gridSelector:    '.settings-widget-grid',
+				countId:         'settings-selected-count',
+				cardSelector:    '.settings-widget-card',
+				checkboxSelector: '.settings-widget-checkbox',
+				toggleSelector:  '.settings-widget-card-toggle',
+				selectAllId:     'settings-select-all',
+				deselectAllId:   'settings-deselect-all',
+			} );
+		}
+	} );
+} )();

package/admin/views/onboarding.php

@@ -0,0 +1,62 @@
+<?php
+/**
+ * Onboarding Wizard — Main Wrapper
+ *
+ * @var string $step Current step slug
+ * @var array  $data Step-specific data
+ *
+ * @package SocialLane\Elements
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$steps = [
+	'requirements' => [ 'label' => __( 'Requirements', 'sociallane-elements' ), 'number' => 1 ],
+	'widgets'      => [ 'label' => __( 'Choose Widgets', 'sociallane-elements' ), 'number' => 2 ],
+	'complete'     => [ 'label' => __( 'Complete', 'sociallane-elements' ), 'number' => 3 ],
+];
+?>
+<div class="sociallane-onboarding wrap max-w-5xl mx-auto py-12 px-4">
+	<div class="text-center mb-12">
+		<h1 class="text-3xl font-bold text-neutral-900">
+			<?php esc_html_e( 'Welcome to SocialLane Elements', 'sociallane-elements' ); ?>
+		</h1>
+		<p class="mt-2 text-neutral-500">
+			<?php esc_html_e( "Let's get your widget library set up in a few quick steps.", 'sociallane-elements' ); ?>
+		</p>
+	</div>
+
+	<div class="flex items-center justify-center gap-4 mb-12 flex-wrap">
+		<?php foreach ( $steps as $key => $s ) : ?>
+			<?php
+			$is_active    = ( $key === $step );
+			$is_completed = ( $s['number'] < $steps[ $step ]['number'] );
+			$dot_class    = $is_active ? 'bg-primary text-white' : ( $is_completed ? 'bg-green-500 text-white' : 'bg-neutral-200 text-neutral-500' );
+			?>
+			<div class="flex items-center gap-2">
+				<span class="w-8 h-8 rounded-full flex items-center justify-center text-sm font-bold <?php echo esc_attr( $dot_class ); ?>">
+					<?php echo $is_completed ? '&#10003;' : (int) $s['number']; ?>
+				</span>
+				<span class="text-sm font-medium <?php echo $is_active ? 'text-neutral-900' : 'text-neutral-400'; ?>">
+					<?php echo esc_html( $s['label'] ); ?>
+				</span>
+			</div>
+			<?php if ( $s['number'] < 3 ) : ?>
+				<div class="w-16 h-px bg-neutral-200" aria-hidden="true"></div>
+			<?php endif; ?>
+		<?php endforeach; ?>
+	</div>
+
+	<div class="bg-white rounded-2xl shadow-sm border border-neutral-200 p-8">
+		<?php
+		$step_file = SOCIALLANE_ELEMENTS_PATH . 'admin/views/partials/step-' . $step . '.php';
+		if ( file_exists( $step_file ) ) {
+			include $step_file;
+		} else {
+			echo '<p>' . esc_html__( 'Step template not found.', 'sociallane-elements' ) . '</p>';
+		}
+		?>
+	</div>
+</div>

package/admin/views/partials/category-tabs.php

@@ -0,0 +1,39 @@
+<?php
+/**
+ * Admin Partial: Category tabs for widget browser
+ *
+ * Expects: $categories, $registry, $prefix (e.g. '' or 'settings-')
+ *
+ * @package SocialLane\Elements
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$tab_class = $prefix . 'category-tab';
+?>
+<div class="flex flex-wrap gap-2 mb-6 border-b border-neutral-200 pb-4" role="tablist">
+	<?php $first = true; ?>
+	<?php foreach ( $categories as $cat_key => $cat_label ) : ?>
+		<?php
+		$count = count( array_filter( $registry, function ( $w ) use ( $cat_key ) {
+			return $w['category'] === $cat_key;
+		} ) );
+		if ( $count === 0 ) {
+			continue;
+		}
+		?>
+		<button
+			type="button"
+			role="tab"
+			data-category="<?php echo esc_attr( $cat_key ); ?>"
+			class="<?php echo esc_attr( $tab_class ); ?> px-4 py-2 rounded-full text-sm font-medium transition-colors <?php echo $first ? 'bg-primary text-white' : 'bg-neutral-100 text-neutral-600 hover:bg-neutral-200'; ?>"
+			aria-selected="<?php echo $first ? 'true' : 'false'; ?>"
+		>
+			<?php echo esc_html( $cat_label ); ?>
+			<span class="ml-1 text-xs opacity-75">(<?php echo (int) $count; ?>)</span>
+		</button>
+		<?php $first = false; ?>
+	<?php endforeach; ?>
+</div>

package/admin/views/partials/step-complete.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * Onboarding Step: Complete
+ *
+ * @var array $data Contains 'enabled_count', 'total_count'
+ *
+ * @package SocialLane\Elements
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$enabled_count = (int) ( $data['enabled_count'] ?? 0 );
+$total_count   = (int) ( $data['total_count'] ?? 0 );
+?>
+<div class="text-center py-6">
+	<div class="inline-flex items-center justify-center w-16 h-16 rounded-full bg-green-100 text-green-600 mb-6" aria-hidden="true">
+		<svg class="w-8 h-8" fill="currentColor" viewBox="0 0 20 20"><path fill-rule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clip-rule="evenodd" /></svg>
+	</div>
+	<h2 class="text-2xl font-bold text-neutral-900 mb-2">
+		<?php esc_html_e( "You're all set!", 'sociallane-elements' ); ?>
+	</h2>
+	<p class="text-neutral-600 mb-8">
+		<?php
+		printf(
+			/* translators: 1: number of enabled widgets, 2: total widgets */
+			esc_html__( '%1$d of %2$d widgets are enabled and ready to use in the Elementor editor.', 'sociallane-elements' ),
+			$enabled_count,
+			$total_count
+		);
+		?>
+	</p>
+	<div class="flex flex-wrap items-center justify-center gap-4">
+		<a href="<?php echo esc_url( admin_url( 'edit.php?post_type=page' ) ); ?>"
+			class="inline-flex items-center px-5 py-2.5 bg-primary text-white font-medium rounded-lg hover:opacity-90 no-underline">
+			<?php esc_html_e( 'Create a page', 'sociallane-elements' ); ?>
+		</a>
+		<a href="<?php echo esc_url( admin_url( 'admin.php?page=sociallane-settings' ) ); ?>"
+			class="inline-flex items-center px-5 py-2.5 border border-neutral-300 text-neutral-700 font-medium rounded-lg hover:bg-neutral-50 no-underline">
+			<?php esc_html_e( 'Manage Widgets', 'sociallane-elements' ); ?>
+		</a>
+		<a href="<?php echo esc_url( admin_url( 'admin.php?page=sociallane-onboarding' ) ); ?>"
+			class="inline-flex items-center px-5 py-2.5 text-neutral-500 hover:text-neutral-700 no-underline text-sm">
+			<?php esc_html_e( 'Re-run setup wizard', 'sociallane-elements' ); ?>
+		</a>
+	</div>
+</div>

package/admin/views/partials/step-requirements.php

@@ -0,0 +1,52 @@
+<?php
+/**
+ * Onboarding Step: System Requirements
+ *
+ * @var array $data Contains 'requirements', 'all_pass'
+ *
+ * @package SocialLane\Elements
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$requirements = $data['requirements'] ?? [];
+$all_pass     = $data['all_pass'] ?? false;
+?>
+<div class="space-y-4">
+	<?php foreach ( $requirements as $req ) : ?>
+		<?php $pass = ! empty( $req['pass'] ); ?>
+		<div class="flex items-center gap-3 p-4 rounded-lg <?php echo $pass ? 'bg-green-50 dark:bg-green-900/20' : 'bg-red-50 dark:bg-red-900/20'; ?>">
+			<span class="shrink-0 w-8 h-8 rounded-full flex items-center justify-center <?php echo $pass ? 'text-green-600 bg-green-100' : 'text-red-600 bg-red-100'; ?>">
+				<?php if ( $pass ) : ?>
+					<svg class="w-5 h-5" fill="currentColor" viewBox="0 0 20 20" aria-hidden="true"><path fill-rule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clip-rule="evenodd" /></svg>
+				<?php else : ?>
+					<svg class="w-5 h-5" fill="currentColor" viewBox="0 0 20 20" aria-hidden="true"><path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd" /></svg>
+				<?php endif; ?>
+			</span>
+			<div class="min-w-0">
+				<p class="font-medium text-neutral-900 dark:text-neutral-100"><?php echo esc_html( $req['label'] ); ?></p>
+				<p class="text-sm text-neutral-500">
+					<?php
+					printf(
+						/* translators: 1: required value, 2: detected value */
+						esc_html__( 'Required: %1$s — Detected: %2$s', 'sociallane-elements' ),
+						esc_html( $req['required'] ),
+						esc_html( $req['detected'] )
+					);
+					?>
+				</p>
+			</div>
+		</div>
+	<?php endforeach; ?>
+</div>
+
+<div class="flex items-center justify-between mt-8 pt-6 border-t border-neutral-200">
+	<span></span>
+	<a href="<?php echo esc_url( admin_url( 'admin.php?page=sociallane-onboarding&step=widgets' ) ); ?>"
+		class="px-6 py-3 bg-primary text-white font-semibold rounded-lg hover:opacity-90 transition-opacity focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2 no-underline">
+		<?php esc_html_e( 'Continue to Choose Widgets', 'sociallane-elements' ); ?>
+		&rarr;
+	</a>
+</div>

package/admin/views/partials/step-widgets.php

@@ -0,0 +1,63 @@
+<?php
+/**
+ * Onboarding Step: Widget Browser
+ *
+ * @var array $data Contains 'registry', 'categories', 'enabled'
+ *
+ * @package SocialLane\Elements
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$registry   = $data['registry'];
+$categories = $data['categories'];
+$enabled    = $data['enabled'];
+$prefix     = '';
+$grid_class = 'widget-grid';
+?>
+<form method="post" action="">
+	<?php wp_nonce_field( 'sociallane_onboarding', 'sociallane_onboarding_nonce' ); ?>
+	<input type="hidden" name="current_step" value="widgets" />
+
+	<?php
+	require __DIR__ . '/category-tabs.php';
+	$count_id       = 'selected-count';
+	$select_all_id  = 'select-all-cat';
+	$deselect_all_id = 'deselect-all-cat';
+	require __DIR__ . '/widget-toolbar.php';
+	?>
+
+	<?php $first = true; ?>
+	<?php foreach ( $categories as $cat_key => $cat_label ) : ?>
+		<?php
+		$cat_widgets = array_filter( $registry, function ( $w ) use ( $cat_key ) {
+			return $w['category'] === $cat_key;
+		} );
+		if ( empty( $cat_widgets ) ) {
+			continue;
+		}
+		?>
+		<div class="<?php echo esc_attr( $grid_class ); ?> <?php echo $first ? '' : 'hidden'; ?>" data-category="<?php echo esc_attr( $cat_key ); ?>">
+			<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+				<?php foreach ( $cat_widgets as $slug => $widget ) : ?>
+					<?php
+					$is_enabled = in_array( $slug, $enabled, true );
+					require __DIR__ . '/widget-card.php';
+					?>
+				<?php endforeach; ?>
+			</div>
+		</div>
+		<?php $first = false; ?>
+	<?php endforeach; ?>
+
+	<div class="flex items-center justify-between mt-8 pt-6 border-t border-neutral-200">
+		<a href="<?php echo esc_url( admin_url( 'admin.php?page=sociallane-onboarding&step=requirements' ) ); ?>" class="text-sm text-neutral-500 hover:text-neutral-700 no-underline">
+			&larr; <?php esc_html_e( 'Back', 'sociallane-elements' ); ?>
+		</a>
+		<button type="submit" class="px-6 py-3 bg-primary text-white font-semibold rounded-lg hover:opacity-90 transition-opacity focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2 cursor-pointer border-0">
+			<?php esc_html_e( 'Save & Complete Setup', 'sociallane-elements' ); ?>
+		</button>
+	</div>
+</form>

package/admin/views/partials/widget-card.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * Admin Partial: Single widget card (preview, name, description, toggle)
+ *
+ * Expects: $slug, $widget, $is_enabled, $prefix (e.g. '' or 'settings-')
+ *
+ * @package SocialLane\Elements
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$card_class   = $prefix . 'widget-card';
+$checkbox_class = $prefix . 'widget-checkbox';
+$toggle_class = $prefix . 'widget-card-toggle';
+$preview_url  = \SocialLane\Elements\Widget_Manager::get_widget_preview_url( $slug, $widget );
+$preview_is_svg = $preview_url && substr( $preview_url, -4 ) === '.svg';
+$preview_pages_enabled = class_exists( '\SocialLane\Elements\Widget_Preview' ) && \SocialLane\Elements\Widget_Preview::is_enabled();
+$preview_page_url = $preview_pages_enabled ? home_url( '/widget-preview/' . $slug . '/' ) : '';
+?>
+<label class="<?php echo esc_attr( $card_class ); ?> group relative rounded-xl border-2 cursor-pointer transition-all block <?php echo $is_enabled ? 'border-primary bg-primary/5' : 'border-neutral-200 hover:border-neutral-300'; ?>">
+	<input
+		type="checkbox"
+		name="widgets[]"
+		value="<?php echo esc_attr( $slug ); ?>"
+		<?php checked( $is_enabled ); ?>
+		class="sr-only <?php echo esc_attr( $checkbox_class ); ?>"
+	/>
+	<?php if ( $preview_url ) : ?>
+		<div class="aspect-video overflow-hidden rounded-t-lg flex items-center justify-center <?php echo $preview_is_svg ? 'bg-neutral-100 p-6' : ''; ?>">
+			<?php if ( $preview_is_svg ) : ?>
+				<img
+					src="<?php echo esc_url( $preview_url ); ?>"
+					alt=""
+					class="w-full h-full object-contain"
+					loading="lazy"
+				/>
+			<?php else : ?>
+				<img
+					src="<?php echo esc_url( $preview_url ); ?>"
+					alt="<?php echo esc_attr( $widget['name'] ); ?> preview"
+					class="w-full h-full object-cover object-top"
+					loading="lazy"
+				/>
+			<?php endif; ?>
+		</div>
+	<?php else : ?>
+		<div class="aspect-video flex items-center justify-center bg-neutral-50 rounded-t-lg">
+			<span class="text-neutral-400 text-sm text-center px-2"><?php echo esc_html( $widget['name'] ); ?></span>
+		</div>
+	<?php endif; ?>
+	<div class="p-4 flex items-start justify-between gap-3">
+		<div class="min-w-0">
+			<h3 class="font-semibold text-sm text-neutral-900 truncate"><?php echo esc_html( $widget['name'] ); ?></h3>
+			<p class="text-xs text-neutral-500 mt-0.5 line-clamp-2"><?php echo esc_html( $widget['description'] ); ?></p>
+			<?php if ( $preview_page_url ) : ?>
+				<a href="<?php echo esc_url( $preview_page_url ); ?>" target="_blank" rel="noopener noreferrer" class="text-xs text-primary hover:underline mt-2 inline-block" onclick="event.stopPropagation();">
+					<?php esc_html_e( 'Preview', 'sociallane-elements' ); ?>
+				</a>
+			<?php endif; ?>
+		</div>
+		<div class="<?php echo esc_attr( $toggle_class ); ?> shrink-0 w-10 h-6 rounded-full flex items-center transition-colors <?php echo $is_enabled ? 'bg-primary' : 'bg-neutral-300'; ?>">
+			<span class="block w-4 h-4 rounded-full bg-white shadow transition-transform <?php echo $is_enabled ? 'translate-x-5' : 'translate-x-1'; ?>"></span>
+		</div>
+	</div>
+</label>

package/admin/views/partials/widget-toolbar.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * Admin Partial: Widget selection toolbar (count + select/deselect all)
+ *
+ * Expects: $enabled, $registry, $count_id, $select_all_id, $deselect_all_id
+ *
+ * @package SocialLane\Elements
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+?>
+<div class="flex items-center justify-between mb-6">
+	<p class="text-sm text-neutral-500">
+		<span id="<?php echo esc_attr( $count_id ); ?>"><?php echo (int) count( $enabled ); ?></span>
+		<?php printf( esc_html__( 'of %d widgets selected', 'sociallane-elements' ), count( $registry ) ); ?>
+	</p>
+	<div class="flex gap-2">
+		<button type="button" id="<?php echo esc_attr( $select_all_id ); ?>" class="text-sm text-primary hover:underline cursor-pointer border-0 bg-transparent p-0">
+			<?php esc_html_e( 'Select all in category', 'sociallane-elements' ); ?>
+		</button>
+		<span class="text-neutral-300">|</span>
+		<button type="button" id="<?php echo esc_attr( $deselect_all_id ); ?>" class="text-sm text-neutral-500 hover:underline cursor-pointer border-0 bg-transparent p-0">
+			<?php esc_html_e( 'Deselect all in category', 'sociallane-elements' ); ?>
+		</button>
+	</div>
+</div>

package/admin/views/preview-embed.php

@@ -0,0 +1,78 @@
+<?php
+/**
+ * Widget Preview — Embed (widget only, no frame)
+ *
+ * Renders a single widget with sample/default data for iframe display.
+ *
+ * @package SocialLane\Elements
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+// Suppress notices/warnings during preview so missing default keys never leak into output.
+$prev_error_level = error_reporting( E_ERROR | E_PARSE );
+
+$slug = get_query_var( 'sociallane_preview', '' );
+$slug = is_string( $slug ) ? preg_replace( '/[^a-z0-9-]/', '', $slug ) : '';
+if ( $slug === '' ) {
+	return;
+}
+
+$widgets_dir = SOCIALLANE_ELEMENTS_PATH . 'packages/widgets';
+if ( ! is_dir( $widgets_dir ) ) {
+	$widgets_dir = SOCIALLANE_ELEMENTS_PATH . 'widgets';
+}
+$widget_dir = $widgets_dir . '/' . $slug;
+$view_file  = $widget_dir . '/data/view.php';
+$wrapper    = $widget_dir . '/templates/wrapper.php';
+
+if ( ! is_file( $view_file ) || ! is_file( $wrapper ) ) {
+	status_header( 404 );
+	echo esc_html__( 'Widget not found.', 'sociallane-elements' );
+	return;
+}
+
+$prepare_fn = 'prepare_' . str_replace( '-', '_', $slug ) . '_view';
+if ( ! function_exists( $prepare_fn ) ) {
+	require_once $view_file;
+}
+if ( ! function_exists( $prepare_fn ) ) {
+	status_header( 404 );
+	echo esc_html__( 'Widget view not found.', 'sociallane-elements' );
+	return;
+}
+
+$defaults_file = SOCIALLANE_ELEMENTS_PATH . 'includes/widget-preview-defaults.php';
+if ( is_file( $defaults_file ) ) {
+	require_once $defaults_file;
+}
+$settings = function_exists( 'sociallane_get_preview_defaults' ) ? sociallane_get_preview_defaults( $slug ) : [];
+$settings = apply_filters( 'sociallane_elements_preview_settings', $settings, $slug );
+$view     = $prepare_fn( $settings, 'preview' );
+if ( empty( $view ) || ! is_array( $view ) ) {
+	status_header( 500 );
+	echo esc_html__( 'Widget preview failed.', 'sociallane-elements' );
+	return;
+}
+
+// Minimal HTML document so plugin styles (wp_head) load.
+?><!DOCTYPE html>
+<html <?php language_attributes(); ?>>
+<head>
+	<meta charset="<?php bloginfo( 'charset' ); ?>">
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<title><?php echo esc_html( $slug ); ?></title>
+	<?php wp_head(); ?>
+</head>
+<body class="sociallane-preview-embed">
+	<?php
+	include $wrapper;
+	?>
+	<?php wp_footer(); ?>
+</body>
+</html>
+<?php
+error_reporting( $prev_error_level );
+exit;