mates 0.3.0-beta.2 → 0.3.0-beta.4

package/dist/Directives/customEvent.d.ts

@@ -0,0 +1,74 @@
+import type { DirectiveResult } from "lit-html/directive.js";
+/**
+ * A typed custom event handler. Receives the `detail` payload directly —
+ * no need to unwrap `event.detail` manually.
+ */
+export type EleEventHandler<T = unknown> = (detail: T, event: CustomEvent<T>) => void;
+export declare function onEleEvent<T = unknown>(eventName: string, handler: EleEventHandler<T>): DirectiveResult;
+/**
+ * `useEleEvent` — call in the **outer function** of a mates component to get
+ * a `dispatch` function. Use `dispatch` anywhere in the component (event
+ * handlers, effects, async callbacks) to fire a bubbling `CustomEvent` from
+ * a specific element.
+ *
+ * The host element is passed as the first argument to `dispatch` — this is
+ * typically the element the event should originate from (e.g. the clicked
+ * `<li>`, the focused `<input>`). Events bubble upward and are composed, so
+ * any ancestor listening with `onEleEvent` will receive them.
+ *
+ * No cleanup is needed — `dispatch` just calls `dispatchEvent`, there are no
+ * persistent listeners to remove.
+ *
+ * @example
+ * ```ts
+ * import { onEleEvent, useEleEvent } from "mates";
+ *
+ * // ── Child ─────────────────────────────────────────────────────────────────
+ * const ListItem = (propsFn) => {
+ *   const { dispatch } = useEleEvent();
+ *
+ *   return () => html`
+ *     <li
+ *       @click=${(e: MouseEvent) =>
+ *         dispatch(e.currentTarget as HTMLElement, "item-select", {
+ *           id: propsFn().id,
+ *           label: propsFn().label,
+ *         })}
+ *     >
+ *       ${propsFn().label}
+ *     </li>
+ *   `;
+ * };
+ *
+ * // ── Parent ────────────────────────────────────────────────────────────────
+ * html`
+ *   <ul ${onEleEvent("item-select", (detail: { id: string }) => {
+ *     console.log("selected", detail.id);
+ *   })}>
+ *     ${items.map(item => x(ListItem, item))}
+ *   </ul>
+ * `;
+ *
+ * // ── Dispatching without an element ref (from a button click) ─────────────
+ * html`
+ *   <button @click=${(e: MouseEvent) =>
+ *     dispatch(e.currentTarget as HTMLElement, "form-submit", { value })}>
+ *     Submit
+ *   </button>
+ * `;
+ * ```
+ */
+export declare function useEleEvent(): {
+    /**
+     * Dispatch a named `CustomEvent` from the component's host `<x-x>` element.
+     *
+     * The host is captured once when `useEleEvent()` is called (outer function).
+     * The event bubbles and is composed so any ancestor with `onEleEvent` will
+     * receive it.
+     *
+     * @param eventName  The custom event name.
+     * @param detail     Optional typed payload attached as `event.detail`.
+     */
+    dispatch<T = unknown>(eventName: string, detail?: T): void;
+};
+//# sourceMappingURL=customEvent.d.ts.map

package/dist/Directives/customEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customEvent.d.ts","sourceRoot":"","sources":["../../lib/Directives/customEvent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAM7D;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,OAAO,IAAI,CACzC,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAClB,IAAI,CAAC;AA2EV,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAC1B,eAAe,CAEjB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,WAAW;IAQvB;;;;;;;;;OASG;aACM,CAAC,uBAAuB,MAAM,WAAW,CAAC,GAAG,IAAI;EAY7D"}

package/dist/Directives/disappear.d.ts

@@ -0,0 +1,23 @@
+/**
+ * disappear — removes the host element from the DOM after `ms` milliseconds.
+ *
+ * Useful for self-dismissing messages, temporary overlays, or any element
+ * that should vanish after a delay without any component re-render.
+ *
+ * The countdown is cancelled automatically if the element is removed from
+ * the DOM before the delay elapses (e.g. parent unmounts).
+ *
+ * If `ms` changes on re-render a fresh countdown is started from the new value.
+ *
+ * @param ms  Delay in milliseconds before the element is removed.
+ *
+ * @example
+ * // Remove a toast message after 3 seconds
+ * html`<div class="toast" ${disappear(3000)}>Saved!</div>`
+ *
+ * @example
+ * // Configurable delay
+ * html`<p class="hint" ${disappear(ttl)}>This hint disappears soon.</p>`
+ */
+export declare const disappear: (nextMs: number) => import("lit-html/directive").DirectiveResult;
+//# sourceMappingURL=disappear.d.ts.map

package/dist/Directives/disappear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disappear.d.ts","sourceRoot":"","sources":["../../lib/Directives/disappear.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS,kEAyBpB,CAAC"}

package/dist/Directives/eleHook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eleHook.d.ts","sourceRoot":"","sources":["../../lib/Directives/eleHook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAI1C;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,IAAI;IACnD,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAChC,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,IAAI,CACjD,CAAC,EAAE,WAAW,EACd,GAAG,IAAI,EAAE,CAAC,KACP,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;AAoB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,EAC1C,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,eAAe,CAmEjC;AAED,YAAY,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"eleHook.d.ts","sourceRoot":"","sources":["../../lib/Directives/eleHook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAI1C;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,IAAI;IACnD,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAChC,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,IAAI,CACjD,CAAC,EAAE,WAAW,EACd,GAAG,IAAI,EAAE,CAAC,KACP,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;AAoB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,EAC1C,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,eAAe,CA8EjC;AAED,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/Directives/index.d.ts

@@ -2,6 +2,8 @@ export { $, type DollarChain } from "./$";
 export { type AnimatedIfConfig, type AnimatedXConfig, animatedIf, animatedX, } from "./animatedConditional";
 export { type AttrMap, type AttrValue, attr, removeAttr, } from "./attrDirective";
 export { type ClassEntry, type ClassesInput, classes, removeClasses, } from "./classesDirective";
+export { type EleEventHandler, onEleEvent, useEleEvent } from "./customEvent";
+export { disappear } from "./disappear";
 export { type EleHookLifecycle, type EleHookMountFn, eleHook } from "./eleHook";
 export { type HtmlHookLifecycle, type HtmlHookMountFn, type HtmlHookRenderFn, htmlHook, } from "./htmlHook";
 export { type IntersectCallback, type IntersectOptions, onHidden, onIntersect, onVisible, } from "./intersectDirective";
@@ -13,6 +15,6 @@ export { type MatesCustomEventMap, type OnEventMap, on, on as onEvent, removeOn,
 export { type OnParentMap, onParent } from "./onParentDirective";
 export { renderSwitch, type SwitchCase, type SwitchEntry, } from "./renderSwitch";
 export { removeStyle, type StyleMap, type StyleValue, style, } from "./styleDirective";
-export { type TimerContent, timer } from "./timerDirective";
+export { type TimerContent, timerTemplate } from "./timerDirective";
 export { type VirtualListOptions, type VirtualMasonryOptions, virtualList, virtualMasonry, } from "./virtualHelpers";
 //# sourceMappingURL=index.d.ts.map

package/dist/Directives/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/Directives/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,UAAU,EACV,SAAS,GACV,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,IAAI,EACJ,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,OAAO,EACP,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,QAAQ,EACR,WAAW,EACX,SAAS,GACV,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,QAAQ,EACR,kBAAkB,EAClB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,KAAK,cAAc,GACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,EAAE,EACF,EAAE,IAAI,OAAO,EACb,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,WAAW,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,WAAW,EACX,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,GACN,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,WAAW,EACX,cAAc,GACf,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/Directives/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,UAAU,EACV,SAAS,GACV,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,IAAI,EACJ,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,OAAO,EACP,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,QAAQ,EACR,WAAW,EACX,SAAS,GACV,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,QAAQ,EACR,kBAAkB,EAClB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,KAAK,cAAc,GACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,EAAE,EACF,EAAE,IAAI,OAAO,EACb,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,WAAW,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,WAAW,EACX,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,GACN,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,WAAW,EACX,cAAc,GACf,MAAM,kBAAkB,CAAC"}

package/dist/Directives/timerDirective.d.ts

@@ -20,12 +20,12 @@ export type TimerContent = () => unknown;
  * @example
  * ```ts
  * import { html } from "mates";
- * import { timer } from "mates";
+ * import { timerTemplate } from "mates";
  *
  * // Live clock — updates every second, no component re-render
  * html`
  *   <div>
- *     Time: ${timer(() => new Date().toLocaleTimeString(), 1000)}
+ *     Time: ${timerTemplate(() => new Date().toLocaleTimeString(), 1000)}
  *   </div>
  * `;
  *
@@ -33,7 +33,7 @@ export type TimerContent = () => unknown;
  * const end = Date.now() + 60_000;
  * html`
  *   <span>
- *     ${timer(() => {
+ *     ${timerTemplate(() => {
  *       const remaining = Math.max(0, Math.ceil((end - Date.now()) / 1000));
  *       return remaining === 0 ? "Done!" : `${remaining}s`;
  *     }, 1000)}
@@ -43,10 +43,10 @@ export type TimerContent = () => unknown;
  * // Dynamic HTML content
  * html`
  *   <div>
- *     ${timer(() => html`<strong>${new Date().toLocaleTimeString()}</strong>`, 500)}
+ *     ${timerTemplate(() => html`<strong>${new Date().toLocaleTimeString()}</strong>`, 500)}
  *   </div>
  * `;
  * ```
  */
-export declare function timer(callback: TimerContent, ms: number): import("lit-html/directive").DirectiveResult<import("lit-html/directive").DirectiveClass>;
+export declare function timerTemplate(callback: TimerContent, ms: number): import("lit-html/directive").DirectiveResult<import("lit-html/directive").DirectiveClass>;
 //# sourceMappingURL=timerDirective.d.ts.map

package/dist/Directives/timerDirective.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timerDirective.d.ts","sourceRoot":"","sources":["../../lib/Directives/timerDirective.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC;AA+CzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,6FAEvD"}
+{"version":3,"file":"timerDirective.d.ts","sourceRoot":"","sources":["../../lib/Directives/timerDirective.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC;AA+CzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,6FAE/D"}

package/dist/Mutables/Extended Atoms/changeFlagAtom.d.ts

@@ -0,0 +1,56 @@
+import type { AtomConfig, AtomType } from "../atom/atom";
+export type ChangeFlagAtomType = AtomType<number> & {
+    /**
+     * Trigger a reactivity update.
+     *
+     * - Called with no argument: sets the value to `Math.random()`, guaranteeing
+     *   a new value every call and forcing all subscribers / effects / views to
+     *   re-run.
+     * - Called with a number: sets the value to that number. Useful when you
+     *   want a meaningful version counter or a specific sentinel value.
+     *
+     * @example
+     * flag.change();        // random — always triggers
+     * flag.change(n + 1);   // explicit increment
+     */
+    change(value?: number): void;
+    /** Discriminator tag — always `"changeFlagAtom"`. */
+    readonly name: "changeFlagAtom";
+};
+/**
+ * changeFlagAtom — a reactive number atom whose sole purpose is to force
+ * re-renders, effect re-runs, and subscription callbacks.
+ *
+ * The stored number is intentionally meaningless by default — only the fact
+ * that it changed matters. Call `change()` to trigger, or pass a value if
+ * you want a meaningful version counter.
+ *
+ * Pairs well with `disappear` to bring back a disappeared element:
+ *
+ * @example
+ * const flag = changeFlagAtom();
+ *
+ * // Re-render the element (and restart the disappear timer) each time flag changes
+ * return () => html`
+ *   ${flag()}   // read flag so the template re-runs when it changes
+ *   <div ${disappear(3000)}>I vanish in 3 s</div>
+ *   <button @click=${() => flag.change()}>Show again</button>
+ * `;
+ *
+ * @example
+ * // Explicit version counter
+ * const version = changeFlagAtom(0);
+ * version.change(version() + 1);
+ *
+ * @example
+ * // Pair with effect
+ * const refresh = changeFlagAtom();
+ * effect(() => {
+ *   refresh(); // subscribe
+ *   fetchData();
+ * });
+ * // later:
+ * refresh.change(); // re-triggers the effect
+ */
+export declare function changeFlagAtom(initial?: number, config?: AtomConfig): ChangeFlagAtomType;
+//# sourceMappingURL=changeFlagAtom.d.ts.map

package/dist/Mutables/Extended Atoms/changeFlagAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changeFlagAtom.d.ts","sourceRoot":"","sources":["../../../lib/Mutables/Extended Atoms/changeFlagAtom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAKzD,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG;IAClD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE,MAAU,EACnB,MAAM,CAAC,EAAE,UAAU,GAClB,kBAAkB,CAYpB"}

package/dist/Mutables/Extended Atoms/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./cacheAtom";
+export * from "./changeFlagAtom";
 export * from "./paginationAtom";
 export * from "./themeAtom";
 //# sourceMappingURL=index.d.ts.map

package/dist/Mutables/Extended Atoms/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/Mutables/Extended Atoms/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/Mutables/Extended Atoms/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC"}

package/dist/Mutables/atom/delayAtom.d.ts

@@ -0,0 +1,40 @@
+import { type AtomConfig, type AtomType } from "./atom";
+/**
+ * delayAtom — a reactive atom whose `set()` and `update()` calls are applied
+ * after a fixed `delay` in milliseconds.
+ *
+ * Unlike `debouncedAtom`, **every call fires** — there is no cancellation of
+ * previous pending writes. Each call schedules its own independent timeout.
+ * This makes it useful for "apply this value after N ms" patterns rather than
+ * "apply only the last value after N ms of silence".
+ *
+ * Accepts either a plain initial value or a source {@link AtomType}. When a
+ * source atom is provided the delay atom mirrors the source's value, applying
+ * the delay to every propagated change.
+ *
+ * All pending timeouts are cancelled automatically when the atom is disposed
+ * via `registerCleanup`.
+ *
+ * @param initialAtomOrState - A plain initial value, or a source atom to mirror.
+ * @param delay - How long to wait (ms) before each `set` / `update` is applied.
+ * @param config - Optional atom configuration forwarded to the underlying atom.
+ *
+ * @example
+ * // Every set fires independently after 1 second:
+ * const status = delayAtom("idle", 1000);
+ * status.set("loading");  // applied after 1 s
+ * status.set("done");     // also applied after 1 s (both fire, in order)
+ *
+ * @example
+ * // Mirror a source with delay:
+ * const immediate = atom(0);
+ * const delayed = delayAtom(immediate, 500);
+ * immediate.set(42); // delayed reflects 42 after 500 ms
+ *
+ * @example
+ * // Useful with disappear — update state after the animation finishes:
+ * const visible = delayAtom(true, 300);
+ * visible.set(false); // hides the element 300 ms later (after CSS transition)
+ */
+export declare function delayAtom<T>(initialAtomOrState: T | AtomType<T>, delay: number, config?: AtomConfig): AtomType<T>;
+//# sourceMappingURL=delayAtom.d.ts.map

package/dist/Mutables/atom/delayAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delayAtom.d.ts","sourceRoot":"","sources":["../../../lib/Mutables/atom/delayAtom.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAQ,MAAM,QAAQ,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,kBAAkB,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EACnC,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,UAAU,GAClB,QAAQ,CAAC,CAAC,CAAC,CA8Db"}

package/dist/Mutables/atom/index.d.ts

@@ -2,6 +2,7 @@ export * from "./atom";
 export * from "./atom";
 export * from "./createTimedAtom";
 export * from "./debouncedAtom";
+export * from "./delayAtom";
 export * from "./mapAtom";
 export * from "./setAtom";
 export * from "./storageAtom";

package/dist/Mutables/atom/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/Mutables/atom/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/Mutables/atom/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/Router/historyStateAtom.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `historyStateAtom` — a reactive atom that always reflects
+ * `window.history.state`.
+ *
+ * Updated in two situations:
+ *
+ * 1. **`popstate`** — the user pressed back / forward. The browser restores
+ *    the state that was associated with that history entry and this atom is
+ *    set to `event.state`.
+ *
+ * 2. **`navigateTo(path, replace, data)`** — called directly from
+ *    `navigateTo.ts` before the pushState / replaceState call so any
+ *    subscriber reading the atom during the subsequent `pathAtom` update
+ *    already sees the new state.
+ *
+ * Hydrated from `window.history.state` at module load time so a hard
+ * refresh or direct URL load with pre-existing state is reflected
+ * correctly from the very first render.
+ *
+ * @example
+ * // Pass state when navigating:
+ * navigateTo("/users/42", false, { fromList: true, scrollY: 320 });
+ *
+ * // Read it on the destination page:
+ * historyStateAtom(); // { fromList: true, scrollY: 320 }
+ *
+ * // Back / forward automatically restores the state for that entry.
+ *
+ * @example
+ * // Drive slide direction based on navigation state:
+ * const { direction } = historyStateAtom() ?? {};
+ * html`<div class=${direction === "back" ? "slide-right" : "slide-left"}>…</div>`
+ *
+ * @example
+ * // Guard: know whether the user arrived via in-app nav or direct load:
+ * const state = historyStateAtom();
+ * if (!state?.fromApp) navigateTo("/");
+ */
+export declare const historyStateAtom: import("../Mutables/atom/atom").AtomType<unknown>;
+//# sourceMappingURL=historyStateAtom.d.ts.map

package/dist/Router/historyStateAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"historyStateAtom.d.ts","sourceRoot":"","sources":["../../lib/Router/historyStateAtom.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,gBAAgB,mDAE5B,CAAC"}

package/dist/Router/historyUtils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Replace dynamic route params in the current URL using a **pattern** that
+ * describes which segments are params.
+ *
+ * The pattern tells `replaceParams` the *names* of the dynamic segments —
+ * the current path provides the *positions*. Together they let you swap out
+ * individual param values without touching the rest of the URL.
+ *
+ * Uses `replaceState` — no new history entry is created.
+ *
+ * ```ts
+ * // Current path: /users/42/posts/7
+ * replaceParams("/users/:id/posts/:postId", { id: 99 });
+ * // → /users/99/posts/7
+ *
+ * replaceParams("/users/:id/posts/:postId", { id: 99, postId: 3 });
+ * // → /users/99/posts/3
+ * ```
+ *
+ * @param pattern  Route pattern with `:param` segments (e.g. `"/users/:id"`).
+ * @param params   Param names → new values. Only provided keys are replaced;
+ *                 all other segments are left unchanged.
+ */
+export declare function replaceParams(pattern: string, params: Record<string, string | number | boolean>): void;
+//# sourceMappingURL=historyUtils.d.ts.map

package/dist/Router/historyUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"historyUtils.d.ts","sourceRoot":"","sources":["../../lib/Router/historyUtils.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAChD,IAAI,CA0CN"}

package/dist/Router/index.d.ts

@@ -1,10 +1,13 @@
 export { type AnimatedRouteConfig, type AnimatedRouterOptions, animatedRouter, } from "./animatedRouter";
 export { buildPath } from "./buildPath";
 export { hashAtom } from "./hashAtom";
+export { historyStateAtom } from "./historyStateAtom";
+export { replaceParams } from "./historyUtils";
 export { isPathMatching } from "./isPathMatching";
 export { location } from "./location";
 export { navigateTo } from "./navigateTo";
 export { lockNavigation, navigationLocked, unlockNavigation, } from "./navigationLock";
+export { type NavigationRequestDetail, navigationRequestEvent, onNavigationRequest, } from "./navigationRequest";
 export { pathAtom } from "./pathAtom";
 export { qsAtom } from "./qsAtom";
 export { Router, route } from "./Router";

package/dist/Router/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/Router/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/Router/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,uBAAuB,EAC5B,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC"}

package/dist/Router/navigateTo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigateTo.d.ts","sourceRoot":"","sources":["../../lib/Router/navigateTo.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAU5E"}
+{"version":3,"file":"navigateTo.d.ts","sourceRoot":"","sources":["../../lib/Router/navigateTo.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CA8C5E"}

package/dist/Router/navigationRequest.d.ts

@@ -0,0 +1,75 @@
+export interface NavigationRequestDetail {
+    /** The path the user is navigating to. */
+    to: string;
+    /** The path the user is currently on. */
+    from: string;
+}
+/**
+ * Fired by `navigateTo()` immediately before navigation is committed.
+ *
+ * Subscribe with `on()` in a component's outer function to react to every
+ * navigation attempt — for example to show a "leave page?" confirmation dialog
+ * before the route actually changes.
+ *
+ * The event carries `{ to, from }` so you always know both endpoints.
+ *
+ * @example
+ * ```ts
+ * import { navigationRequestEvent } from "mates";
+ * import { on } from "mates";
+ *
+ * const MyPage = () => {
+ *   const confirm = useConfirmDialog({ danger: false });
+ *
+ *   on(async ({ to }) => {
+ *     const ok = await confirm.show(`Leave to ${to}?`);
+ *     if (!ok) lockNavigation();
+ *   }, [navigationRequestEvent]);
+ *
+ *   return () => html`…`;
+ * };
+ * ```
+ */
+export declare const navigationRequestEvent: import("../Mutables/events/events").EventType<NavigationRequestDetail>;
+/**
+ * `onNavigationRequest` — component-scoped hook that fires whenever
+ * `navigateTo()` is called, **before** the navigation is committed.
+ *
+ * Exactly mirrors the `onNavigate` pattern but fires at request time rather
+ * than after the route has already changed. Use it to:
+ * - Show a "you have unsaved changes" dialog
+ * - Conditionally lock navigation with `lockNavigation()`
+ * - Log analytics for navigation intent
+ *
+ * The callback receives `{ to, from }` and may optionally return a cleanup
+ * function that runs before the next invocation.
+ *
+ * Must be called in the **outer function** of a mates component.
+ *
+ * @example
+ * ```ts
+ * import { onNavigationRequest, lockNavigation, unlockNavigation } from "mates";
+ *
+ * const EditorPage = () => {
+ *   const isDirty = atom(false);
+ *   const confirm = useConfirmDialog();
+ *
+ *   onNavigationRequest(async ({ to }) => {
+ *     if (!isDirty()) return;
+ *     const ok = await confirm.show("Leave without saving?", {
+ *       yesLabel: "Leave",
+ *       noLabel:  "Stay",
+ *     });
+ *     if (!ok) {
+ *       lockNavigation();
+ *       // re-unlock so future navigation works after user decides to stay
+ *       Promise.resolve().then(unlockNavigation);
+ *     }
+ *   });
+ *
+ *   return () => html`…`;
+ * };
+ * ```
+ */
+export declare const onNavigationRequest: (fn: (detail: NavigationRequestDetail) => void | (() => void)) => void;
+//# sourceMappingURL=navigationRequest.d.ts.map

package/dist/Router/navigationRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigationRequest.d.ts","sourceRoot":"","sources":["../../lib/Router/navigationRequest.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;CACd;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,sBAAsB,wEAElC,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,mBAAmB,GAC9B,IAAI,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,KAC3D,IAUF,CAAC"}

package/dist/Router/pathAtom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pathAtom.d.ts","sourceRoot":"","sources":["../../lib/Router/pathAtom.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,uDAEpB,CAAC"}
+{"version":3,"file":"pathAtom.d.ts","sourceRoot":"","sources":["../../lib/Router/pathAtom.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,uDAEpB,CAAC"}

package/dist/Utils/countdown.d.ts

@@ -0,0 +1,48 @@
+export type CountdownState = "idle" | "running" | "paused" | "stopped";
+export interface Countdown {
+    /** Start the timer from the full duration. No-op if already running. */
+    start(): void;
+    /**
+     * Pause the timer. The remaining time is frozen at the current value.
+     * No-op if already paused, idle, or stopped.
+     */
+    pause(): void;
+    /**
+     * Resume a paused timer. Restarts a `setTimeout` for the remaining duration.
+     * No-op if already running, idle, or stopped.
+     */
+    resume(): void;
+    /**
+     * Stop and reset the timer. The callback will never fire.
+     * Remaining time is reset to the full duration.
+     * Calling start() after stop() begins a fresh countdown.
+     */
+    stop(): void;
+    /** Current state of the timer. */
+    readonly state: CountdownState;
+    /**
+     * Milliseconds remaining.
+     * - While `running`: live value computed from wall-clock elapsed.
+     * - While `paused` / `idle` / `stopped`: last frozen snapshot.
+     */
+    readonly remaining: number;
+}
+/**
+ * timer — precise pausable countdown timer.
+ *
+ * @param callback  Called once when the full duration has elapsed.
+ * @param duration  Total countdown duration in milliseconds.
+ *
+ * @example
+ * const { start, pause, resume, stop, remaining } = timer(() => {
+ *   dismiss(id);
+ * }, 6000);
+ *
+ * start();
+ * // user hovers card
+ * pause();
+ * // user leaves card
+ * resume();
+ */
+export declare function countdown(callback: () => void, duration: number): Countdown;
+//# sourceMappingURL=countdown.d.ts.map

package/dist/Utils/countdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"countdown.d.ts","sourceRoot":"","sources":["../../lib/Utils/countdown.ts"],"names":[],"mappings":"AAuBA,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEvE,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,KAAK,IAAI,IAAI,CAAC;IACd;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IACd;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IACf;;;;OAIG;IACH,IAAI,IAAI,IAAI,CAAC;IACb,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CA6G3E"}

package/dist/Utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./Context";
+export * from "./countdown";
 export * from "./deepClone";
 export * from "./deepFreeze";
 export * from "./getAllProps";

package/dist/Utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/Utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,MAAM,CAAC;AACrB,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/Utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,MAAM,CAAC;AACrB,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC"}