@fest-lib/lure 0.1.48 → 0.1.50

package/README.md

@@ -1,305 +1,98 @@
-<h1 align="center">🌀 LUR-E 🌀</h1>
-<p align="center"><img src="./assets/logo/logo-0.png" width="128" alt="LUR-E Logo"/></p>
-
----
+<h1 align="center">🌀 LUR.E</h1>
+<p align="center"><img src="./assets/logo/logo-0.png" width="128" alt="LUR.E"></p>
 
 <p align="center">
-  <a href="https://github.com/fest-live/lur.e/blob/main/LICENSE"><img src="https://img.shields.io/github/license/fest-live/lur.e?style=flat-square" alt="License"/></a>
-  <a href="https://github.com/fest-live/lur.e/stargazers"><img src="https://img.shields.io/github/stars/fest-live/lur.e?style=flat-square" alt="GitHub stars"/></a>
-  <a href="https://github.com/fest-live/lur.e/commits/main"><img src="https://img.shields.io/github/last-commit/fest-live/lur.e?style=flat-square" alt="Last Commit"/></a>
-  <a href="https://github.com/fest-live/lur.e/issues"><img src="https://img.shields.io/github/issues/fest-live/lur.e?style=flat-square" alt="Issues"/></a>
+  <a href="https://www.npmjs.com/package/@fest-lib/lure"><img src="https://img.shields.io/npm/v/@fest-lib/lure?style=flat-square" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@fest-lib/lure?style=flat-square" alt="MIT"></a>
+  <a href="https://github.com/fest-live/lur.e"><img src="https://img.shields.io/github/stars/fest-live/lur.e?style=flat-square" alt="stars"></a>
 </p>
 
-## Overview
-
-`@fest-lib/lure` (LUR.E) is the fest-lib reactive DOM layer. It binds `@fest-lib/object` refs to real nodes (`E`, `H`, `M`, `Q`, `T`, `C`, `S`), form/input observers, overlay placement, and drag helpers. Web components and CSS-in-JS (`S`) are first-class.
-
----
-
-## ✨ Features
-
-- **Efficient Memory Management**
-- **Advanced Cache & Reaction System**
-- **Low-Level DOM Manipulation**
-- **Full CSS Compatibility**
-- **Web Components Support**
-- **Experimental Typed OM**
-- **Attribute Mutation Observer**
-- **Reactive Input Handling**
-
----
+`@fest-lib/lure` — level 2 reactive DOM. Binds `@fest-lib/object` refs to real nodes (`E`, `H`, `M`, `Q`, `T`, `C`, `S`), forms, overlays, and drag. Web components and CSS-in-JS (`S`) are first-class.
 
-## 📦 Installation
-
-```
-npm install @fest-lib/core
-npm install @fest-lib/object
-npm install @fest-lib/dom
-npm install @fest-lib/uniform
-npm install @fest-lib/lure
+```text
+core · dom · object · uniform
+ └── fest/lure        ← you are here
+      └── icon · image · veela · fl-ui
 ```
 
-- Where last line is main library...
-- Other previously is dependencies.
-
----
-
-## 🔌 API Overview
-
-The core API provides a concise and powerful way to work with the DOM:
+## Install
 
-- `E(Element|Selector, { attributes, dataset, style, ... }, children[] | mapped)`
-  - Create or wrap a DOM element with specified properties and children (binding).
-- `M(Array|Set, generateCb)`
-  - Map arrays or sets to DOM elements.
-- `H(DOMCode)` or `` H`DOMCode` ``
-  - Create static DOM HTML from code.
-- `T(String|StringRef)` or `` T`Code` ``
-  - Create a TextNode object (with reactive support).
-- `C(ref, whatToMake)`
-  - Create changeable DOM element (include for texts).
-- `S(CSSCode)` or `` S`CSSCode` ``
-  - Create controllable CSS code for elements
-- `Q(selector, root)`
-  - Make dynamically query selected wrapper
-  - Alternative of JQuery features, which is static
-
----
-
-## API Specification
-
-This is a consolidated, human-friendly overview of the public API exported from `src/index.ts`. For the full, generated reference, see the markdown files under `./docs/`.
-
-### Imports
-
-```ts
-import {
-  // Core
-  bindBeh, bindCtrl, bindHandler, bindWith, bindForms,
-  $observeInput, $observeAttribute,
-  // Refs
-  makeRef, attrRef, valueRef, valueAsNumberRef, localStorageRef,
-  sizeRef, checkedRef, scrollRef, visibleRef, matchMediaRef, hashTargetRef, orientRef, makeWeakRef,
-  // Node
-  E, M, Q, createElement, H,
-  // Extensions (selected)
-  bindDraggable, grabForDrag, agWrapEvent,
-} from "@fest-lib/lure";
+```bash
+npm install @fest-lib/core @fest-lib/dom @fest-lib/object @fest-lib/uniform @fest-lib/lure
 ```
 
-### Quick Start
+Peers: `core`, `dom`, `object`, `uniform` (`>=0.1.0`). ESM, `sideEffects: true`.
 
 ```ts
-// Create an element
-const el = E("div", {
-  attributes: { id: "app" },
-  classList: new Set(["box"]),
-  style: { padding: "8px" },
-}, [
-  "Hello",
-]);
+import { E, H, M, Q, T } from "@fest-lib/lure";
+import { observe, iterated } from "@fest-lib/object";
 
+const el = E("div", {
+    attributes: { id: "app" },
+    classList: new Set(["box"]),
+    style: { padding: "8px" },
+    on: { click: () => console.log("hi") }
+}, ["Hello"]);
 document.body.append(el as Node);
 ```
 
-### Core
-
-- `bindBeh(element, store, behavior)`: Invoke `behavior` on store changes.
-- `bindCtrl(element, ctrlCb)`: Wire common input/change/click listeners.
-- `bindHandler(element, value, prop, handler, set?, withObserver?)`: Generic bridge for refs → DOM.
-- `bindWith(el, prop, value, handler, set?, withObserver?)`: Apply once and affected.
-- `bindForms(fields?, wrapper?, state?)`: Two-way bind inputs within a container to a reactive `state`.
-- `$observeInput(element, ref?, prop = "value")`: Sync input property to ref.
-- `$observeAttribute(el, ref?, prop)`: Sync attribute to ref.
-
-### Refs
+## Factory map
 
-Create reactive references, often linked to DOM state:
+| API | Role |
+| --- | --- |
+| `E(tag \| node, props, children)` | create / wrap + bind |
+| `H\`html\`` / `H("<div>")` | parse HTML or tagged template |
+| `M(list, mapFn)` | reactive list → nodes |
+| `Q(selector, root?)` | live query wrapper |
+| `T(string \| ref)` | text node |
+| `C(ref, factory)` | swap node when ref changes |
+| `S\`css\`` | controllable stylesheet |
 
-- `makeRef(host?, type?, link?, ...args)`
-- `attrRef(host, name)`, `valueRef(host, name)`, `valueAsNumberRef(host, name)`
-- `localStorageRef(key)`, `sizeRef(host, prop?)`, `checkedRef(host)`, `scrollRef(host, prop?)`, `visibleRef(host)`
-- `matchMediaRef(query)`, `hashTargetRef()`, `orientRef(host)`
-- `makeWeakRef(initial?, behavior?)`
-
-### Node API
-
-#### `E`: Element factory with bindings
+`H` prefixes: `attr:*` attribute · `prop:*` property · `on:*` / `@*` event · `ref` / `ref:*` assign.
 
 ```ts
-const out = E("button", {
-  attributes: { title: "Click me" },
-  properties: { disabled: false },
-  on: { click: (e) => console.log("clicked", e) },
-}, ["OK"]);
+const items = iterated(["A", "B"]);
+const list = H`<ul>${M(items, (x) => H`<li>${x}</li>`)}</ul>`;
+items.push("C"); // DOM updates
 ```
 
-#### JSX factory
+## Triggers & overlays
 
-```tsx
-// Use with JSX if configured (jsxFactory: createElement)
-const v = createElement("div", { className: "c" }, ["hello"]);
-```
-
-#### `Q`: Query wrapper
+Use these instead of ad-hoc listeners:
 
 ```ts
-const box = Q("#app");
-box.attr.id = "app2"; // example of reactive wrapper operations
-```
-
-#### `M`: Reactive mapping
-
-`M(observable, mapper)` maps a reactive array/set into DOM. Returns a reactive fragment-like node.
-
-```ts
-import { observe } from "@fest-lib/object";
-
-const rxItems = iterated(["A", "B", "C"]);
-const list = H`<ul>${M(rxItems, (x) => H`<li>${x}</li>`)}</ul>`;
-
-// later
-rxItems.push("D"); // DOM updates
-```
-
-### `H` and HTML Templates
-
-`H` supports both raw HTML strings and tagged template strings.
-
-- Raw string starting/ending with `<`/`>` → parsed into `Node`/`DocumentFragment`.
-- Plain string → `Text` node.
-- Function → invoked and processed recursively.
-- Tagged template → interpolates values into content/attributes/events/props.
-
-Attribute/prop/event/ref prefixes inside tagged templates:
-
-- `attr:*` → HTML attribute
-- `prop:*` → DOM property
-- `on:*` or `@*` → event listener
-- `ref` or `ref:*` → assigns element to ref(s)
-
-Examples:
-
-```ts
-// Raw string → Node
-const el = H("<div class=box>hello</div>");
-
-// Tagged template → content interpolation
-const name = "World";
-const title = H`<h1 class="title">Hello, ${name}!</h1>`;
-
-// Dynamic tag: supports tag#id.class1.class2
-const tag = "button.primary";
-const btn = H`<${tag}>Click</${tag}>`;
-
-// Attributes/props/events/refs
-const ref = { value: null as HTMLElement | null };
-const click = (e: Event) => console.log("clicked", e);
-const button = H`<button attr:title=${"Click"} prop:disabled=${false} on:click=${click} ref=${ref}>OK</button>`;
-```
-
-Static vs Reactive lists in `H` content:
-
-```ts
-// Static (non-reactive) mapping in template content
-const items = ["A", "B", "C"];
-const listStatic = H`<ul>${items.map(x => H`<li>${x}</li>`)}</ul>`;
-
-// Reactive list: use M(...)
-import { observe } from "@fest-lib/object";
-const rxItems = iterated(["A", "B", "C"]);
-const listReactive = H`<ul>${M(rxItems, (x) => H`<li>${x}</li>`)}</ul>`;
-```
-
-Multiple top-level nodes produce a `DocumentFragment`:
-
-```ts
-const frag = H`<div>one</div><div>two</div>`; // DocumentFragment
+import {
+    withTriggerModifiers,
+    bindOutsideDismiss,
+    resolvePlacement,
+    registerTransientOverlay
+} from "@fest-lib/lure";
 ```
 
-### Extensions (selection)
+- **TriggerCore** — `once` / `debounce` / `prevent` / `stop` / `capture` / `passive` via `withTriggerModifiers` and `E({ on })` tuples.
+- **bindOutsideDismiss** — composed path, panel roots, Escape, idempotent cleanup.
+- **resolvePlacement** / `placeOverlay` — CSS-anchor with JS fallback.
+- **registerTransientOverlay** — same-kind overlays close LIFO.
 
-Pointer helpers and drag handling:
+Forms: `formLink` / `bindForms` / `FormBinding` (`bindFormControl`, `formRef`). Mount lifecycle is opt-in (`bindWhileConnected`).
 
 ```ts
-import { bindDraggable, grabForDrag } from "@fest-lib/lure";
-
-const target = H`<div class="draggable" />` as HTMLElement;
+import { bindDraggable } from "@fest-lib/lure";
 bindDraggable(target, () => console.log("drag end"));
 ```
 
-### Handling refs and DOM elements
-
-**Flexible handling of refs and DOM elements:**
+## Also in the package
 
-- Referenced content is also a DOM element (`Text` node)
-- HTML DOM elements also can be placed as content of other DOM elements
-- `ref(...)` are reactive and will be updated when the referenced content changes
+OPFS / file helpers (`pickFile`, `saveFile`, markdown asset bind), clipboard, history, scrollbar, voice input, theme / color engines. Subpath: `@fest-lib/lure/markdown-assets`. JSX: `jsxFactory` → `createElement` (`@fest-lib/lure/src/lure/node/jsx-runtime`).
 
-```ts
-import { ref } from "@fest-lib/object";
-import { H } from "@fest-lib/lure";
-
-// referenced content is also a DOM element (`Text` node)
-const txt = ref("Hello");
-const hookOf = (el: HTMLElement) => { console.log(el); };
-const span = H`<span ref=${hookOf}>${txt}</span>`; // span is a DOM element (`HTMLSpanElement`)
-const button = H`<button>${span}</button>`;
-
-// Regular DOM elements
-const regular = document.createElement("span");
-regular.textContent = "Hello";
-const another = H`<button>${regular}</button>`;
-```
-
-### Documentation
-
-- Full markdown API reference is generated into `./docs/` by:
-
-```bash
-npm run docs:md
-```
-
-- HTML documentation can be generated by:
+## Workspace
 
 ```bash
-npm run docs
+cd modules/projects/lur.e
+npm test                 # linker, interaction, placement, overlay-host, trigger-core, form-binding
+npm run demo
+npm run build
+npm run publish
 ```
 
----
-
-## 🚧 Roadmap & Plans
-
-- Investigate advanced MutationObserver and IntersectionObserver features for DOM tree changes.
-- Explore integration with [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
-- Research and implement animation-specific features, including scroll-driven animations and animation worklets.
-- Consider adding support for ResizeObserver.
-
----
-
-## 📄 License
-
-This project is licensed under the [MIT License](./LICENSE).
-
----
-
-## 🤝 Contributing
-
-Contributions, issues, and feature requests are welcome!
-Feel free to check [issues page](https://github.com/fest-live/lur.e/issues).
-
----
-
-<p align="center"><b>Made with ❤️ by fest-live</b></p>
-
----
-
-## About naming conflicts
-
-- Originally, project was named as **BLU.E**.
-  - However, I won't have 'B' as first letter.
-- Also, **LUR.E** also should been named as **BLUR**.
-  - However, I would to save 'E' letter at end.
-  - And also, I don't want 'B' as first letter.
-- So, I decided to use **LUR.E** naming.
-  - However, that naming still controversial.
+Typedoc: `npm run docs:md`. License: [MIT](LICENSE).

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@fest-lib/lure",
     "description": "fest-lib LUR.E: reactive DOM (E/H/M/Q), form bind, overlays, drag",
-    "version": "0.1.48",
+    "version": "0.1.50",
     "license": "MIT",
     "type": "module",
     "sideEffects": true,