=== Emberly Popups ===
Contributors: emberlydigital
Tags: popup, modal, overlay, accessible, developer
Requires at least: 5.0
Tested up to: 6.8
Stable tag: 1.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Lightweight, accessible popups for WordPress—made by developers, for developers.

== Description ==

**Emberly Popups** is a simple PHP function that generates ARIA‑compliant modal popups. Great for newsletters, surveys, announcements, or any call‑to‑action:

* Auto‑open after a configurable delay  
* Cookie‑ or session‑based “show once” control  
* Repeat interval (milliseconds) between popups  
* Shortcode support inside popup content  
* Adjustable width and padding  
* Accessible markup with proper ARIA roles

== Installation ==

1. Copy the **emberly_popup()** function into your theme’s `functions.php` or a custom plugin.  
2. Enqueue or include the popup’s CSS and JS assets.  
3. Ensure `assets/icons/close.svg` exists (used for the close button).  
4. Call `emberly_popup()` anywhere in your PHP templates.

== Usage ==

=== PHP 8+ (named arguments) ===
```php
emberly_popup(
    title            : 'Welcome!',
    content          : '<p>Thanks for visiting our site. Don’t miss our latest offers!</p>',
    id               : 'welcome-popup',
    width            : '50rem',
    padding          : '3rem',
    echo             : true,
    output_shortcodes: true,
    auto_open        : true,
    delay            : 2000,
    show_once        : false,
    persistence_method: 'session',
    show_interval_ms : 1800000  // 30 minutes
);
```

=== PHP 7 & earlier (ordered arguments) ===
```php
emberly_popup(
    '',                               // $title
    '<p>Thanks for visiting our site. Don't miss our latest offers!</p>',
    'category-survey-popup',          // $id
    '50rem',                          // $width
    '3rem',                           // $padding
    true,                             // $echo
    true,                             // $output_shortcodes
    true,                             // $auto_open
    2000,                             // $delay
    false,                            // $show_once
    'session',                        // $persistence_method
    1800000                           // $show_interval_ms
);
```

=== Manual triggers ===  
Anywhere in your markup, add:
```html
<a href="#" em-popup-trigger-id="welcome-popup">Open Welcome Popup</a>
```
The `em-popup-trigger-id` value must match the `$id` you set in `emberly_popup()`.

== Parameters ==

| Parameter             | Type    | Default   | Description                                                                 |
|-----------------------|---------|-----------|-----------------------------------------------------------------------------|
| title                 | string  | ''        | Popup heading text.                                                         |
| content               | string  | ''        | HTML for the popup’s body.                                                  |
| id                    | string  | ''        | Unique popup identifier (required for cookies/sessions & triggers).         |
| width                 | string  | '60rem'   | CSS max-width for the popup container.                                       |
| padding               | string  | '3rem'    | Inner padding inside the popup.                                              |
| echo                  | bool    | true      | Echo the markup immediately (false to return as string).                     |
| output_shortcodes     | bool    | false     | Process WordPress shortcodes in `content`.                                   |
| auto_open             | bool    | false     | Automatically open after `delay` ms.                                         |
| delay                 | int     | 0         | Milliseconds to wait before auto-open.                                       |
| show_once             | bool    | false     | If true, shows only once per session/cookie period.                          |
| persistence_method    | string  | 'cookie'  | Where to store “shown” flag: 'cookie' or 'session'.                           |
| show_interval_ms      | int     | 0         | Minimum interval (ms) before showing again. 0 disables repeats.              |
| debug                 | bool    | false     | Log internal events to browser console (load, open, cookies, scroll lock).   |

== Debugging ==

Add `debug: true` (PHP 8+) or append `true` as the 13th argument (PHP 7) to enable console logging:

```php
// PHP 8+ example
emberly_popup(
    title : 'Debug Popup',
    content: '<p>Debugging is on!</p>',
    id    : 'debug-popup',
    debug : true
);
```

== Frequently Asked Questions ==

= What if I don’t set an ID? =
An ID is required for cookies/sessions and manual triggers; omit at your own risk.

= Can I use shortcodes in my popup? =
Yes—set `output_shortcodes` to `true`.

== Changelog ==

= 1.3 =
* Fixed minor CSS selector issue in nested themes.
* Added `debug` parameter to PHP 7 ordered args example.
* Improved README formatting for WP.org.
* Fixed trigger logging order. Now logs triggers before content by moving the trigger handler up to the body.
* Added compatibility to override smooth scrolling when closing a popup.

= 1.2 =
* Added `debug` logging support.
* Support for PHP 8 named arguments.

= 1.0 =
* Initial public release.

== Upgrade Notice ==

= 1.3 =
Make sure to rebuild assets if you override CSS/JS; no breaking changes.

== Screenshots ==
No screenshots yet. Feel free to submit one via the support forum!
