meno-interactions 0.1.0

package/README.md

@@ -0,0 +1,611 @@
+# Meno Interactions
+
+Attribute-driven JavaScript interactions for Meno projects and static no-code sites.
+
+Meno already supports component JavaScript with vanilla DOM code scoped to the component root, and it supports interactive styles through state classes such as `.is-open` or `.is-scrolled`. This package gives no-code builders a reusable script they can add once, then control behavior with custom attributes in the Meno Attributes panel.
+
+## Install
+
+```bash
+npm install meno-interactions
+```
+
+Or use the browser files from `dist/` in a Meno project:
+
+```json
+{
+  "meta": {
+    "libraries": {
+      "js": [{ "url": "/libraries/meno-interactions.umd.js", "mode": "defer" }],
+      "css": [{ "url": "/libraries/meno-interactions.css" }]
+    }
+  }
+}
+```
+
+## CDN Setup
+
+After this package is published to npm, you can load it from a CDN with one CSS file and one deferred script.
+
+### Option 1: jsDelivr
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/meno-interactions/dist/meno-interactions.css">
+<script defer src="https://cdn.jsdelivr.net/npm/meno-interactions/dist/meno-interactions.umd.js"></script>
+```
+
+### Option 2: unpkg
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/meno-interactions/dist/meno-interactions.css">
+<script defer src="https://unpkg.com/meno-interactions/dist/meno-interactions.umd.js"></script>
+```
+
+### Option 3: Version-pin the CDN
+
+Pinning a version prevents future package updates from changing an already-launched site.
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/meno-interactions@0.1.0/dist/meno-interactions.css">
+<script defer src="https://cdn.jsdelivr.net/npm/meno-interactions@0.1.0/dist/meno-interactions.umd.js"></script>
+```
+
+### Add CDN Files in Meno
+
+In Meno, add the CDN URLs as page or project libraries. If editing JSON directly, put them in `meta.libraries`:
+
+```json
+{
+  "meta": {
+    "libraries": {
+      "css": [
+        { "url": "https://cdn.jsdelivr.net/npm/meno-interactions@0.1.0/dist/meno-interactions.css" }
+      ],
+      "js": [
+        { "url": "https://cdn.jsdelivr.net/npm/meno-interactions@0.1.0/dist/meno-interactions.umd.js", "mode": "defer" }
+      ]
+    }
+  }
+}
+```
+
+The script auto-initializes on page load. You do not need to write JavaScript for normal use.
+
+### Self-hosted CDN-style Setup
+
+If you do not want third-party CDN URLs, copy these files into your Meno project's `/libraries/` folder:
+
+- `dist/meno-interactions.umd.js`
+- `dist/meno-interactions.css`
+
+Then load them like this:
+
+```json
+{
+  "meta": {
+    "libraries": {
+      "css": [{ "url": "/libraries/meno-interactions.css" }],
+      "js": [{ "url": "/libraries/meno-interactions.umd.js", "mode": "defer" }]
+    }
+  }
+}
+```
+
+## Quick Use
+
+Add attributes in Meno's Attributes panel. For example, an accordion only needs a wrapper and trigger attributes:
+
+```html
+<div data-meno-accordion data-meno-single="true">
+  <button data-meno-accordion-trigger>Question</button>
+  <div>Answer</div>
+</div>
+```
+
+In Meno JSON, the same idea is represented through `attributes`:
+
+```json
+{
+  "type": "node",
+  "tag": "div",
+  "attributes": { "data-meno-accordion": "", "data-meno-single": "true" },
+  "children": [
+    {
+      "type": "node",
+      "tag": "button",
+      "attributes": { "data-meno-accordion-trigger": "" },
+      "children": "Question"
+    },
+    { "type": "node", "tag": "div", "children": "Answer" }
+  ]
+}
+```
+
+## Attribute Reference and Examples
+
+### Disclosure / Simple Toggle
+
+Use this for one button that opens or closes one nearby panel.
+
+```html
+<button data-meno-toggle data-meno-target="#details">Show details</button>
+<div id="details" hidden>
+  Extra content goes here.
+</div>
+```
+
+Attributes:
+
+- `data-meno-toggle`: marks the clickable trigger.
+- `data-meno-target="#details"`: optional selector for the panel. If omitted, the next sibling is used.
+
+State classes and attributes:
+
+- The panel receives `.is-open` when open.
+- The trigger receives `aria-expanded="true"` or `aria-expanded="false"`.
+- The panel `hidden` attribute is toggled.
+
+### Accordion
+
+Use this for FAQ rows or any stacked expandable content.
+
+```html
+<div data-meno-accordion data-meno-single="true">
+  <button data-meno-accordion-trigger>What is included?</button>
+  <div hidden>Everything needed for the starter setup.</div>
+
+  <button data-meno-accordion-trigger>Can I open many rows?</button>
+  <div hidden>Set data-meno-single="false" on the wrapper.</div>
+</div>
+```
+
+Attributes:
+
+- `data-meno-accordion`: marks the accordion wrapper.
+- `data-meno-accordion-trigger`: marks each clickable row header.
+- `data-meno-single="true"`: only one panel can be open at a time.
+- `data-meno-single="false"`: multiple panels can stay open.
+
+Panel rule:
+
+- Each trigger controls its next sibling unless the trigger has `aria-controls="panel-id"`.
+
+### Tabs
+
+Use this for switching between multiple panels.
+
+```html
+<div data-meno-tabs data-meno-initial-tab="overview">
+  <div role="tablist">
+    <button data-meno-tab="overview">Overview</button>
+    <button data-meno-tab="specs">Specs</button>
+    <button data-meno-tab="faq">FAQ</button>
+  </div>
+
+  <section data-meno-tab-panel="overview">Overview content.</section>
+  <section data-meno-tab-panel="specs">Specs content.</section>
+  <section data-meno-tab-panel="faq">FAQ content.</section>
+</div>
+```
+
+Attributes:
+
+- `data-meno-tabs`: marks the tab set wrapper.
+- `data-meno-tab="id"`: marks a tab button.
+- `data-meno-tab-panel="id"`: marks the matching panel.
+- `data-meno-initial-tab="id"`: optional initial tab. If omitted, the first tab is selected.
+
+State:
+
+- Active tab and panel receive `.is-active`.
+- Inactive panels receive `hidden`.
+- Buttons receive `aria-selected`.
+
+### Dropdown
+
+Use this for nav menus or compact option panels.
+
+```html
+<nav>
+  <button data-meno-dropdown="services">Services</button>
+  <div data-meno-dropdown-panel="services">
+    <a href="/design">Design</a>
+    <a href="/development">Development</a>
+  </div>
+</nav>
+```
+
+Attributes:
+
+- `data-meno-dropdown="services"`: trigger key.
+- `data-meno-dropdown-panel="services"`: matching panel key.
+
+State:
+
+- The panel receives `.is-open`.
+- The trigger receives `aria-expanded`.
+- Clicking outside the root closes open dropdowns.
+
+### Modal
+
+Use this for centered overlays, signup prompts, video popups, and confirmations.
+
+```html
+<button data-meno-open-modal="signup">Open signup</button>
+
+<div data-meno-modal="signup" data-meno-backdrop-close="true">
+  <div data-meno-modal-panel>
+    <button data-meno-close aria-label="Close">Close</button>
+    <h2>Join the list</h2>
+    <p>Modal content goes here.</p>
+  </div>
+</div>
+```
+
+Attributes:
+
+- `data-meno-open-modal="signup"`: opens a modal with the same key.
+- `data-meno-modal="signup"`: modal wrapper.
+- `data-meno-close`: closes the nearest modal.
+- `data-meno-backdrop-close="true"`: clicking the backdrop closes the modal.
+- `data-meno-backdrop-close="false"`: disables backdrop close.
+
+State:
+
+- The modal receives `.is-open`.
+- The modal `hidden` attribute is toggled.
+- Body scrolling is locked while a modal is open.
+- Escape closes open modals.
+
+### Drawer / Mobile Nav
+
+Use this for side panels, mobile menus, filter panels, or cart drawers.
+
+```html
+<button data-meno-open-drawer="menu">Menu</button>
+
+<aside data-meno-drawer="menu">
+  <button data-meno-close aria-label="Close menu">Close</button>
+  <a href="/">Home</a>
+  <a href="/about">About</a>
+</aside>
+```
+
+Attributes:
+
+- `data-meno-open-drawer="menu"`: opens a drawer with the same key.
+- `data-meno-drawer="menu"`: drawer wrapper.
+- `data-meno-close`: closes the drawer.
+
+Meno agent compatibility:
+
+- `data-action="toggle-mobile-nav"` is also treated as a drawer opener.
+- `data-action="open-drawer"` is also supported.
+
+State:
+
+- The drawer receives `.is-open`.
+- The drawer `hidden` attribute is toggled.
+- Body scrolling is locked while a drawer is open.
+- Escape closes open drawers.
+
+### Carousel
+
+Use this for horizontally scrolling cards, logos, images, or testimonials.
+
+```html
+<div data-meno-carousel>
+  <button data-meno-carousel-prev aria-label="Previous">Previous</button>
+
+  <div data-meno-carousel-track>
+    <article data-meno-carousel-item>Slide 1</article>
+    <article data-meno-carousel-item>Slide 2</article>
+    <article data-meno-carousel-item>Slide 3</article>
+  </div>
+
+  <button data-meno-carousel-next aria-label="Next">Next</button>
+</div>
+```
+
+Attributes:
+
+- `data-meno-carousel`: marks the carousel wrapper.
+- `data-meno-carousel-track`: marks the scrollable track.
+- `data-meno-carousel-item`: optional item marker for scroll snapping styles.
+- `data-meno-carousel-prev`: previous button.
+- `data-meno-carousel-next`: next button.
+
+Meno agent compatibility:
+
+- `data-el="carousel-track"` is also supported.
+- `data-action="carousel-prev"` and `data-action="carousel-next"` are also supported.
+
+Behavior:
+
+- Prev/next scroll by one item width.
+- The CSS file adds smooth horizontal scroll and scroll snapping.
+
+### Sticky Header
+
+Use this to add a class after the visitor scrolls.
+
+```html
+<header data-meno-sticky data-meno-sticky-threshold="16">
+  Site header
+</header>
+```
+
+Attributes:
+
+- `data-meno-sticky`: watches scroll position.
+- `data-meno-sticky-threshold="16"`: optional pixel threshold. Default is `8`.
+
+Meno agent compatibility:
+
+- `data-el="site-header"` is also treated as sticky.
+
+State:
+
+- The header receives `.is-scrolled` after the threshold.
+
+### Smooth Scroll
+
+Use this for in-page anchor navigation.
+
+```html
+<nav data-meno-smooth-scroll>
+  <a href="#features">Features</a>
+  <a href="#pricing">Pricing</a>
+</nav>
+
+<section id="features">Features content</section>
+<section id="pricing">Pricing content</section>
+```
+
+Attributes:
+
+- `data-meno-smooth-scroll`: put this on a wrapper containing anchor links, or directly on an anchor.
+
+Behavior:
+
+- Links starting with `#` scroll smoothly to matching element IDs.
+- The URL hash is updated without a full jump.
+
+### Copy to Clipboard
+
+Use this for copying codes, links, email addresses, or snippets.
+
+```html
+<code id="coupon">SAVE20</code>
+<button data-meno-copy="#coupon" data-meno-copied-label="Copied!">Copy code</button>
+```
+
+You can also copy a literal value without a source element:
+
+```html
+<button data-meno-copy data-meno-copy-text="hello@example.com">Copy email</button>
+```
+
+Attributes:
+
+- `data-meno-copy="#coupon"`: selector or ID of the source element.
+- `data-meno-copy-text="value"`: fallback literal text to copy.
+- `data-meno-copied-label="Copied!"`: temporary success label.
+- `data-meno-copy-timeout="1500"`: how long the success label stays, in milliseconds.
+
+Meno agent compatibility:
+
+- `data-action="copy"` and `data-copy-target="coupon"` are also supported.
+
+### Form State
+
+Use this for simple no-backend validation and success state.
+
+```html
+<form data-meno-form data-meno-success="Thanks, we received it.">
+  <label>
+    Email
+    <input name="email" type="email" required data-meno-error="Email is required">
+  </label>
+
+  <button type="submit">Submit</button>
+  <p data-meno-form-status></p>
+</form>
+```
+
+Attributes:
+
+- `data-meno-form`: marks a form for handling.
+- `data-meno-form-status`: element where error/success text appears.
+- `data-meno-success="message"`: success message.
+- `data-meno-reset-on-submit="true"`: reset form after success. Default is `true`.
+- `data-meno-reset-on-submit="false"`: keep form values after success.
+- `data-meno-error="message"`: field-level required error message.
+
+Behavior:
+
+- The package prevents default submission.
+- Required fields are checked.
+- A `meno:form-submit` event is dispatched with `{ data }`.
+- No network call is made. Wire your own backend by listening for `meno:form-submit`.
+
+### Lightbox
+
+Use this for image gallery zoom.
+
+```html
+<a href="/images/photo-large.webp" data-meno-open-lightbox data-meno-lightbox-alt="Project photo">
+  <img src="/images/photo-thumb.webp" alt="Project photo">
+</a>
+
+<div data-meno-lightbox hidden>
+  <button data-meno-close aria-label="Close">Close</button>
+  <img src="" alt="">
+</div>
+```
+
+Attributes:
+
+- `data-meno-open-lightbox`: opens the lightbox.
+- `data-meno-open-lightbox="/images/photo-large.webp"`: optional explicit image URL.
+- `data-meno-lightbox-alt="Text"`: alt text for the opened image.
+- `data-meno-lightbox`: lightbox wrapper.
+- `data-meno-close`: close button.
+
+State:
+
+- The lightbox receives `.is-open`.
+- The lightbox `hidden` attribute is toggled.
+
+### Generic Class Toggle
+
+Use this when you only need to add, remove, or toggle a class.
+
+```html
+<button data-meno-class-toggle="is-highlighted" data-meno-target="#card">
+  Toggle highlight
+</button>
+
+<article id="card">Card content</article>
+```
+
+Attributes:
+
+- `data-meno-class-toggle="class-name"`: toggles a class.
+- `data-meno-class-add="class-name"`: adds a class.
+- `data-meno-class-remove="class-name"`: removes a class.
+- `data-meno-target="#selector"`: optional target. If omitted, the clicked element is used.
+
+Examples:
+
+```html
+<button data-meno-class-add="is-open" data-meno-target="#panel">Open</button>
+<button data-meno-class-remove="is-open" data-meno-target="#panel">Close</button>
+<div id="panel">Panel</div>
+```
+
+### Custom Event Dispatch
+
+Use this to let no-code controls trigger custom JavaScript elsewhere.
+
+```html
+<button data-meno-dispatch="pricing:select">Choose plan</button>
+
+<script>
+  document.addEventListener('pricing:select', function (event) {
+    console.log('Selected from', event.detail.source);
+  });
+</script>
+```
+
+Attributes:
+
+- `data-meno-dispatch="event-name"`: dispatches a bubbling custom event from the clicked element.
+
+## MenoFilter
+
+MenoFilter is built into Meno and already works with attributes such as `data-meno-filter`, `data-meno-list`, `data-meno-search`, `data-meno-sort`, and `data-meno-page`. This package does not replace it; it complements it for UI interactions outside filtering.
+
+Common MenoFilter attributes:
+
+```html
+<div data-meno-filter="posts" data-meno-url-sync="true" data-meno-per-page="6">
+  <input data-meno-search data-meno-search-fields="title,excerpt" placeholder="Search">
+
+  <button data-meno-filter-field="category" data-meno-filter-value="Design">Design</button>
+  <button data-meno-clear>Clear</button>
+
+  <div data-meno-list>
+    <article data-category="Design" data-title="Example post">Example post</article>
+  </div>
+
+  <p><span data-meno-count="results"></span> results</p>
+  <div data-meno-empty>No results found.</div>
+</div>
+```
+
+## Interactive Styles Pattern
+
+Use the package to toggle state classes, then style those states in Meno `interactiveStyles` or component CSS.
+
+```json
+{
+  "interactiveStyles": [
+    {
+      "name": "Open panel",
+      "prefix": "",
+      "postfix": ".is-open",
+      "style": { "base": { "display": "block", "opacity": "1" } }
+    }
+  ]
+}
+```
+
+For child targets, put the interactive style on the target node and use a parent selector:
+
+```json
+{
+  "prefix": "[data-el='dropdown']:hover ",
+  "postfix": "",
+  "style": { "base": { "opacity": "1", "visibility": "visible" } }
+}
+```
+
+## Meno Agent Compatibility
+
+The script recognizes Meno agent conventions as aliases:
+
+| Agent convention | Package behavior |
+| --- | --- |
+| `data-action="toggle-accordion"` | Accordion trigger |
+| `data-action="select-tab"` | Tab trigger |
+| `data-el="tab-panel"` | Tab panel |
+| `data-action="toggle-dropdown"` | Dropdown trigger |
+| `data-el="dropdown-panel"` | Dropdown panel |
+| `data-action="open-modal"` | Modal trigger |
+| `data-action="close-modal"` | Modal close |
+| `data-action="open-drawer"` | Drawer trigger |
+| `data-action="close-drawer"` | Drawer close |
+| `data-action="toggle-mobile-nav"` | Drawer/mobile nav trigger |
+| `data-el="carousel-track"` | Carousel track |
+| `data-action="carousel-prev"` | Carousel previous |
+| `data-action="carousel-next"` | Carousel next |
+| `data-el="site-header"` | Sticky header |
+| `data-action="copy"` | Copy trigger |
+| `data-copy-target="id"` | Copy source |
+| `data-el="form-status"` | Form status element |
+
+## JavaScript API
+
+```js
+import { init, destroy, register } from 'meno-interactions';
+
+const app = init({ root: document });
+app.refresh();
+destroy();
+
+register('my-interaction', function (root) {
+  const button = root.querySelector('[data-my-button]');
+  if (!button) return [];
+  const handler = function () {
+    console.log('Clicked');
+  };
+  button.addEventListener('click', handler);
+  return [function () { button.removeEventListener('click', handler); }];
+});
+```
+
+The browser build exposes `window.MenoInteractions`:
+
+```html
+<script>
+  window.MenoInteractions.init();
+</script>
+```
+
+## Build
+
+```bash
+npm run build
+npm test
+```

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export interface MenoInteractionsOptions {
+  root?: Document | Element;
+  activeClass?: string;
+  openClass?: string;
+  scrolledClass?: string;
+  hiddenClass?: string;
+  reducedMotion?: boolean;
+}
+
+export interface MenoInteractionsInstance {
+  root: Document | Element | null;
+  destroy(): void;
+  refresh(): MenoInteractionsInstance;
+}
+
+export function init(options?: MenoInteractionsOptions): MenoInteractionsInstance;
+export function destroy(root?: Document | Element): void;
+export function register(name: string, initializer: (root: Document | Element, options: MenoInteractionsOptions) => Array<() => void> | void): void;
+
+export const MenoInteractions: {
+  init: typeof init;
+  destroy: typeof destroy;
+  register: typeof register;
+  version: string;
+};