@typed/template 0.14.0 → 1.0.0-beta.0

package/src/EventHandler.ts

@@ -1,142 +1,374 @@
-/**
- * @since 1.0.0
- */
-import { type EventWithTarget, isUsingKeyModifier } from "@typed/dom/EventTarget"
-import * as Effect from "effect/Effect"
-import type { Placeholder } from "./Placeholder.js"
+import type * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
+import { type Pipeable, pipeArguments } from "effect/Pipeable";
+import { hasProperty } from "effect/Predicate";
+import type * as ServiceMap from "effect/ServiceMap";
+
+export const EventHandlerTypeId = Symbol.for("@typed/template/EventHandler");
+export type EventHandlerTypeId = typeof EventHandlerTypeId;
 
 /**
+ * Represents a DOM event handler that returns an Effect.
+ *
+ * It encapsulates the event handler logic and any options (like `preventDefault`, `once`, etc.)
+ * that should be applied when the event is triggered.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as EventHandler from "@typed/template/EventHandler"
+ * import { html } from "@typed/template"
+ *
+ * // Simple event handler
+ * const handleClick = EventHandler.make((event: MouseEvent) => {
+ *   console.log("Clicked!", event)
+ * })
+ *
+ * // Event handler with Effect
+ * const handleSubmit = EventHandler.make((event: SubmitEvent) =>
+ *   Effect.gen(function* () {
+ *     event.preventDefault()
+ *     yield* Effect.sync(() => console.log("Form submitted"))
+ *   })
+ * )
+ *
+ * // Use in template
+ * const template = html`<button onclick=${handleClick}>Click me</button>`
+ * ```
+ *
  * @since 1.0.0
+ * @category models
  */
-export const EventHandlerTypeId = Symbol.for("@typed/template/EventHandler")
+export interface EventHandler<Ev extends Event = Event, E = never, R = never> extends Pipeable {
+  readonly [EventHandlerTypeId]: EventHandlerTypeId;
+  readonly handler: (event: Ev) => Effect.Effect<unknown, E, R>;
+  readonly options: (AddEventListenerOptions & EventOptions) | undefined;
+}
+
+export type Context<T> = T extends EventHandler<infer _Ev, infer _E, infer R> ? R : never;
+export type Error<T> = T extends EventHandler<infer _Ev, infer E, infer _R> ? E : never;
+export type EventOf<T> = T extends EventHandler<infer Ev, infer _E, infer _R> ? Ev : never;
+
 /**
- * @since 1.0.0
+ * Options for configuring event handling behavior.
  */
-export type EventHandlerTypeId = typeof EventHandlerTypeId
+export type EventOptions = {
+  readonly preventDefault?: boolean;
+  readonly stopPropagation?: boolean;
+  readonly stopImmediatePropagation?: boolean;
+};
 
 /**
+ * Creates a new `EventHandler`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as EventHandler from "@typed/template/EventHandler"
+ * import { html } from "@typed/template"
+ *
+ * // Simple handler
+ * const clickHandler = EventHandler.make((event) => {
+ *   console.log("Button clicked")
+ * })
+ *
+ * // Handler with Effect
+ * const submitHandler = EventHandler.make((event) =>
+ *   Effect.gen(function* () {
+ *     const form = event.target as HTMLFormElement
+ *     const data = new FormData(form)
+ *     yield* Effect.sync(() => console.log("Submitting:", data))
+ *   })
+ * )
+ *
+ * // Handler with options
+ * const preventDefaultHandler = EventHandler.make(
+ *   (event) => console.log("Prevented default"),
+ *   { preventDefault: true }
+ * )
+ *
+ * const template = html`<button onclick=${clickHandler}>Click</button>`
+ * ```
+ *
+ * @param handler - The function to execute when the event occurs. Can return void or an Effect.
+ * @param options - Optional configuration for the event listener.
  * @since 1.0.0
+ * @category constructors
  */
-export interface EventHandler<Ev extends Event = Event, E = never, R = never> extends Placeholder<never, E, R> {
-  readonly [EventHandlerTypeId]: EventHandlerTypeId
-  readonly handler: (event: Ev) => Effect.Effect<unknown, E, R>
-  readonly options: AddEventListenerOptions | undefined
+export function make<Ev extends Event, E = never, R = never>(
+  handler: (event: Ev) => void | Effect.Effect<unknown, E, R>,
+  options?: AddEventListenerOptions & EventOptions,
+): EventHandler<Ev, E, R> {
+  return {
+    [EventHandlerTypeId]: EventHandlerTypeId,
+    handler: (ev: Ev) => {
+      if (options) handleEventOptions(options, ev);
+      const result = handler(ev);
+      if (Effect.isEffect(result)) return result;
+      return Effect.void;
+    },
+    options,
+    pipe(this: EventHandler<Ev, E, R>) {
+      return pipeArguments(this, arguments);
+    },
+  };
 }
 
 /**
+ * Provides services to the `EventHandler`.
+ *
+ * This allows you to inject dependencies into the effect returned by the event handler.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Context } from "effect"
+ * import * as EventHandler from "@typed/template/EventHandler"
+ *
+ * interface Database {
+ *   readonly save: (data: string) => Effect.Effect<void>
+ * }
+ * const Database = Context.GenericTag<Database>("Database")
+ *
+ * const handler = EventHandler.make((event) =>
+ *   Effect.flatMap(Database, (db) => db.save("data"))
+ * )
+ *
+ * // Provide services
+ * const provided = EventHandler.provide(handler, Database.of({ save: (d) => Effect.sync(() => console.log(d)) }))
+ * ```
+ *
  * @since 1.0.0
+ * @category combinators
  */
-export type Context<T> = T extends EventHandler<infer _Ev, infer _E, infer R> ? R : never
+export const provide: {
+  <R2 = never>(
+    services: ServiceMap.ServiceMap<R2>,
+  ): <Ev extends Event, E = never, R = never>(
+    handler: EventHandler<Ev, E, R>,
+  ) => EventHandler<Ev, E, Exclude<R, R2>>;
+
+  <Ev extends Event, E = never, R = never, R2 = never>(
+    handler: EventHandler<Ev, E, R>,
+    services: ServiceMap.ServiceMap<R2>,
+  ): EventHandler<Ev, E, Exclude<R, R2>>;
+} = dual(
+  2,
+  <Ev extends Event, E = never, R = never, R2 = never>(
+    handler: EventHandler<Ev, E, R>,
+    services: ServiceMap.ServiceMap<R2>,
+  ): EventHandler<Ev, E, Exclude<R, R2>> => {
+    return make(
+      (ev) => handler.handler(ev).pipe(Effect.provideServices(services)),
+      handler.options,
+    );
+  },
+);
+
 /**
+ * Recovers from errors in the `EventHandler`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as EventHandler from "@typed/template/EventHandler"
+ *
+ * const handler = EventHandler.make((event) =>
+ *   Effect.fail("Something went wrong")
+ * )
+ *
+ * // Recover from errors
+ * const recovered = EventHandler.catchCause(handler, (cause) =>
+ *   Effect.sync(() => console.error("Error:", cause))
+ * )
+ * ```
+ *
  * @since 1.0.0
+ * @category combinators
  */
-export type Error<T> = T extends EventHandler<infer _Ev, infer E, infer _R> ? E : never
+export const catchCause: {
+  <E, E2 = never, R2 = never>(
+    f: (cause: Cause.Cause<E>) => Effect.Effect<unknown, E2, R2>,
+  ): <Ev extends Event, R = never>(handler: EventHandler<Ev, E, R>) => EventHandler<Ev, E2, R | R2>;
+
+  <Ev extends Event, E = never, R = never, E2 = never, R2 = never>(
+    handler: EventHandler<Ev, E, R>,
+    f: (cause: Cause.Cause<E>) => Effect.Effect<unknown, E2, R2>,
+  ): EventHandler<Ev, E2, R | R2>;
+} = dual(
+  2,
+  <Ev extends Event, E = never, R = never, E2 = never, R2 = never>(
+    handler: EventHandler<Ev, E, R>,
+    f: (cause: Cause.Cause<E>) => Effect.Effect<unknown, E2, R2>,
+  ): EventHandler<Ev, E2, R | R2> => {
+    return make((ev) => handler.handler(ev).pipe(Effect.catchCause(f)), handler.options);
+  },
+);
+
 /**
- * @since 1.0.0
+ * Helper to ensure a value is an `EventHandler`.
+ *
+ * If the input is already an `EventHandler`, it is returned as is.
+ * If it is an `Effect`, it is wrapped in an `EventHandler` that ignores the event argument.
  */
-export type EventOf<T> = T extends EventHandler<infer Ev, infer _E, infer _R> ? Ev : never
+export function fromEffectOrEventHandler<Ev extends Event, E = never, R = never>(
+  handler: Effect.Effect<unknown, E, R> | EventHandler<Ev, E, R>,
+): EventHandler<Ev, E, R> {
+  if (isEventHandler(handler)) return handler;
+  return make(() => handler as Effect.Effect<unknown, E, R>);
+}
 
 /**
+ * Checks if a value is an `EventHandler`.
+ *
+ * @example
+ * ```ts
+ * import * as EventHandler from "@typed/template/EventHandler"
+ *
+ * const handler = EventHandler.make((event) => console.log("Click"))
+ * const isHandler = EventHandler.isEventHandler(handler)
+ * console.log(isHandler) // true
+ *
+ * const notHandler = (event: Event) => console.log("Click")
+ * const isNotHandler = EventHandler.isEventHandler(notHandler)
+ * console.log(isNotHandler) // false
+ * ```
+ *
  * @since 1.0.0
+ * @category guards
  */
-export function make<Ev extends Event, E = never, R = never>(
-  handler: (event: Ev) => Effect.Effect<unknown, E, R>,
-  options?: AddEventListenerOptions
-): EventHandler<Ev, E, R> {
-  return {
-    [EventHandlerTypeId]: EventHandlerTypeId,
-    handler,
-    options
-  } as any
+export function isEventHandler<Ev extends Event, E = never, R = never>(
+  handler: unknown,
+): handler is EventHandler<Ev, E, R> {
+  return hasProperty(handler, EventHandlerTypeId);
 }
 
 /**
- * @since 1.0.0
+ * Applies event options to a native DOM event.
  */
-export function preventDefault<R, E, Ev extends Event>(
-  handler: (event: Ev) => Effect.Effect<unknown, E, R>,
-  options?: AddEventListenerOptions
-): EventHandler<Ev, E, R> {
-  return make((ev) => (ev.preventDefault(), handler(ev)), options)
+export function handleEventOptions<Ev extends Event>(eventOptions: EventOptions, ev: Ev): boolean {
+  if (eventOptions.preventDefault) ev.preventDefault();
+  if (eventOptions.stopPropagation) ev.stopPropagation();
+  if (eventOptions.stopImmediatePropagation) ev.stopImmediatePropagation();
+
+  return true;
 }
 
 /**
+ * Modifies an `EventHandler` to call `preventDefault()` on the event.
+ *
+ * @example
+ * ```ts
+ * import * as EventHandler from "@typed/template/EventHandler"
+ * import { html } from "@typed/template"
+ *
+ * const handler = EventHandler.make((event) => {
+ *   console.log("Form submit prevented")
+ * })
+ *
+ * const preventDefaultHandler = EventHandler.preventDefault(handler)
+ *
+ * const template = html`<form onsubmit=${preventDefaultHandler}>...</form>`
+ * ```
+ *
  * @since 1.0.0
+ * @category combinators
  */
-export function stopPropagation<R, E, Ev extends Event>(
-  handler: (event: Ev) => Effect.Effect<unknown, E, R>,
-  options?: AddEventListenerOptions
+export function preventDefault<Ev extends Event, E = never, R = never>(
+  handler: EventHandler<Ev, E, R>,
 ): EventHandler<Ev, E, R> {
-  return make((ev) => (ev.stopPropagation(), handler(ev)), options)
+  return make(handler.handler, { ...handler.options, preventDefault: true });
 }
 
 /**
+ * Modifies an `EventHandler` to call `stopPropagation()` on the event.
+ *
+ * @example
+ * ```ts
+ * import * as EventHandler from "@typed/template/EventHandler"
+ *
+ * const handler = EventHandler.make((event) => {
+ *   console.log("Event stopped")
+ * })
+ *
+ * const stopPropHandler = EventHandler.stopPropagation(handler)
+ * ```
+ *
  * @since 1.0.0
+ * @category combinators
  */
-export function stopImmediatePropagation<R, E, Ev extends Event>(
-  handler: (event: Ev) => Effect.Effect<unknown, E, R>,
-  options?: AddEventListenerOptions
+export function stopPropagation<Ev extends Event, E = never, R = never>(
+  handler: EventHandler<Ev, E, R>,
 ): EventHandler<Ev, E, R> {
-  return make((ev) => (ev.stopImmediatePropagation(), handler(ev)), options)
+  return make(handler.handler, { ...handler.options, stopPropagation: true });
 }
 
 /**
+ * Modifies an `EventHandler` to call `stopImmediatePropagation()` on the event.
+ *
+ * @example
+ * ```ts
+ * import * as EventHandler from "@typed/template/EventHandler"
+ *
+ * const handler = EventHandler.make((event) => {
+ *   console.log("Immediate propagation stopped")
+ * })
+ *
+ * const stopImmediateHandler = EventHandler.stopImmediatePropagation(handler)
+ * ```
+ *
  * @since 1.0.0
+ * @category combinators
  */
-export type EventOptions = {
-  readonly preventDefault?: boolean
-  readonly stopPropagation?: boolean
-  readonly stopImmediatePropagation?: boolean
-}
-
-function handleEventOptions<Ev extends Event>(
-  eventOptions: EventOptions,
-  ev: Ev
-): boolean {
-  if (eventOptions.preventDefault) ev.preventDefault()
-  if (eventOptions.stopPropagation) ev.stopPropagation()
-  if (eventOptions.stopImmediatePropagation) ev.stopImmediatePropagation()
-
-  return true
+export function stopImmediatePropagation<Ev extends Event, E = never, R = never>(
+  handler: EventHandler<Ev, E, R>,
+): EventHandler<Ev, E, R> {
+  return make(handler.handler, { ...handler.options, stopImmediatePropagation: true });
 }
 
 /**
+ * Modifies an `EventHandler` to run only once.
+ *
+ * @example
+ * ```ts
+ * import * as EventHandler from "@typed/template/EventHandler"
+ *
+ * const handler = EventHandler.make((event) => {
+ *   console.log("This will only run once")
+ * })
+ *
+ * const onceHandler = EventHandler.once(handler)
+ * ```
+ *
  * @since 1.0.0
+ * @category combinators
  */
-export function target<T extends HTMLElement>(eventOptions?: {
-  preventDefault?: boolean
-  stopPropagation?: boolean
-  stopImmediatePropagation?: boolean
-}) {
-  return <R, E, Ev extends Event>(
-    handler: (event: EventWithTarget<T, Ev>) => Effect.Effect<unknown, E, R>,
-    options?: AddEventListenerOptions
-  ): EventHandler<EventWithTarget<T, Ev>, E, R> => {
-    return make(
-      eventOptions ?
-        (ev) => {
-          handleEventOptions(eventOptions, ev)
-          return handler(ev)
-        } :
-        handler,
-      options
-    )
-  }
+export function once<Ev extends Event, E = never, R = never>(
+  handler: EventHandler<Ev, E, R>,
+): EventHandler<Ev, E, R> {
+  return make(handler.handler, { ...handler.options, once: true, passive: false });
 }
 
 /**
+ * Modifies an `EventHandler` to be passive (improves scrolling performance).
+ *
+ * @example
+ * ```ts
+ * import * as EventHandler from "@typed/template/EventHandler"
+ *
+ * const handler = EventHandler.make((event) => {
+ *   // Passive handlers can't call preventDefault
+ *   console.log("Scroll event")
+ * })
+ *
+ * const passiveHandler = EventHandler.passive(handler)
+ * ```
+ *
  * @since 1.0.0
+ * @category combinators
  */
-export function keys<Keys extends ReadonlyArray<string>>(...keys: Keys) {
-  return <E, R>(
-    handler: (event: KeyboardEvent & { key: Keys[number] }) => Effect.Effect<unknown, E, R>,
-    options?: AddEventListenerOptions & EventOptions
-  ): EventHandler<KeyboardEvent, E, R> =>
-    make(
-      (ev: KeyboardEvent) =>
-        !isUsingKeyModifier(ev) && keys.includes(ev.key)
-          ? (options && handleEventOptions(options, ev), handler(ev as any))
-          : Effect.void,
-      options
-    )
+export function passive<Ev extends Event, E = never, R = never>(
+  handler: EventHandler<Ev, E, R>,
+): EventHandler<Ev, E, R> {
+  return make(handler.handler, { ...handler.options, passive: true, once: false });
 }

package/src/EventSource.ts

@@ -0,0 +1,202 @@
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Scope from "effect/Scope";
+import type { EventHandler } from "./EventHandler.js";
+import { getElements, type Rendered } from "./Wire.js";
+
+type EventName = string;
+
+type Handler<Ev extends Event> = EventHandler<Ev>;
+
+/**
+ * An interface for managing event listeners on DOM nodes.
+ *
+ * It abstracts the process of adding and removing event listeners, ensuring that they are
+ * properly cleaned up when the scope is closed or the element is removed.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { makeEventSource } from "@typed/template/EventSource"
+ * import * as EventHandler from "@typed/template/EventHandler"
+ * import { Scope } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const eventSource = makeEventSource()
+ *   const button = document.createElement("button")
+ *
+ *   // Add event listener
+ *   const handler = EventHandler.make((event: MouseEvent) => {
+ *     console.log("Button clicked")
+ *   })
+ *
+ *   const disposable = eventSource.addEventListener(button, "click", handler)
+ *
+ *   // Setup listeners for rendered content
+ *   yield* eventSource.setup(button, yield* Scope.make())
+ *
+ *   // Cleanup
+ *   disposable[Symbol.dispose]()
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface EventSource {
+  /**
+   * Adds an event listener to a target.
+   */
+  readonly addEventListener: <Ev extends Event>(
+    element: EventTarget,
+    event: EventName,
+    handler: Handler<Ev>,
+  ) => Disposable;
+
+  /**
+   * Sets up event listeners for a rendered template within a scope.
+   */
+  readonly setup: (rendered: Rendered, scope: Scope.Scope) => Effect.Effect<void>;
+}
+
+type Entry = readonly [Element, Handler<any>];
+type Run = <E, A>(effect: Effect.Effect<A, E>) => Fiber.Fiber<A, E>;
+
+const disposable = (f: () => void): Disposable => ({ [Symbol.dispose]: f });
+const dispose = (d: Disposable): void => d[Symbol.dispose]();
+
+/**
+ * Creates a new `EventSource`.
+ *
+ * The created `EventSource` can efficiently manage multiple event listeners,
+ * grouping them by event type and handling setup/teardown lifecycles.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { makeEventSource } from "@typed/template/EventSource"
+ * import * as EventHandler from "@typed/template/EventHandler"
+ *
+ * const program = Effect.gen(function* () {
+ *   const eventSource = makeEventSource()
+ *   const element = document.createElement("div")
+ *
+ *   // Add multiple event listeners
+ *   eventSource.addEventListener(element, "click", EventHandler.make(() => console.log("clicked")))
+ *   eventSource.addEventListener(element, "mouseover", EventHandler.make(() => console.log("hovered")))
+ *
+ *   // Setup all listeners
+ *   yield* eventSource.setup(element, yield* Scope.make())
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeEventSource(): EventSource {
+  const listeners = new Map<EventName, readonly [normal: Set<Entry>, once: Set<Entry>]>();
+
+  function addEventListener(
+    element: EventTarget,
+    event: EventName,
+    handler: Handler<any>,
+  ): Disposable {
+    const sets = listeners.get(event);
+    const entry: Entry = [element as Element, handler];
+    const isOnce = handler.options?.once === true;
+    const normal: Set<Entry> = sets?.[0] ?? new Set<Entry>();
+    const once: Set<Entry> = sets?.[1] ?? new Set<Entry>();
+    if (sets === undefined) {
+      listeners.set(event, [normal, once]);
+    }
+    if (isOnce) {
+      once.add(entry);
+      return disposable(() => once.delete(entry));
+    } else {
+      normal.add(entry);
+      return disposable(() => normal.delete(entry));
+    }
+  }
+
+  function setupListeners(element: Element, run: Run) {
+    const disposables: Array<Disposable> = [];
+
+    for (const [event, sets] of listeners) {
+      for (const handlers of sets) {
+        if (handlers.size === 0) continue;
+        const listener = (ev: Event) =>
+          run(
+            Effect.forEach(handlers, ([el, { handler }]) => {
+              const match = ev.target === el || el.contains(ev.target as Node);
+              return match ? handler(proxyCurrentTarget(ev, el)) : Effect.void;
+            }),
+          );
+        element.addEventListener(event, listener, getDerivedAddEventListenerOptions(handlers));
+        disposables.push(disposable(() => element.removeEventListener(event, listener)));
+      }
+    }
+
+    return disposables;
+  }
+
+  function setup(rendered: Rendered, scope: Scope.Scope) {
+    if (listeners.size === 0) return Effect.void;
+
+    const elements = getElements(rendered);
+    if (elements.length === 0) return Effect.void;
+
+    const disposables: Array<Disposable> = [];
+    const fibers = new Map<symbol, Fiber.Fiber<any, any>>();
+    const run: Run = <E, A>(effect: Effect.Effect<A, E>) => {
+      const id = Symbol();
+      const fiber = Effect.runFork(
+        Effect.onExit(effect, () => Effect.sync(() => fibers.delete(id))),
+      );
+      fibers.set(id, fiber);
+      return fiber;
+    };
+
+    if (listeners.size > 0) {
+      for (const element of elements) {
+        // eslint-disable-next-line no-restricted-syntax
+        disposables.push(...setupListeners(element, run));
+      }
+    }
+
+    return Scope.addFinalizer(
+      scope,
+      Effect.suspend(() => {
+        disposables.forEach(dispose);
+        if (fibers.size === 0) return Effect.void;
+        return Fiber.interruptAll(fibers.values());
+      }),
+    );
+  }
+
+  return {
+    addEventListener,
+    setup,
+  };
+}
+
+function proxyCurrentTarget<E extends Event>(event: E, currentTarget: Element): E {
+  return new Proxy(event, {
+    get(target: E, property: string | symbol) {
+      if (property === "currentTarget") return currentTarget;
+      const value = target[property as keyof E];
+      if (typeof value === "function") return value.bind(event);
+      return value;
+    },
+  });
+}
+
+function getDerivedAddEventListenerOptions(entries: Set<Entry>): AddEventListenerOptions {
+  let once = true;
+  let passive = true;
+  for (const h of entries) {
+    if (h[1].options?.once !== true) once = false;
+    if (h[1].options?.passive !== true) passive = false;
+    if (!once && !passive) break;
+  }
+  return { once, passive };
+}