@sociallane/elements 1.0.0

package/docs/npm-widget-cheatsheet.md

@@ -0,0 +1,178 @@
+# npm Widget Import Cheatsheet
+
+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
+
+# Dev watch (rebuilds on file change)
+npm run dev
+```
+
+**Important:** `npm run build` is required. Tailwind scans the plugin root (`packages/widgets/`, `elements/`) for PHP templates and only outputs utility classes it finds. Without a build, widgets render unstyled.
+
+---
+
+## Widget selection
+
+Edit `widgets.json` at plugin root:
+
+```json
+{
+  "widgets": [
+    "hero-split",
+    "hero-overlay",
+    "content-block",
+    "faq"
+  ]
+}
+```
+
+Only slugs listed here are loaded. Add or remove as needed.
+
+---
+
+## Widget → npm package & command
+
+Every widget and its npm package / add command:
+
+| Widget | Package | Command |
+|--------|---------|---------|
+| bento-grid | `@sociallane/widget-bento-grid` | `npm install @sociallane/widget-bento-grid` |
+| bento-portfolio | `@sociallane/widget-bento-portfolio` | `npm install @sociallane/widget-bento-portfolio` |
+| blog-grid | `@sociallane/widget-blog-grid` | `npm install @sociallane/widget-blog-grid` |
+| card-hover-reveal | `@sociallane/widget-card-hover-reveal` | `npm install @sociallane/widget-card-hover-reveal` |
+| client-logos | `@sociallane/widget-client-logos` | `npm install @sociallane/widget-client-logos` |
+| content-block | `@sociallane/widget-content-block` | `npm install @sociallane/widget-content-block` |
+| 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` |
+| 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` |
+| footer | `@sociallane/widget-footer` | `npm install @sociallane/widget-footer` |
+| footer-brand | `@sociallane/widget-footer-brand` | `npm install @sociallane/widget-footer-brand` |
+| footer-links-contact | `@sociallane/widget-footer-links-contact` | `npm install @sociallane/widget-footer-links-contact` |
+| 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` |
+| grid-team | `@sociallane/widget-grid-team` | `npm install @sociallane/widget-grid-team` |
+| grid-testimonials | `@sociallane/widget-grid-testimonials` | `npm install @sociallane/widget-grid-testimonials` |
+| 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-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` |
+| 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` |
+| 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` |
+| sales-dashboard | `@sociallane/widget-sales-dashboard` | `npm install @sociallane/widget-sales-dashboard` |
+| section-stats | `@sociallane/widget-section-stats` | `npm install @sociallane/widget-section-stats` |
+| 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` |
+| testimonial-quote | `@sociallane/widget-testimonial-quote` | `npm install @sociallane/widget-testimonial-quote` |
+
+Then add the slug to `widgets.json`.
+
+---
+
+## Available widget slugs (by category)
+
+| 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` |
+| 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` |
+
+---
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Build core (Tailwind + animations) |
+| `npm run dev` | Watch build for core |
+| `npm run build:all` | Build all workspaces |
+| `npm run build:core` | Alias for core build |
+
+---
+
+## Workspace packages
+
+- **@sociallane/core** — Required. Theme, animations, PHP bootstrap. Tailwind `@source` scans the full plugin root so widget utilities are included in the build.
+- **@sociallane/widget-{slug}** — Optional. One per widget (e.g. `@sociallane/widget-hero-split`).
+
+Widget packages are peer-dependent on core; no separate build needed for most widgets. Run `npm run build` from plugin root after install.
+
+---
+
+## Fresh setup
+
+```bash
+cd wp-content/plugins/sociallane-elements
+
+# 1. Install dependencies (core + all widget packages)
+npm install
+
+# 2. Build core — REQUIRED for styled widgets
+#    Tailwind scans packages/widgets/, elements/ for PHP templates
+npm run build
+
+# 3. Edit widgets.json with desired slugs
+```
+
+---
+
+## Reducing widgets
+
+1. Edit `widgets.json` — keep only the slugs you want.
+2. Optionally remove widget dirs from `packages/widgets/` (e.g. if using git submodules).
+3. Run `npm run build` to refresh Tailwind output (scans current templates).
+
+---
+
+## Troubleshooting
+
+### Widgets unstyled
+
+Run `npm run build`. Tailwind only outputs utility classes it finds when scanning `packages/widgets/` and `elements/`.
+
+### Tailwind not loading
+
+If Tailwind styles don’t appear, the plugin may be trying to load from the Vite dev server instead of the built files.
+
+**Quick fix** — add to `wp-config.php`:
+
+```php
+define( 'SOCIALLANE_ELEMENTS_VITE_PRODUCTION', true );
+```
+
+This forces use of built assets in `packages/core/assets/dist/`.
+
+Then ensure the build has run:
+
+```bash
+npm run build
+```

package/docs/package-installation.md

@@ -0,0 +1,127 @@
+# Package Installation (npm / Git Submodules)
+
+SocialLane Elements uses a modular package layout so you can load only the widgets you need per instance.
+
+> **New instance?** See [install-new-instance.md](install-new-instance.md) to clone the plugin into a fresh WordPress site.
+
+## Structure
+
+- **packages/core** — Shared Tailwind theme, GSAP animations, PHP traits, and plugin bootstrap. Required.
+- **packages/widgets/{slug}** — One directory per widget (e.g. `hero-split`, `faq`). Each has its own `package.json` and optional assets.
+
+## Loading which widgets
+
+- **widgets.json** (plugin root) — List of widget slugs to register. If this file exists, only these widgets are loaded.
+- If `widgets.json` is missing, the loader falls back to the Widget Manager enabled list (onboarding/settings).
+
+### Package mode (when widgets.json exists)
+
+When `widgets.json` is present, the plugin runs in **package mode**. Only the widget components are available:
+
+- **Available:** Widget components (Elementor widgets), core assets (Tailwind, GSAP), elements (Button, Image).
+- **Not available:** Onboarding wizard, SocialLane admin settings page, widget preview pages (`/widget-preview/...`), setup widget catalog shortcode. These features are disabled so that NPM/git-submodule installations get components only, with no admin UI or previews.
+
+If you need the full admin (widget management, previews, onboarding), remove or rename `widgets.json`; the plugin will then use the Widget Manager and show all admin features.
+
+Edit `widgets.json` to include only the widget slugs you want. You can also let the plugin keep it in sync automatically (see below).
+
+### Syncing widgets.json with packages/widgets (automated)
+
+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.
+- **Manual sync** — From the plugin root run:
+  ```bash
+  npm run sync-widgets
+  ```
+  Use this after adding/removing widget packages by hand (e.g. git submodule add/remove) so you don’t have to edit `widgets.json` yourself.
+
+```json
+{
+  "widgets": [
+    "hero-split",
+    "hero-overlay",
+    "content-block",
+    "faq"
+  ]
+}
+```
+
+## Git submodules (selective widgets)
+
+Use submodules so each WordPress instance only has the core package and the widget packages it needs.
+
+1. Clone or use the main plugin repo (with `packages/core` and optionally some `packages/widgets/*`).
+
+2. To use **only** core and a few widgets via submodules:
+   - Ensure `packages/core` is present (required).
+   - Add widget packages as submodules only where you need them, e.g.:
+
+   ```bash
+   cd wp-content/plugins/sociallane-elements
+
+   # Core is required (may already be in repo or added as submodule)
+   git submodule add <url-to-sociallane-core> packages/core
+
+   # 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
+   ```
+
+3. Update **widgets.json** so its `widgets` array lists only the slugs you added (e.g. `hero-split`, `faq`).
+
+4. Install and build from plugin root (both required for styled widgets):
+
+   ```bash
+   npm install
+   npm run build
+   ```
+
+   Tailwind scans the full plugin root (`packages/widgets/`, `elements/`) for PHP templates and outputs utility classes used in them. Without `npm run build`, widgets render unstyled.
+
+5. After clone, init/update submodules:
+
+   ```bash
+   git submodule update --init --recursive
+   npm install
+   npm run build
+   ```
+
+## npm workspaces
+
+From the plugin root:
+
+- `npm install` — Installs core and all widget package dependencies.
+- `npm run build` — **Required.** Builds core (Tailwind + animations). Tailwind `@source` scans the plugin root (`packages/widgets/`, `elements/`) so the output includes utility classes used in widget templates. Skip this and widgets are unstyled.
+- `npm run dev` — Watch build for core.
+- `npm run build:all` — Build all workspaces (core and any widget that defines a build).
+- `npm run reinstall` — Removes `node_modules` and runs `npm install` (and postinstall build). Use when dependencies are broken or you want a clean install.
+- `npm run sync-widgets` — Updates `widgets.json` from `packages/widgets/` (add new slugs, remove missing ones). Runs automatically on postinstall.
+
+Widget packages declare a peer dependency on `@sociallane/core`. Most widgets have no custom CSS/JS and rely on core’s build.
+
+### Uninstall and reinstall
+
+To fully uninstall and reinstall the npm package (e.g. after changing Node version or fixing a bad install):
+
+```bash
+cd wp-content/plugins/sociallane-elements
+npm run reinstall
+```
+
+Or manually: delete `node_modules`, then run `npm install`. On Windows: `rmdir /s /q node_modules` then `npm install`. After install, `postinstall` runs `npm run build` automatically.
+
+### Publishing to npm (maintainers)
+
+The plugin is published as `@sociallane/elements`. To publish:
+
+1. Log in: `npm login` (use an account with access to the `@sociallane` scope).
+2. Bump version if needed: edit `version` in `package.json` or run `npm version patch|minor|major`.
+3. Publish: `npm publish --access public` (required for scoped packages the first time).
+
+`.npmignore` excludes `node_modules`, `.git`, and dev files so the tarball contains plugin source and `packages/`. Consumers run `npm install` in the plugin directory after copying to `wp-content/plugins` to install workspaces and trigger the build.
+
+## Adding a new widget package
+
+1. Add the widget directory under `packages/widgets/{slug}` with `{slug}.php`, `data/`, `templates/`, and `package.json` (see existing widgets).
+2. Add the slug to `widgets.json` if you use it to control which widgets load.

package/docs/widgets/blog-grid.md

@@ -0,0 +1,31 @@
+# Blog Grid
+
+## Overview
+Article cards with category tag overlay on the featured image, date (with calendar icon),
+title, excerpt, and read-more link. Centered section header (title + subtitle) and CTA
+button below the grid. Matches the "Laatste Inzichten" / Latest Insights design.
+
+## Setup
+- Registered as the `blog-grid` widget in `widgets/blog-grid/blog-grid.php`.
+- Query: posts from WordPress `post` type; configure count, order, categories, offset.
+- Header: heading, heading tag, subtitle (all with show/hide toggles).
+- CTA: button text, URL (with show/hide toggle).
+- Display: image, category tag, date, excerpt, excerpt length, read-more text.
+- Layout: 2, 3, or 4 columns.
+
+## Dependencies
+- `sociallane_prepare_button_data()` for CTA button.
+- `sociallane_animation_view_data()` for GSAP animations.
+- Button element at `elements/button/templates/render.php`.
+- Image element at `elements/image/templates/render.php`.
+- Tailwind styles in `assets/css/tailwind.css`.
+
+## Critical Knowledge
+- Category tag is overlaid on the image (top-left, oval, dark translucent bg).
+  When no featured image is present, the category is shown as a pill above the date.
+- Cards use white background, rounded corners, shadow, and hover shadow.
+- Read-more link uses blue-chill color and right-arrow SVG.
+- CTA button uses light grey background (neutral-200) and chevron icon.
+
+## Change Log
+- 2026-02-07: Initial creation (renamed from grid-insights).

package/docs/widgets/card-hover-reveal.md

@@ -0,0 +1,27 @@
+# Card Hover Reveal
+
+## Overview
+Repeatable cards in a grid; each card has an image and, on hover, a backdrop-blur bar
+fades up from the bottom with title (name), optional description (role), and optional CTA.
+GSAP animates the bar and content; section and grid use scroll reveal + stagger. Respects `prefers-reduced-motion`.
+
+## Setup
+- Registered as the `card-hover-reveal` widget in `widgets/card-hover-reveal/card-hover-reveal.php`.
+- **Cards** (repeater): Per card: image, alt, optional link; show title, title, title tag; show description, description; show CTA, button text/URL/style.
+- **Layout**: Card aspect ratio (16:9, 4:3, 3:2, 1:1, 3:4); columns (2 or 3).
+
+## Dependencies
+- `sociallane_prepare_image_data()`, `sociallane_prepare_button_data()` for data normalization.
+- Button element at `elements/button/templates/render.php`.
+- GSAP hover-reveal: `assets/js/utilities/hover-reveal.js` (initialized from `animations.js`).
+- Tailwind: `.card-hover-reveal__bar` initial state in `assets/css/tailwind.css`.
+
+## Critical Knowledge
+- **data-sl-hover-reveal**: Root container; `initHoverReveal()` binds mouseenter/mouseleave/focusin/focusout.
+- **data-sl-hover-reveal-bar**: The blur bar; GSAP animates `yPercent: 100 → 0` and `opacity: 0 → 1`.
+- **data-sl-hover-reveal-item**: Children inside the bar; stagger animation (opacity + y).
+- Bar is hidden by default via CSS (`transform: translateY(100%); opacity: 0`) so there is no flash before GSAP runs. When `prefers-reduced-motion: reduce`, bar and content are shown immediately (no animation).
+
+## Change Log
+- 2026-02-07: Converted to repeatable cards in a grid; layout (aspect ratio, columns); stagger animation on grid.
+- 2026-02-07: Initial widget: image card with hover-reveal backdrop bar and GSAP animation.

package/docs/widgets/cta-banner.md

@@ -0,0 +1,31 @@
+# CTA Banner
+
+## Overview
+Full-width banner with background image and a lower CTA block: dark overlay
+covering roughly the bottom 45–50% of the image, centered headline, description,
+and contact info (phone and email with icons, optional separator). Optional
+primary button. Matches the design with dark slate blue overlay, white text,
+and teal/cyan icons.
+
+## Setup
+- Registered as the `cta-banner` widget in `widgets/cta-banner/cta-banner.php`.
+- **Background**: Background image, alt text, minimum section height (50vh–100vh).
+- **Content**: Show/hide headline, headline text, tag (H1–H3), show/hide description, description text.
+- **Contact**: Show/hide phone, phone number, optional custom phone link URL; show/hide email, email address.
+- **Button**: Optional show/hide CTA button, label, URL.
+- **Layout**: CTA block height as percentage of section (40–60%).
+
+## Dependencies
+- `sociallane_prepare_image_data()`, `sociallane_prepare_button_data()`, `sociallane_show_field()`, `sociallane_sanitize_text()`, `sociallane_validate_heading_tag()`, `sociallane_animation_view_data()`, `sociallane_section_animation_attrs()` from `includes/helpers.php`.
+- Button element at `elements/button/templates/render.php`.
+- Animation_Controls trait (section reveal only; no headline/stagger).
+- Tailwind: `blue-chill-*` overlay and icon colors in `assets/css/tailwind.css`.
+
+## Critical Knowledge
+- Overlay is absolutely positioned at bottom of section; section has explicit `height` (same as `min_height`) so overlay’s percentage height works.
+- Phone link: uses custom URL if set, otherwise `tel:` from the phone number.
+- Email link: `mailto:` from email address.
+- All color/theme classes live in `data/view.php` (`$view['classes']`); template only echoes them (light/dark prepared).
+
+## Change Log
+- 2026-02-07: Initial widget: background image, lower CTA block, headline, description, phone/email with icons, optional button.

package/docs/widgets/cta-split.md

@@ -0,0 +1,26 @@
+# CTA Split
+
+## Overview
+Two-column section: **left** = dark slate panel (~#2E3E4C) with headline, description, and contact (phone | email) with teal icons and text (#34D399). **Right** = full-height image, no overlay, object-cover. Clean split layout; on mobile content stacks (content first, then image).
+
+## Setup
+- Registered as the `cta-split` widget in `widgets/cta-split/cta-split.php`.
+- **Content**: Show/hide headline, headline text, headline tag (H1–H3). Show/hide description, description text.
+- **Contact**: Show/hide phone, phone number, optional phone URL; show/hide email, email address. Rendered as phone | email with teal icon + text, left-aligned.
+- **Image**: Right column image with alt text.
+- **Layout**: Minimum section height (40vh–100vh). Desktop: fixed height so image fills column; mobile: auto height.
+
+## Dependencies
+- `sociallane_show_field()`, `sociallane_sanitize_text()`, `sociallane_validate_heading_tag()`, `sociallane_prepare_image_data()`, `sociallane_animation_view_data()`, `sociallane_section_animation_attrs()`, `sociallane_headline_animation_attrs()` from `includes/helpers.php`.
+- Animation_Controls trait (section reveal + headline only).
+- Image element at `elements/image/templates/render.php`.
+- Tailwind: `blue-chill-900` for left panel, `emerald-400` for contact/icon.
+
+## Critical Knowledge
+- All color/theme classes live in `data/view.php` (`$view['classes']`); template only echoes them.
+- Section uses inline `min-height` and `height` (same value) on desktop so the right column can be `h-full`; `max-lg:!h-auto` overrides height on mobile so the section grows with stacked content.
+- Left column uses `grid-cols-[minmax(0,1.25fr)_minmax(0,1fr)]` so left is ~55%, right ~45%.
+- Contact block: vertical bar `|` separator between phone and email; both use same teal for icon and text.
+
+## Change Log
+- 2026-02-07: Initial widget: split layout, dark left panel, headline, description, phone | email (teal), full-height image right.

package/docs/widgets/faq.md

@@ -0,0 +1,31 @@
+# FAQ
+
+## Overview
+Accordion-style FAQ widget with stacked, split, and centered layouts. Supports
+optional section title/description, per-item buttons, and FAQPage JSON-LD schema
+for SEO.
+
+## Setup
+- Registered as the `faq` widget in `widgets/faq/faq.php`.
+- Configure items in the repeater: Question, Answer, optional Button Label/Link.
+- Layout options: `stacked`, `split`, `centered`. Split layout supports header
+  position (left/right).
+- "First item open by default" opens the first displayed item.
+
+## Dependencies
+- `sociallane_prepare_button_data()` for button data normalization.
+- Button element template at `elements/button/templates/render.php`.
+- Tailwind styles in `assets/css/tailwind.css` (FAQ accordion transitions).
+
+## Critical Knowledge
+- The accordion partial runs in a shared include scope. Local FAQ class data is
+  stored in `$faq_classes` to avoid collisions with the button template’s
+  `$classes` variable.
+- In stacked layout, items are split into two columns; the first visible item
+  opens when the "first open" toggle is enabled.
+- If a button label is empty, the button is not rendered; links are sanitized
+  in the data layer.
+
+## Change Log
+- 2026-02-07: Prevented button template variable collision and ensured the first
+  displayed item opens when enabled.

package/docs/widgets/feature-list.md

@@ -0,0 +1,21 @@
+# Feature List
+
+## Overview
+Section with one main heading (top-left) and a list of items, each with a teal checkmark icon. Items can be shown in one or two columns. Light background (~#F8F8F8), dark title, lighter body text, emerald checkmarks. Reusable for services, features, or help topics (e.g. “What can we help you with?”).
+
+## Setup
+- Registered as the `feature-list` widget in `widgets/feature-list/feature-list.php`.
+- **Content**: Show/hide title, title text, title tag (H1–H3). Repeater for list items (label only).
+- **Layout**: Columns 1 or 2 (2-column layout on large screens with wide gap).
+
+## Dependencies
+- `sociallane_animation_view_data()`, `sociallane_section_animation_attrs()`, `sociallane_headline_animation_attrs()`, `sociallane_stagger_attrs()` from `includes/helpers.php`.
+- Animation_Controls trait (section reveal, headline, stagger).
+- Tailwind: `neutral-100`, `zinc-*`, `emerald-500` for section, text, and icon; `max-w-7xl` container.
+
+## Critical Knowledge
+- All color/theme classes live in `data/view.php` (`$view['classes']`); template only echoes them.
+- Section is `aria-labelledby` when title is shown; list is semantic `<ul>` with list-style removed.
+
+## Change Log
+- 2026-02-07: Initial widget: heading, repeater items, teal checkmarks, 1/2 columns, headline + stagger animation.

package/docs/widgets/footer-links-contact.md

@@ -0,0 +1,24 @@
+# Footer Links & Contact
+
+## Overview
+Reusable dark footer: logo column (text + optional subtitle + dot, or image), link columns from a WordPress menu, contact column (address, phone, email with icons), and bottom bar (optional social link — LinkedIn/Twitter/Instagram — copyright, footer links repeater). Content constrained to container width (max-w-7xl). No client-specific naming or defaults.
+
+## Setup
+- Registered as the `footer-links-contact` widget in `widgets/footer-links-contact/footer-links-contact.php`.
+- **Logo**: Text (main + optional subtitle + optional dot) or image; logo link URL. Default text: "Lorem".
+- **Link columns**: One WordPress menu; top-level items = column headings, children = links.
+- **Contact**: Heading, address line 1 & 2, phone, email (placeholders only; no client copy).
+- **Bottom bar**: Show social (icon: LinkedIn, Twitter, or Instagram; URL), copyright text, repeater "Footer Links" (label + URL). Default links: "Privacy Policy", "Terms of Use". Default copyright: "© 2026 Lorem ipsum. All rights reserved."
+
+## Dependencies
+- `sociallane_footer_menu_to_columns()` from `includes/footer-menu-columns.php`.
+- `sociallane_animation_view_data()`, `sociallane_section_animation_attrs()` from `includes/helpers.php`.
+- Animation_Controls trait (section reveal only).
+
+## Critical Knowledge
+- All color/theme classes live in `data/view.php` (`$view['classes']`); templates only echo them (light/dark prepared).
+- Grid: logo column wider (1.5fr), then link columns (1fr each), then contact (1fr).
+- Bottom bar: social icon is configurable (LinkedIn, Twitter, Instagram); "Footer Links" repeater is generic (privacy, terms, or any links).
+
+## Change Log
+- 2026-02-07: Renamed from footer-legal to footer-links-contact; generic naming, placeholder defaults, bottom_links repeater, optional social icon (LinkedIn/Twitter/Instagram).

package/elements/button/button.php

@@ -0,0 +1,161 @@
+<?php
+/**
+ * Element: Button
+ *
+ * A reusable button element with multiple variants and sizes.
+ * Available as standalone Elementor widget AND as includable template.
+ *
+ * @package SocialLane_Elements
+ */
+
+namespace SocialLane\Elements;
+
+use Elementor\Widget_Base;
+use Elementor\Controls_Manager;
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Button Element
+ */
+class Button extends Widget_Base {
+
+	public function get_name(): string {
+		return 'button';
+	}
+
+	public function get_title(): string {
+		return esc_html__( 'Button', 'sociallane-elements' );
+	}
+
+	public function get_icon(): string {
+		return 'eicon-button';
+	}
+
+	public function get_categories(): array {
+		return [ 'sociallane-elements' ];
+	}
+
+	public function get_keywords(): array {
+		return [ 'button', 'link', 'cta', 'action' ];
+	}
+
+	protected function register_controls(): void {
+		$this->start_controls_section(
+			'section_button',
+			[
+				'label' => esc_html__( 'Button', 'sociallane-elements' ),
+			]
+		);
+
+		$this->add_control(
+			'text',
+			[
+				'label'   => esc_html__( 'Text', 'sociallane-elements' ),
+				'type'    => Controls_Manager::TEXT,
+				'default' => esc_html__( 'Click Here', 'sociallane-elements' ),
+			]
+		);
+
+		$this->add_control(
+			'url',
+			[
+				'label' => esc_html__( 'URL', 'sociallane-elements' ),
+				'type'  => Controls_Manager::URL,
+			]
+		);
+
+		$this->add_control(
+			'variant',
+			[
+				'label'   => esc_html__( 'Style', 'sociallane-elements' ),
+				'type'    => Controls_Manager::SELECT,
+				'default' => 'primary',
+				'options' => [
+					'primary'   => esc_html__( 'Primary', 'sociallane-elements' ),
+					'secondary' => esc_html__( 'Secondary', 'sociallane-elements' ),
+					'ghost'     => esc_html__( 'Ghost', 'sociallane-elements' ),
+					'outline'   => esc_html__( 'Outline', 'sociallane-elements' ),
+				],
+			]
+		);
+
+		$this->add_control(
+			'color',
+			[
+				'label'   => esc_html__( 'Color', 'sociallane-elements' ),
+				'type'    => Controls_Manager::SELECT,
+				'default' => 'default',
+				'options' => function_exists( 'sociallane_get_button_color_options' ) ? sociallane_get_button_color_options() : [ 'default' => esc_html__( 'Default (brand)', 'sociallane-elements' ) ],
+				'description' => esc_html__( 'Same style, different accent.', 'sociallane-elements' ),
+			]
+		);
+
+		$this->add_control(
+			'size',
+			[
+				'label'   => esc_html__( 'Size', 'sociallane-elements' ),
+				'type'    => Controls_Manager::SELECT,
+				'default' => 'md',
+				'options' => [
+					'sm' => esc_html__( 'Small', 'sociallane-elements' ),
+					'md' => esc_html__( 'Medium', 'sociallane-elements' ),
+					'lg' => esc_html__( 'Large', 'sociallane-elements' ),
+				],
+			]
+		);
+
+		$this->add_control(
+			'icon',
+			[
+				'label' => esc_html__( 'Icon', 'sociallane-elements' ),
+				'type'  => Controls_Manager::ICONS,
+			]
+		);
+
+		$this->add_control(
+			'icon_position',
+			[
+				'label'   => esc_html__( 'Icon Position', 'sociallane-elements' ),
+				'type'    => Controls_Manager::SELECT,
+				'default' => 'right',
+				'options' => [
+					'left'  => esc_html__( 'Left', 'sociallane-elements' ),
+					'right' => esc_html__( 'Right', 'sociallane-elements' ),
+				],
+			]
+		);
+
+		$this->end_controls_section();
+	}
+
+	protected function render(): void {
+		$settings = $this->get_settings_for_display();
+
+		$url_data = $settings['url'] ?? [];
+		$button   = [
+			'text'          => esc_html( $settings['text'] ?? '' ),
+			'url'           => esc_url( $url_data['url'] ?? '#' ),
+			'variant'       => $settings['variant'] ?? 'primary',
+			'size'          => $settings['size'] ?? 'md',
+			'color'         => $settings['color'] ?? 'default',
+			'icon'          => $settings['icon'] ?? null,
+			'icon_position' => $settings['icon_position'] ?? 'right',
+			'attrs'         => '',
+		];
+
+		$attrs = [];
+		if ( ! empty( $url_data['is_external'] ) ) {
+			$attrs[] = 'target="_blank"';
+			$attrs[] = 'rel="noopener noreferrer"';
+		}
+		if ( ! empty( $url_data['nofollow'] ) ) {
+			$attrs[] = 'rel="nofollow"';
+		}
+		$button['attrs'] = implode( ' ', $attrs );
+
+		include __DIR__ . '/templates/render.php';
+	}
+}