=== MD3 Elementor Kit ===
Contributors:      angiesnippets
Tags:              elementor, material-design, material-design-3, md3, widgets, design-system, rtl, hebrew, dark-mode
Requires at least: 6.3
Tested up to:      6.7
Requires PHP:      8.0
Stable tag:        1.0.0
License:           GPLv2 or later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

A production-ready Elementor widget kit built on Material Design 3 (MD3) design tokens — with full RTL, Hebrew, and dark-mode support.

== Description ==

**MD3 Elementor Kit** brings Google's Material Design 3 system directly into Elementor's visual editor. Every widget ships with the full MD3 colour-role system, typescale tokens, shape scale, and elevation layers — all driven by CSS custom properties so you can theme globally from one place.

**Key features:**

* 30+ MD3 colour roles (primary, surface-container, error, inverse-surface, …) exposed as live CSS variables.
* Shape scale — None / Extra Small / Small / Medium / Large / Extra Large / Full (pill) — applied via `prefix_class` so you can override per-widget in a single CSS line.
* Elevation levels 0–5 with MD3-spec tonal surface overlay and box-shadow.
* State-layer ripple effect on all interactive widgets (pure JS, no jQuery).
* Focus-visible keyboard-navigation ring — appears only for keyboard users via `.md3-keyboard` body class.
* Full RTL / bidirectional layout support (`inset-inline-start/end`, logical properties throughout).
* Dark mode via `[data-theme="dark"]` or `prefers-color-scheme: dark` — zero extra markup.
* **Editor safety**: a dedicated editor stylesheet forces light-mode token fallbacks in the Elementor canvas and shows dashed overlays around state-layer elements to aid design.
* All strings translatable; Hebrew (he_IL) `.pot` template included.
* GPLv2+, zero external dependencies, no telemetry.

**Requires:** Elementor (free) 3.18+.
**Works with:** Elementor Pro, Hello Elementor, Astra, Kadence, GeneratePress.

== Installation ==

1. Upload the `md3-elementor-kit` folder to `/wp-content/plugins/`.
2. Activate the plugin via **Plugins > Installed Plugins**.
3. Open any page or template in Elementor. The **MD3** widget category appears in the widget panel.
4. (Optional) Enqueue a Material Symbols or Material Icons web-font in your theme for icon controls.

= Minimum requirements =

* WordPress 6.3+
* PHP 8.0+
* Elementor (free) 3.18+

== Frequently Asked Questions ==

= Does this require Elementor Pro? =

No. All widgets work with the free Elementor plugin. Some advanced layout features (Theme Builder, Display Conditions) become available if Elementor Pro is active, but are never required.

= How do I change the primary colour? =

Override the `--md-sys-color-primary` CSS custom property on `:root` in **Appearance > Customize > Additional CSS** (or your child theme's `style.css`). All colour-role variables cascade from there.

= Does it support RTL / Hebrew? =

Yes. All widgets use CSS logical properties (`margin-inline-start`, `padding-block-end`, etc.). Activate a Hebrew locale and Elementor's RTL mode together; the widgets flip automatically.

= Does dark mode work automatically? =

The kit ships with dark-mode token overrides inside `assets/css/md3-tokens.css` keyed to both `[data-theme="dark"]` and `@media (prefers-color-scheme: dark)`. Set `data-theme="dark"` on `<body>` (or let a theme-toggle JS snippet do it) and all widgets switch instantly.

= Can I use my own typescale (custom fonts)? =

Yes. Override the `--md-sys-typescale-*` variables in `:root`. The widgets read every typescale property (font-family, size, weight, line-height, letter-spacing) from those variables.

= The ripple effect does not appear. What's wrong? =

Ensure `assets/js/md3-base.js` is loading (check the Network tab). The interactive element must carry the class `md3-state-layer` — widgets add this automatically. If you are using a caching plugin, purge the JS cache.

= How do I report a bug or request a feature? =

Open an issue in the plugin's GitHub repository (linked in the plugin header) or contact support via the AngieSnippets website.

== Screenshots ==

1. Widget panel — the MD3 category with all registered widgets.
2. Card widget — shape, elevation, and colour-role controls in the Elementor Style tab.
3. Dark-mode demo — the same page in light and dark themes side by side.
4. RTL demo — Hebrew layout with correct bidirectional rendering.
5. Ripple effect — state-layer ripple on a button widget (screen recording frame).

== Changelog ==

= 1.0.0 — 2026-06-02 =
* Initial public release.
* Registered widget categories: MD3 Basics, MD3 Navigation, MD3 Data Display.
* Shipped widgets: Button, Card, Chip, FAB, Icon Button, Navigation Bar, Navigation Rail, Top App Bar, List, Divider, Badge, Tooltip, Progress Indicator, Snackbar, Dialog.
* MD3 token CSS: full colour-role system (light + dark), typescale, shape scale, elevation.
* Frontend JS: ripple effect, focus-visible keyboard bridge, Elementor widget-ready hook.
* Editor CSS: canvas readability, state-layer indicators, forced light-mode in editor canvas.
* RTL: all widgets pass logical CSS properties; Hebrew locale `.pot` included.
* Helpers class: `add_md3_style_section`, `color_role_options`, `role_var`, `typescale_var`, `state_layer_markup`, `font_family`, `wrap_selector`, `link_attrs`, `safe_icon`, `is_rtl_locale`.

== Upgrade Notice ==

= 1.0.0 =
First release — no upgrade steps needed.
