@sociallane/elements 1.0.11 → 1.0.13

package/docs/install-new-instance.md

@@ -55,13 +55,13 @@ cd wp-content/plugins/sociallane-elements && npm install && npm run build
 
 ```bash
 # From your WordPress root (directory that contains wp-content)
-npx @sociallane/elements --minimal
+npx @sociallane/elements --base
 ```
 
 Then add widgets by slug (no manual `widgets.json` editing):
 
 ```bash
-npx @sociallane/elements add hero-split faq content-block widget-filter
+npx @sociallane/elements add hero-split faq-stacked content-block widget-filter
 ```
 
 Each `add` updates `widgets.json` and runs the build. You can run `add` anytime to add more widgets.
@@ -77,8 +77,8 @@ This copies the full plugin to `wp-content/plugins/sociallane-elements`, runs `n
 **Custom path:**
 
 ```bash
-npx @sociallane/elements --minimal path/to/wp-content/plugins/sociallane-elements
-npx @sociallane/elements add hero-split faq   # run from WordPress root or plugin dir
+npx @sociallane/elements --base path/to/wp-content/plugins/sociallane-elements
+npx @sociallane/elements add --target path/to/wp-content/plugins/sociallane-elements hero-split faq-stacked
 ```
 
 **Single widget (per-widget packages):**
@@ -87,7 +87,7 @@ You can install one widget at a time via its own package. This installs the Soci
 
 ```bash
 # From your WordPress root or wp-content/plugins
-npx @sociallane/widget-hero-overlay
+npx @sociallane/widget-content-block
 npx @sociallane/widget-faq-stacked
 ```
 

package/docs/npm-widget-cheatsheet.md

@@ -7,8 +7,11 @@ Quick reference for loading widgets via npm workspaces.
 ## One-liners
 
 ```bash
-# Full install — REQUIRED for styled widgets (from plugin root)
-npm install && npm run build
+# Base install (no widgets imported yet)
+npx @sociallane/elements --base
+
+# Add selected widgets
+npx @sociallane/elements add hero-split faq-stacked content-block
 
 # Dev watch (rebuilds on file change)
 npm run dev
@@ -28,7 +31,7 @@ Edit `widgets.json` at plugin root:
     "hero-split",
     "hero-overlay",
     "content-block",
-    "faq"
+    "faq-stacked"
   ]
 }
 ```
@@ -39,7 +42,10 @@ Only slugs listed here are loaded. Add or remove as needed.
 
 ## Widget → npm package & command
 
-Every widget and its npm package / add command:
+Common widgets and their npm package / add command:
+
+> Note: per-widget packages may not all be published at the same time.  
+> The most reliable flow is `npx @sociallane/elements --base` then `npx @sociallane/elements add ...`.
 
 | Widget | Package | Command |
 |--------|---------|---------|
@@ -52,7 +58,9 @@ Every widget and its npm package / add command:
 | cta-banner | `@sociallane/widget-cta-banner` | `npm install @sociallane/widget-cta-banner` |
 | cta-notify | `@sociallane/widget-cta-notify` | `npm install @sociallane/widget-cta-notify` |
 | cta-split | `@sociallane/widget-cta-split` | `npm install @sociallane/widget-cta-split` |
-| faq | `@sociallane/widget-faq` | `npm install @sociallane/widget-faq` |
+| faq-stacked | `@sociallane/widget-faq-stacked` | `npm install @sociallane/widget-faq-stacked` |
+| faq-split | `@sociallane/widget-faq-split` | `npm install @sociallane/widget-faq-split` |
+| faq-centered | `@sociallane/widget-faq-centered` | `npm install @sociallane/widget-faq-centered` |
 | feature-grid | `@sociallane/widget-feature-grid` | `npm install @sociallane/widget-feature-grid` |
 | feature-list | `@sociallane/widget-feature-list` | `npm install @sociallane/widget-feature-list` |
 | feature-list-cta | `@sociallane/widget-feature-list-cta` | `npm install @sociallane/widget-feature-list-cta` |
@@ -62,25 +70,34 @@ Every widget and its npm package / add command:
 | form-contact | `@sociallane/widget-form-contact` | `npm install @sociallane/widget-form-contact` |
 | grid-case-studies | `@sociallane/widget-grid-case-studies` | `npm install @sociallane/widget-grid-case-studies` |
 | grid-components | `@sociallane/widget-grid-components` | `npm install @sociallane/widget-grid-components` |
-| grid-posts | `@sociallane/widget-grid-posts` | `npm install @sociallane/widget-grid-posts` |
+| posts-grid | `@sociallane/widget-posts-grid` | `npm install @sociallane/widget-posts-grid` |
+| posts-grid-overlay | `@sociallane/widget-posts-grid-overlay` | `npm install @sociallane/widget-posts-grid-overlay` |
 | grid-team | `@sociallane/widget-grid-team` | `npm install @sociallane/widget-grid-team` |
-| grid-testimonials | `@sociallane/widget-grid-testimonials` | `npm install @sociallane/widget-grid-testimonials` |
+| testimonials-grid | `@sociallane/widget-testimonials-grid` | `npm install @sociallane/widget-testimonials-grid` |
+| testimonials-masonry | `@sociallane/widget-testimonials-masonry` | `npm install @sociallane/widget-testimonials-masonry` |
+| testimonials-bento | `@sociallane/widget-testimonials-bento` | `npm install @sociallane/widget-testimonials-bento` |
 | hero-announcement | `@sociallane/widget-hero-announcement` | `npm install @sociallane/widget-hero-announcement` |
 | hero-centered-image | `@sociallane/widget-hero-centered-image` | `npm install @sociallane/widget-hero-centered-image` |
 | hero-collage | `@sociallane/widget-hero-collage` | `npm install @sociallane/widget-hero-collage` |
 | hero-overlay | `@sociallane/widget-hero-overlay` | `npm install @sociallane/widget-hero-overlay` |
-| hero-saas | `@sociallane/widget-hero-saas` | `npm install @sociallane/widget-hero-saas` |
+| hero-saas-split | `@sociallane/widget-hero-saas-split` | `npm install @sociallane/widget-hero-saas-split` |
+| hero-saas-stacked | `@sociallane/widget-hero-saas-stacked` | `npm install @sociallane/widget-hero-saas-stacked` |
+| hero-saas-centered | `@sociallane/widget-hero-saas-centered` | `npm install @sociallane/widget-hero-saas-centered` |
 | hero-split | `@sociallane/widget-hero-split` | `npm install @sociallane/widget-hero-split` |
 | hero-stacked-image | `@sociallane/widget-hero-stacked-image` | `npm install @sociallane/widget-hero-stacked-image` |
 | intro-pattern | `@sociallane/widget-intro-pattern` | `npm install @sociallane/widget-intro-pattern` |
 | intro-text | `@sociallane/widget-intro-text` | `npm install @sociallane/widget-intro-text` |
-| logo-grid | `@sociallane/widget-logo-grid` | `npm install @sociallane/widget-logo-grid` |
+| logo-grid-centered | `@sociallane/widget-logo-grid-centered` | `npm install @sociallane/widget-logo-grid-centered` |
+| logo-grid-row | `@sociallane/widget-logo-grid-row` | `npm install @sociallane/widget-logo-grid-row` |
+| logo-grid-split | `@sociallane/widget-logo-grid-split` | `npm install @sociallane/widget-logo-grid-split` |
 | nav-default | `@sociallane/widget-nav-default` | `npm install @sociallane/widget-nav-default` |
 | nav-centered | `@sociallane/widget-nav-centered` | `npm install @sociallane/widget-nav-centered` |
 | nav-minimal | `@sociallane/widget-nav-minimal` | `npm install @sociallane/widget-nav-minimal` |
 | nav-compact | `@sociallane/widget-nav-compact` | `npm install @sociallane/widget-nav-compact` |
 | nav-floating | `@sociallane/widget-nav-floating` | `npm install @sociallane/widget-nav-floating` |
 | newsletter | `@sociallane/widget-newsletter` | `npm install @sociallane/widget-newsletter` |
+| newsletter-card | `@sociallane/widget-newsletter-card` | `npm install @sociallane/widget-newsletter-card` |
+| newsletter-section | `@sociallane/widget-newsletter-section` | `npm install @sociallane/widget-newsletter-section` |
 | outreach-dashboard | `@sociallane/widget-outreach-dashboard` | `npm install @sociallane/widget-outreach-dashboard` |
 | pipeline-dashboard | `@sociallane/widget-pipeline-dashboard` | `npm install @sociallane/widget-pipeline-dashboard` |
 | pricing-table | `@sociallane/widget-pricing-table` | `npm install @sociallane/widget-pricing-table` |
@@ -89,7 +106,9 @@ Every widget and its npm package / add command:
 | services | `@sociallane/widget-services` | `npm install @sociallane/widget-services` |
 | simple-page-hero | `@sociallane/widget-simple-page-hero` | `npm install @sociallane/widget-simple-page-hero` |
 | social-proof | `@sociallane/widget-social-proof` | `npm install @sociallane/widget-social-proof` |
+| social-proof-trust | `@sociallane/widget-social-proof-trust` | `npm install @sociallane/widget-social-proof-trust` |
 | testimonial-quote | `@sociallane/widget-testimonial-quote` | `npm install @sociallane/widget-testimonial-quote` |
+| widget-filter | `@sociallane/widget-widget-filter` | `npm install @sociallane/widget-widget-filter` |
 
 Then add the slug to `widgets.json`.
 
@@ -99,12 +118,12 @@ Then add the slug to `widgets.json`.
 
 | Category | Slugs |
 |----------|-------|
-| Heroes | `hero-split`, `hero-overlay`, `hero-saas`, `hero-collage`, `hero-centered-image`, `hero-stacked-image`, `hero-announcement`, `simple-page-hero` |
-| Content | `content-block`, `intro-text`, `intro-pattern`, `faq`, `feature-list`, `feature-list-cta`, `feature-grid` |
-| Cards & Grids | `card-hover-reveal`, `bento-grid`, `bento-portfolio`, `grid-posts`, `grid-team`, `grid-testimonials`, `grid-case-studies`, `grid-components`, `logo-grid`, `client-logos` |
-| Forms & CTAs | `cta-banner`, `cta-split`, `cta-notify`, `newsletter`, `form-contact`, `pricing-table` |
+| Heroes | `hero-split`, `hero-overlay`, `hero-overlay-single`, `hero-overlay-slider`, `hero-saas-split`, `hero-saas-stacked`, `hero-saas-centered`, `hero-collage`, `hero-centered-image`, `hero-stacked-image`, `hero-announcement`, `simple-page-hero`, `page-hero-left`, `page-hero-center` |
+| Content | `content-block`, `intro-text`, `intro-pattern`, `faq-stacked`, `faq-split`, `faq-centered`, `feature-list`, `feature-list-cta`, `feature-grid` |
+| Cards & Grids | `card-hover-reveal`, `bento-grid`, `bento-portfolio`, `posts-grid`, `posts-grid-overlay`, `grid-team`, `testimonials-grid`, `testimonials-masonry`, `testimonials-bento`, `grid-case-studies`, `grid-components`, `logo-grid-centered`, `logo-grid-row`, `logo-grid-split`, `client-logos` |
+| Forms & CTAs | `cta-banner`, `cta-split`, `cta-notify`, `newsletter`, `newsletter-card`, `newsletter-section`, `form-contact`, `pricing-table` |
 | Navigation | `nav-default`, `nav-centered`, `nav-minimal`, `nav-compact`, `nav-floating`, `footer`, `footer-brand`, `footer-links-contact` |
-| Other | `section-stats`, `social-proof`, `services`, `blog-grid`, `outreach-dashboard`, `pipeline-dashboard`, `sales-dashboard`, `testimonial-quote` |
+| Other | `section-stats`, `social-proof`, `social-proof-trust`, `services`, `blog-grid`, `outreach-dashboard`, `pipeline-dashboard`, `sales-dashboard`, `testimonial-quote`, `widget-filter` |
 
 ---
 

package/docs/package-installation.md

@@ -29,7 +29,8 @@ Edit `widgets.json` to include only the widget slugs you want. You can also let
 
 Adding or removing widget directories is reflected in `widgets.json` automatically:
 
-- **On `npm install`** — The postinstall script runs `sync-widgets` then `build`. Any new folder under `packages/widgets/{slug}` with `{slug}.php` is added to `widgets.json`; removed folders are removed from the list. Existing order is preserved; new slugs are appended sorted.
+- **On `npm install`** — The postinstall script runs `sync-widgets` then `build` by default. Any new folder under `packages/widgets/{slug}` with `{slug}.php` is added to `widgets.json`; removed folders are removed from the list. Existing order is preserved; new slugs are appended sorted.  
+  The installers use `SOCIALLANE_SKIP_SYNC_WIDGETS=1` for base/cherry-pick flows so `widgets.json` is not expanded unintentionally.
 - **Manual sync** — From the plugin root run:
   ```bash
   npm run sync-widgets
@@ -42,7 +43,7 @@ Adding or removing widget directories is reflected in `widgets.json` automatical
     "hero-split",
     "hero-overlay",
     "content-block",
-    "faq"
+    "faq-stacked"
   ]
 }
 ```
@@ -65,10 +66,10 @@ Use submodules so each WordPress instance only has the core package and the widg
 
    # Add only the widgets you want
    git submodule add <url-to-widget-hero-split> packages/widgets/hero-split
-   git submodule add <url-to-widget-faq> packages/widgets/faq
+   git submodule add <url-to-widget-faq-stacked> packages/widgets/faq-stacked
    ```
 
-3. Update **widgets.json** so its `widgets` array lists only the slugs you added (e.g. `hero-split`, `faq`).
+3. Update **widgets.json** so its `widgets` array lists only the slugs you added (e.g. `hero-split`, `faq-stacked`).
 
 4. Install and build from plugin root (both required for styled widgets):
 
@@ -123,13 +124,13 @@ The plugin is published as `@sociallane/elements`. To publish:
 
 ## Per-widget npm packages
 
-Individual widgets are published as `@sociallane/widget-<slug>` (e.g. `@sociallane/widget-hero-overlay`). Run from your WordPress root or `wp-content/plugins`:
+Individual widgets are published as `@sociallane/widget-<slug>` (for example `@sociallane/widget-faq-stacked`). Run from your WordPress root or `wp-content/plugins`:
 
 ```bash
-npx @sociallane/widget-hero-overlay
+npx @sociallane/widget-faq-stacked
 ```
 
-The installer installs the base plugin (`@sociallane/elements`) with `--minimal` if it is not present, then copies the widget into the plugin, runs `sync-widgets`, and `npm install`. Use these when you want a one-command install for a single widget. To add multiple widgets, `npx @sociallane/elements add slug1 slug2` is usually simpler.
+The installer installs the base plugin (`@sociallane/elements`) with `--base` if it is not present, then delegates to `npx @sociallane/elements add --target <pluginDir> <slug>`. Use these when you want a one-command install for a single widget. To add multiple widgets, `npx @sociallane/elements add --target <pluginDir> slug1 slug2` is usually simpler.
 
 ## Adding a new widget package
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sociallane/elements",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "Elementor widgets and elements with Tailwind CSS for SocialLane. WordPress plugin.",
   "type": "module",
   "private": false,

package/packages/widgets/card-hover-reveal/data/view.php

@@ -77,7 +77,7 @@ function prepare_card_hover_reveal_view( array $settings, string $widget_id ): a
 	$aspect_map    = [ '16/9' => 'aspect-video', '4/3' => 'aspect-[4/3]', '3/2' => 'aspect-[3/2]', '1/1' => 'aspect-square', '3/4' => 'aspect-[3/4]' ];
 	$aspect_class  = $aspect_map[ $aspect_ratio ] ?? 'aspect-video';
 	$columns      = sociallane_validate_option( $settings['columns'] ?? '3', [ '2', '3' ], '3' );
-	$grid_class   = sociallane_grid_cols( $columns, [ '2' => 'grid-cols-1 sm:grid-cols-2', '3' => 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3' ] );
+	$grid_class   = sociallane_grid_cols( $columns, [ '2' => 'grid-cols-1 sm:grid-cols-2', '3' => 'grid-cols-1 sm:grid-cols-2 md:grid-cols-3' ] );
 
 	$animation = sociallane_animation_view_data( $settings, [ 'headline' => true, 'stagger' => true ] );
 

package/packages/widgets/grid-components/data/view.php

@@ -23,7 +23,12 @@ function prepare_grid_components_view( array $settings, string $widget_id ): arr
 	$fields       = sociallane_extract_fields( $settings, [ 'headline' => [] ] );
 	$headline_tag = sociallane_validate_heading_tag( $settings, 'headline_tag', 'h2' );
 	$columns      = sociallane_validate_option( $settings['columns'] ?? '4', [ '2', '3', '4' ], '4' );
-	$grid_class   = sociallane_grid_cols( $columns );
+	$grid_class   = sociallane_grid_cols(
+		$columns,
+		[
+			'3' => 'grid-cols-1 sm:grid-cols-2 md:grid-cols-3',
+		]
+	);
 	$placeholder_src = \Elementor\Utils::get_placeholder_image_src();
 
 	$components = sociallane_process_repeater( $settings['components'] ?? [], function ( $item ) use ( $placeholder_src ) {

package/packages/widgets/widget-filter/data/view.php

@@ -484,8 +484,8 @@ function prepare_widget_filter_view( array $settings, string $widget_id ): array
 	// Grid columns class
 	$grid_columns = [
 		'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',
+		'3' => 'grid-cols-1 sm:grid-cols-2 md:grid-cols-3',
+		'4' => 'grid-cols-1 sm:grid-cols-2 md:grid-cols-3 xl:grid-cols-4',
 	];
 	$grid_class = $grid_columns[ $columns ] ?? $grid_columns['3'];
 

package/scripts/install.js

@@ -2,23 +2,60 @@
 /**
  * SocialLane Elements CLI
  *
+ * Install (base):  npx @sociallane/elements --base [path]
  * Install (full):  npx @sociallane/elements [path]
  * Add widgets:     npx @sociallane/elements add <slug> [slug...]
  *
  * Install: copies package to wp-content/plugins/sociallane-elements (or path), runs npm install.
+ * Base install: installs core/deps and keeps widgets.json empty (no widgets loaded by default).
  * Add: copies selected widget folders into an existing plugin, updates widgets.json, runs npm install.
  */
 
-import { cpSync, existsSync, mkdirSync, readdirSync, writeFileSync } from 'fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'fs';
 import { spawnSync } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, '..');
-const widgetsSource = path.join(packageRoot, 'packages', 'widgets');
+const packageJsonPath = path.join(packageRoot, 'package.json');
+
+function getCliVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function printHelp() {
+  console.log('SocialLane Elements CLI');
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx @sociallane/elements [--base|--minimal] [target]');
+  console.log('  npx @sociallane/elements add [--only] [--target <path>] <slug> [slug...]');
+  console.log('  npx @sociallane/elements --help');
+  console.log('  npx @sociallane/elements --version');
+  console.log('');
+  console.log('Options:');
+  console.log('  --base, --minimal   Install core/deps only, keep widgets.json empty');
+  console.log('  --only              With add: replace widgets.json with exactly provided slugs');
+  console.log('  --target <path>     With add: explicit plugin directory target');
+  console.log('  --help              Show this help text');
+  console.log('  --version           Show CLI version');
+  console.log('');
+  console.log('Examples:');
+  console.log('  npx @sociallane/elements --base');
+  console.log('  npx @sociallane/elements add faq-stacked hero-split');
+  console.log('  npx @sociallane/elements add --only --target wp-content/plugins/sociallane-elements content-block');
+}
+
+function resolvePluginDir(targetPath = '') {
+  if (targetPath) {
+    return path.resolve(process.cwd(), targetPath);
+  }
 
-function resolvePluginDir() {
   const cwd = process.cwd();
   const normalized = path.normalize(cwd);
   const pluginsSegment = 'wp-content' + path.sep + 'plugins';
@@ -41,9 +78,59 @@ function resolvePluginDir() {
   return path.join(cwd, 'wp-content', 'plugins', 'sociallane-elements');
 }
 
-function addWidgets(slugs) {
-  const pluginDir = resolvePluginDir();
+function getWidgetsSourceDir() {
+  const candidates = [
+    path.join(packageRoot, 'packages', 'widgets'),
+    path.join(packageRoot, 'widgets'),
+  ];
+
+  for (const dir of candidates) {
+    if (!existsSync(dir)) {
+      continue;
+    }
+    const available = readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && existsSync(path.join(dir, d.name, `${d.name}.php`)))
+      .map((d) => d.name);
+    if (available.length > 0) {
+      return dir;
+    }
+  }
+  return candidates[0];
+}
+
+function updateWidgetsJson(pluginDir, slugsToAdd, replaceAll = false) {
+  const widgetsJsonPath = path.join(pluginDir, 'widgets.json');
+  let existing = [];
+
+  if (!replaceAll && existsSync(widgetsJsonPath)) {
+    try {
+      const raw = readFileSync(widgetsJsonPath, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed?.widgets)) {
+        existing = parsed.widgets.filter((slug) => typeof slug === 'string');
+      }
+    } catch (err) {
+      console.warn('Could not parse widgets.json, recreating it:', err.message);
+    }
+  }
+
+  const merged = [...existing];
+  const existingSet = new Set(existing);
+  for (const slug of slugsToAdd) {
+    if (!existingSet.has(slug)) {
+      merged.push(slug);
+      existingSet.add(slug);
+    }
+  }
+
+  writeFileSync(widgetsJsonPath, JSON.stringify({ widgets: merged }, null, 2) + '\n');
+}
+
+function addWidgets(slugs, options = {}) {
+  const replaceAll = options.replaceAll === true;
+  const pluginDir = resolvePluginDir(options.targetPath || '');
   const widgetsDest = path.join(pluginDir, 'packages', 'widgets');
+  const widgetsSource = getWidgetsSourceDir();
 
   if (!existsSync(path.join(pluginDir, 'sociallane-elements.php'))) {
     console.error('Plugin not found at', pluginDir);
@@ -56,8 +143,10 @@ function addWidgets(slugs) {
     process.exit(1);
   }
 
+  console.log('Target plugin:', pluginDir);
+
   const available = readdirSync(widgetsSource, { withFileTypes: true })
-    .filter((d) => d.isDirectory())
+    .filter((d) => d.isDirectory() && existsSync(path.join(widgetsSource, d.name, `${d.name}.php`)))
     .map((d) => d.name);
 
   const missing = slugs.filter((s) => !available.includes(s));
@@ -84,17 +173,16 @@ function addWidgets(slugs) {
     console.log('Added:', slug);
   }
 
-  console.log('Updating widgets.json and building...');
-  const result = spawnSync('node', [path.join(pluginDir, 'scripts', 'sync-widgets.js')], {
-    cwd: pluginDir,
-    stdio: 'inherit',
-  });
-  if (result.status !== 0) {
-    process.exit(result.status || 1);
-  }
+  updateWidgetsJson(pluginDir, slugs, replaceAll);
+  console.log('Updated widgets.json and installing dependencies...');
+
   const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
   const installResult = spawnSync(npmCmd, ['install'], {
     cwd: pluginDir,
+    env: {
+      ...process.env,
+      SOCIALLANE_SKIP_SYNC_WIDGETS: '1',
+    },
     stdio: 'inherit',
     shell: true,
   });
@@ -108,6 +196,14 @@ function addWidgets(slugs) {
   console.log('Done. Widgets added:', slugs.join(', '));
 }
 
+function prepareBaseMode(pluginDir) {
+  const widgetsDest = path.join(pluginDir, 'packages', 'widgets');
+  if (!existsSync(widgetsDest)) {
+    mkdirSync(widgetsDest, { recursive: true });
+  }
+  updateWidgetsJson(pluginDir, [], true);
+}
+
 function copyPackage(toDir, filter) {
   if (!existsSync(toDir)) {
     mkdirSync(toDir, { recursive: true });
@@ -154,12 +250,21 @@ function install(targetPath, minimal) {
   const targetResolved = path.resolve(target);
   const isSelf = targetResolved === path.resolve(packageRoot) || targetResolved.startsWith(packageRoot + path.sep);
 
-  console.log('SocialLane Elements installer' + (minimal ? ' (minimal – add widgets with: npx @sociallane/elements add <slug> ...)' : ''));
+  console.log(
+    'SocialLane Elements installer' +
+      (minimal ? ' (base mode – add widgets with: npx @sociallane/elements add <slug> ...)' : '')
+  );
   console.log('Target:', target);
 
   if (isSelf) {
+    if (minimal) {
+      prepareBaseMode(packageRoot);
+    }
     console.log('Target is the current package. Running npm install here...');
   } else if (existsSync(target) && existsSync(path.join(target, 'package.json'))) {
+    if (minimal) {
+      prepareBaseMode(target);
+    }
     console.log('Target already exists. Running npm install only...');
   } else {
     console.log('Copying package...');
@@ -168,16 +273,18 @@ function install(targetPath, minimal) {
         const rel = path.relative(packageRoot, src).split(path.sep).join('/');
         // Exclude node_modules within the package (not in parent path)
         if (rel.includes('node_modules')) return false;
-        // Exclude packages/widgets for minimal install
+        // Base install should not ship widget sources; users add explicitly via `add`.
         if (rel === 'packages/widgets' || rel.startsWith('packages/widgets/')) return false;
+        // Exclude legacy widgets directory and generated npm-widget package folders.
+        if (rel === 'widgets' || rel.startsWith('widgets/')) return false;
+        if (rel === 'packages/npm-widgets' || rel.startsWith('packages/npm-widgets/')) return false;
         return true;
       });
       const widgetsDest = path.join(target, 'packages', 'widgets');
       if (!existsSync(widgetsDest)) {
         mkdirSync(widgetsDest, { recursive: true });
       }
-      const widgetsJson = path.join(target, 'widgets.json');
-      writeFileSync(widgetsJson, JSON.stringify({ widgets: [] }, null, 2));
+      updateWidgetsJson(target, [], true);
     } else {
       copyPackage(target);
     }
@@ -186,8 +293,15 @@ function install(targetPath, minimal) {
   const installDir = isSelf ? packageRoot : target;
   console.log('Running npm install in', installDir + '...');
   const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const installEnv = {
+    ...process.env,
+  };
+  if (minimal) {
+    installEnv.SOCIALLANE_SKIP_SYNC_WIDGETS = '1';
+  }
   const result = spawnSync(npmCmd, ['install'], {
     cwd: installDir,
+    env: installEnv,
     stdio: 'inherit',
     shell: true,
   });
@@ -209,19 +323,72 @@ function install(targetPath, minimal) {
 
 function main() {
   const args = process.argv.slice(2);
-  const minimal = args.includes('--minimal');
-  const installArgs = args.filter((a) => a !== '--minimal');
 
-  if (installArgs[0] === 'add') {
-    const slugs = installArgs.slice(1).filter(Boolean);
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log(getCliVersion());
+    return;
+  }
+
+  if (args[0] === 'add') {
+    const addArgs = args.slice(1).filter(Boolean);
+    const knownAddFlags = new Set(['--only', '--target']);
+    let targetPath = '';
+    const slugs = [];
+    for (let i = 0; i < addArgs.length; i++) {
+      const arg = addArgs[i];
+      if (arg === '--target') {
+        const next = addArgs[i + 1];
+        if (!next || next.startsWith('-')) {
+          console.error('Missing value for --target');
+          process.exit(1);
+        }
+        targetPath = next;
+        i++;
+        continue;
+      }
+      if (arg.startsWith('-')) {
+        if (!knownAddFlags.has(arg)) {
+          console.error('Unknown option for add:', arg);
+          process.exit(1);
+        }
+        continue;
+      }
+      slugs.push(arg);
+    }
+
+    const replaceAll = addArgs.includes('--only');
     if (slugs.length === 0) {
-      console.error('Usage: npx @sociallane/elements add <slug> [slug...]');
-      console.error('Example: npx @sociallane/elements add hero-split faq content-block');
+      console.error('Usage: npx @sociallane/elements add [--only] <slug> [slug...]');
+      console.error('Example: npx @sociallane/elements add --only hero-split faq-stacked content-block');
       process.exit(1);
     }
-    addWidgets(slugs);
+    addWidgets(slugs, { replaceAll, targetPath });
   } else {
-    install(installArgs[0], minimal);
+    let minimal = false;
+    const positionals = [];
+    for (const arg of args) {
+      if (arg === '--minimal' || arg === '--base') {
+        minimal = true;
+        continue;
+      }
+      if (arg.startsWith('-')) {
+        console.error('Unknown option:', arg);
+        process.exit(1);
+      }
+      positionals.push(arg);
+    }
+
+    if (positionals.length > 1) {
+      console.error('Too many positional arguments. Expected at most one target path.');
+      process.exit(1);
+    }
+
+    install(positionals[0], minimal);
   }
 }
 

package/scripts/postinstall.js

@@ -54,14 +54,17 @@ function ensureLocalCliShim() {
 
 ensureLocalCliShim();
 
-// Run sync-widgets
-console.log('Running sync-widgets...');
-const syncResult = spawnSync('node', [path.join(__dirname, 'sync-widgets.js')], {
-  cwd: pluginRoot,
-  stdio: 'inherit',
-});
-if (syncResult.status !== 0) {
-  process.exit(syncResult.status || 1);
+const skipSyncWidgets = process.env.SOCIALLANE_SKIP_SYNC_WIDGETS === '1';
+if (!skipSyncWidgets) {
+  // Run sync-widgets
+  console.log('Running sync-widgets...');
+  const syncResult = spawnSync('node', [path.join(__dirname, 'sync-widgets.js')], {
+    cwd: pluginRoot,
+    stdio: 'inherit',
+  });
+  if (syncResult.status !== 0) {
+    process.exit(syncResult.status || 1);
+  }
 }
 
 // Run build

package/scripts/widget-installer.js

@@ -1,18 +1,17 @@
 #!/usr/bin/env node
 /**
  * Per-widget installer: run from a @sociallane/widget-<slug> package (npx).
- * Ensures SocialLane Elements plugin is installed, then copies this package's widget/
- * into the plugin's packages/widgets/<slug>, runs sync-widgets and npm install.
+ * Ensures SocialLane Elements plugin is installed in base mode, then delegates
+ * widget import to the main CLI add command.
  */
 
-import { cpSync, existsSync, mkdirSync, readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { spawnSync } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname);
-const widgetDir = path.join(packageRoot, 'widget');
 
 function getSlugFromPackage() {
   const pkgPath = path.join(packageRoot, 'package.json');
@@ -56,62 +55,29 @@ function resolvePluginDir() {
   return path.join(cwd, 'wp-content', 'plugins', 'sociallane-elements');
 }
 
-function main() {
-  const slug = getSlugFromPackage();
-  if (!existsSync(widgetDir)) {
-    console.error('Widget folder not found:', widgetDir);
-    process.exit(1);
-  }
-  if (!existsSync(path.join(widgetDir, `${slug}.php`))) {
-    console.error('Invalid widget: missing', path.join(widgetDir, `${slug}.php`));
-    process.exit(1);
+function runNpx(args, cwd) {
+  const r = spawnSync('npx', ['--yes', ...args], {
+    cwd,
+    stdio: 'inherit',
+    shell: true,
+  });
+  if (r.status !== 0) {
+    process.exit(r.status ?? 1);
   }
+}
 
+function main() {
+  const slug = getSlugFromPackage();
   const pluginDir = resolvePluginDir();
-  const widgetsDest = path.join(pluginDir, 'packages', 'widgets');
   const pluginExists = existsSync(path.join(pluginDir, 'sociallane-elements.php'));
 
   if (!pluginExists) {
     console.log('SocialLane Elements not found. Installing base plugin...');
-    const r = spawnSync('npx', ['--yes', '@sociallane/elements', '--minimal'], {
-      cwd: path.dirname(pluginDir),
-      stdio: 'inherit',
-      shell: true,
-    });
-    if (r.status !== 0) {
-      process.exit(r.status ?? 1);
-    }
+    runNpx(['@sociallane/elements', '--base', pluginDir], path.dirname(pluginDir));
   }
 
-  if (!existsSync(widgetsDest)) {
-    mkdirSync(widgetsDest, { recursive: true });
-  }
-
-  const dest = path.join(widgetsDest, slug);
-  cpSync(widgetDir, dest, { recursive: true, force: true });
-  console.log('Added widget:', slug);
-
-  console.log('Updating widgets.json and building...');
-  const syncResult = spawnSync('node', [path.join(pluginDir, 'scripts', 'sync-widgets.js')], {
-    cwd: pluginDir,
-    stdio: 'inherit',
-  });
-  if (syncResult.status !== 0) {
-    process.exit(syncResult.status ?? 1);
-  }
-
-  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const installResult = spawnSync(npmCmd, ['install'], {
-    cwd: pluginDir,
-    stdio: 'inherit',
-    shell: true,
-  });
-  if (installResult.status !== 0) {
-    if (installResult.error) {
-      console.error('Failed to run npm:', installResult.error.message);
-    }
-    process.exit(installResult.status ?? 1);
-  }
+  console.log('Adding widget:', slug);
+  runNpx(['@sociallane/elements', 'add', '--target', pluginDir, slug], path.dirname(pluginDir));
 
   console.log('');
   console.log('Done. Widget', slug, 'installed. Activate the plugin in WordPress → Plugins if needed.');

package/widgets/card-hover-reveal/data/view.php

@@ -108,7 +108,7 @@ function prepare_card_hover_reveal_view( array $settings, string $widget_id ): a
 	$columns   = in_array( $settings['columns'] ?? '3', [ '2', '3' ], true ) ? $settings['columns'] : '3';
 	$grid_class = $columns === '2'
 		? 'grid-cols-1 sm:grid-cols-2'
-		: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3';
+		: 'grid-cols-1 sm:grid-cols-2 md:grid-cols-3';
 
 	$animation = sociallane_animation_view_data( $settings, [ 'headline' => true, 'stagger' => true ] );
 

package/widgets/grid-components/data/view.php

@@ -30,7 +30,7 @@ function prepare_grid_components_view( array $settings, string $widget_id ): arr
 	$columns  = in_array( $settings['columns'] ?? '4', [ '2', '3', '4' ], true ) ? $settings['columns'] : '4';
 	$grid_class = [
 		'2' => 'grid-cols-1 sm:grid-cols-2',
-		'3' => 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
+		'3' => 'grid-cols-1 sm:grid-cols-2 md:grid-cols-3',
 		'4' => 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4',
 	][ $columns ];