@typed/template 0.14.0 → 1.0.0-beta.1

package/README.md

@@ -1,5 +1,124 @@
 # @typed/template
 
-> WIP
+> **Beta:** This package is in beta; APIs may change.
 
-Docs: https://tylors.github.io/typed/docs/template
+`@typed/template` provides **type-safe, reactive UIs that integrate with Effect**. It is the core UI layer for typed-smol apps: HTML literals (`html`), DOM rendering, SSR (HTML strings), hydration, event handlers with Effect, and keyed list rendering. Templates are **Fx streams** (`Fx<RenderEvent, E, R>`); you provide a `RenderTemplate` service (e.g. `DomRenderTemplate` for the browser or `HtmlRenderTemplate` for SSR).
+
+## Dependencies
+
+- `effect`
+- `@typed/fx`
+- `html5parser`
+- `happy-dom` (dev)
+
+## Capabilities
+
+- **Reactive interpolation**: Interpolate `Renderable` values—primitives, `Effect`, `Fx`/`Stream`—directly in `html` templates; updates stream through to the DOM.
+- **DOM + SSR targets**: Same templates work in the browser (`DomRenderTemplate`) and on the server (`HtmlRenderTemplate`); choose the layer for your environment.
+- **Hydration**: Use `makeHydrateContext` to attach to existing SSR DOM instead of creating new nodes; supports keyed lists (`many`).
+- **Keyed lists**: `many(values, getKey, render)` renders reactive lists with efficient keyed diffing and per-item `RefSubject` state.
+- **EventHandler with Effect**: `EventHandler.make` for type-safe event handlers that return `Effect`; supports `preventDefault`, `stopPropagation`, etc.
+- **Batched render queue**: `RenderQueue` and `RenderPriority` (Sync, Raf, Idle) batch DOM updates for smoother rendering.
+
+## When to use
+
+Use `@typed/template` when building Effect-based web UIs, when you need SSR + hydration, or when you want type-safe templates and event handlers. For routing, combine with `@typed/router`. For Link and SSR helpers, use `@typed/ui` on top of template.
+
+## API overview
+
+- **Templates:** `html` tag; **Renderable**; **Template** module.
+- **Rendering:** `render(template, container)` — renders an Fx of RenderEvent into a DOM node; **RenderTemplate** (service); **DomRenderTemplate**, **HtmlRenderTemplate** (layers); **RenderEvent**, **DomRenderEvent**, **HtmlRenderEvent**.
+- **Services (Render):** **CurrentRenderDocument**, **CurrentRenderQueue**, **CurrentRenderPriority**.
+- **Events:** **EventHandler**; **EventSource**; **RenderEvent**.
+- **Hydration:** **HydrateContext**, **makeHydrateContext**.
+- **Other:** **Parser**, **Wire**; **HtmlChunk**, **RenderQueue**; subpaths `@typed/template/Render`, `@typed/template/Html`, `@typed/template/HtmlChunk`, etc.
+
+## Example
+
+```ts
+import { Layer } from "effect";
+import { Fx, RefSubject } from "@typed/fx";
+import { DomRenderTemplate, html, render } from "@typed/template";
+
+const Counter = Fx.gen(function* () {
+  const count = yield* RefSubject.make(0);
+  return html`<div>
+    <button onclick=${RefSubject.increment(count)}>Increment</button>
+    <button onclick=${RefSubject.decrement(count)}>Decrement</button>
+    <p>Count: ${count}</p>
+  </div>`;
+});
+
+// Inside Effect.gen(function* () { ... })
+yield *
+  render(Counter, document.body).pipe(
+    Fx.drainLayer,
+    Layer.provide(DomRenderTemplate),
+    Layer.launch,
+  );
+```
+
+See the [counter example](https://github.com/typed-smol/typed-smol/tree/main/examples/counter) for a full app.
+
+## API Reference
+
+### Main entry (`@typed/template`)
+
+| Export                                                                                          | Description                                                                                                                                                                                              |
+| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Templates**                                                                                   |                                                                                                                                                                                                          |
+| `html`                                                                                          | Tag function for HTML template literals; returns an `Fx<RenderEvent, E, R>`. Requires `RenderTemplate` in context.                                                                                       |
+| `many(values, getKey, render)`                                                                  | Renders a reactive list with keyed diffing; `values` is an `Fx<ReadonlyArray<A>>`, `getKey` maps items to keys, `render(ref, key)` returns an Fx of RenderEvents.                                        |
+| **RenderEvent**                                                                                 |                                                                                                                                                                                                          |
+| `RenderEvent`                                                                                   | Union of `DomRenderEvent` and `HtmlRenderEvent`.                                                                                                                                                         |
+| `DomRenderEvent(content)`                                                                       | Constructor for a DOM render result; `content` is `Rendered` (from `Wire`).                                                                                                                              |
+| `HtmlRenderEvent(html, last)`                                                                   | Constructor for an HTML-string render result; `last` indicates final chunk.                                                                                                                              |
+| `isRenderEvent`, `isDomRenderEvent`, `isHtmlRenderEvent`                                        | Type guards for `RenderEvent` variants.                                                                                                                                                                  |
+| **Renderable**                                                                                  |                                                                                                                                                                                                          |
+| `Renderable<A, E, R>`                                                                           | Type of values that can be interpolated: primitives, arrays, `Effect`, `Fx`/`Stream`, objects. `Renderable.Any`, `Renderable.Services`, `Renderable.Error`, `Renderable.Success` for type-level helpers. |
+| **EventHandler** (`EventHandler` namespace)                                                     |                                                                                                                                                                                                          |
+| `EventHandler.make(handler, options?)`                                                          | Creates an event handler; `handler` can return `void` or `Effect`; `options` can include `preventDefault`, `stopPropagation`, `once`, `passive`, etc.                                                    |
+| `EventHandler.provide`, `EventHandler.catchCause`                                               | Provide services or recover from errors.                                                                                                                                                                 |
+| `EventHandler.preventDefault`, `stopPropagation`, `stopImmediatePropagation`, `once`, `passive` | Combinators that add listener options.                                                                                                                                                                   |
+| `EventHandler.fromEffectOrEventHandler`, `EventHandler.isEventHandler`                          | Coerce from Effect or check type.                                                                                                                                                                        |
+| **EventSource**                                                                                 |                                                                                                                                                                                                          |
+| `makeEventSource()`                                                                             | Creates an `EventSource` with `addEventListener` and `setup(rendered, scope)`.                                                                                                                           |
+| **Hydration**                                                                                   |                                                                                                                                                                                                          |
+| `HydrateContext`                                                                                | Service tag for hydration context (internal shape).                                                                                                                                                      |
+| `makeHydrateContext(rootElement)`                                                               | Builds a service map with hydration context for the given root element.                                                                                                                                  |
+| **Parser**                                                                                      |                                                                                                                                                                                                          |
+| `parse(template)`                                                                               | Parses a `TemplateStringsArray` (or readonly string array) into a `Template.Template`.                                                                                                                   |
+| **RenderTemplate**                                                                              |                                                                                                                                                                                                          |
+| `RenderTemplate`                                                                                | Service that implements template rendering; callable as `(templateStrings, values) => Fx<RenderEvent, E, R>`.                                                                                            |
+| **Template**                                                                                    |                                                                                                                                                                                                          |
+| `Template` (namespace)                                                                          | `Template` class (nodes, hash, parts), part/element node types (`NodePart`, `AttrPartNode`, `EventPartNode`, etc.), and AST node types.                                                                  |
+| **HtmlChunk**                                                                                   |                                                                                                                                                                                                          |
+| `HtmlChunk`, `HtmlTextChunk`, `HtmlPartChunk`, `HtmlSparsePartChunk`                            | Types for pre-compiled HTML chunks.                                                                                                                                                                      |
+| `templateToHtmlChunks(template)`, `addTemplateHash(chunks, template)`                           | Build chunks from a parsed template; add hash comments for hydration.                                                                                                                                    |
+| **Wire**                                                                                        |                                                                                                                                                                                                          |
+| `Wire`, `Rendered`                                                                              | Wire is a persistent fragment-like type; `Rendered` is the DOM output type. `persistent(document, templateHash, fragment)`, `toHtml(rendered)`, and internal helpers.                                    |
+| **RenderQueue**                                                                                 |                                                                                                                                                                                                          |
+| `RenderQueue` (abstract), `MixedRenderQueue`, `RenderPriority`                                  | Queue for batched DOM updates; priorities like `RenderPriority.Sync`, `RenderPriority.Raf(n)`, `RenderPriority.Idle(n)`.                                                                                 |
+
+### `@typed/template/Render`
+
+| Export                                    | Description                                                                                                                      |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `render(fx, where)` / `render(where)(fx)` | Mounts an Fx of `RenderEvent`s into the DOM element `where`; provides `HydrateContext` from `where`. Returns Fx of rendered DOM. |
+| `DomRenderTemplate`                       | Layer providing DOM-based `RenderTemplate`. `DomRenderTemplate.using(document)` for a custom document.                           |
+| `CurrentRenderDocument`                   | Service reference for the `Document` used when rendering (default: global `document`).                                           |
+| `CurrentRenderQueue`                      | Service reference for the render queue (default: `MixedRenderQueue`).                                                            |
+| `CurrentRenderPriority`                   | Service reference for default task priority (default: `RenderPriority.Raf(10)`).                                                 |
+| `ToRendered<T>`                           | Type: rendered DOM for `RenderEvent` or `null`.                                                                                  |
+| `attemptHydration(ctx, hash)`             | Internal helper for hydration.                                                                                                   |
+| `TemplateContext`                         | Internal render context type.                                                                                                    |
+
+### `@typed/template/Html`
+
+| Export                     | Description                                                                |
+| -------------------------- | -------------------------------------------------------------------------- |
+| `renderToHtml(fx)`         | Converts an Fx of `RenderEvent`s into an Fx of HTML strings (for SSR).     |
+| `renderToHtmlString(fx)`   | Effect that collects `renderToHtml` output and joins into a single string. |
+| `HtmlRenderTemplate`       | Layer providing HTML-string `RenderTemplate` (for SSR).                    |
+| `StaticHtmlRenderTemplate` | Like `HtmlRenderTemplate` with static rendering optimizations.             |
+| `StaticRendering`          | Service reference (boolean) for static rendering mode.                     |

package/dist/EventHandler.d.ts

@@ -0,0 +1,273 @@
+import type * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import { type Pipeable } from "effect/Pipeable";
+import type * as ServiceMap from "effect/ServiceMap";
+export declare const EventHandlerTypeId: unique symbol;
+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 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;
+/**
+ * Options for configuring event handling behavior.
+ */
+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 declare 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>;
+/**
+ * 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 declare 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>>;
+};
+/**
+ * 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 declare 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>;
+};
+/**
+ * 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 declare function fromEffectOrEventHandler<Ev extends Event, E = never, R = never>(handler: Effect.Effect<unknown, E, R> | EventHandler<Ev, E, R>): EventHandler<Ev, 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 declare function isEventHandler<Ev extends Event, E = never, R = never>(handler: unknown): handler is EventHandler<Ev, E, R>;
+/**
+ * Applies event options to a native DOM event.
+ */
+export declare function handleEventOptions<Ev extends Event>(eventOptions: EventOptions, ev: Ev): boolean;
+/**
+ * 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 declare function preventDefault<Ev extends Event, E = never, R = never>(handler: EventHandler<Ev, E, R>): EventHandler<Ev, E, R>;
+/**
+ * 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 declare function stopPropagation<Ev extends Event, E = never, R = never>(handler: EventHandler<Ev, E, R>): EventHandler<Ev, E, R>;
+/**
+ * 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 declare function stopImmediatePropagation<Ev extends Event, E = never, R = never>(handler: EventHandler<Ev, E, R>): EventHandler<Ev, E, R>;
+/**
+ * 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 declare function once<Ev extends Event, E = never, R = never>(handler: EventHandler<Ev, E, R>): EventHandler<Ev, E, R>;
+/**
+ * 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 declare function passive<Ev extends Event, E = never, R = never>(handler: EventHandler<Ev, E, R>): EventHandler<Ev, E, R>;
+//# sourceMappingURL=EventHandler.d.ts.map

package/dist/EventHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventHandler.d.ts","sourceRoot":"","sources":["../src/EventHandler.ts"],"names":[],"mappings":"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"}

package/dist/EventHandler.js

@@ -0,0 +1,261 @@
+import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
+import { pipeArguments } from "effect/Pipeable";
+import { hasProperty } from "effect/Predicate";
+export const EventHandlerTypeId = Symbol.for("@typed/template/EventHandler");
+/**
+ * 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 function make(handler, options) {
+    return {
+        [EventHandlerTypeId]: EventHandlerTypeId,
+        handler: (ev) => {
+            if (options)
+                handleEventOptions(options, ev);
+            const result = handler(ev);
+            if (Effect.isEffect(result))
+                return result;
+            return Effect.void;
+        },
+        options,
+        pipe() {
+            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 const provide = dual(2, (handler, services) => {
+    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 const catchCause = dual(2, (handler, f) => {
+    return make((ev) => handler.handler(ev).pipe(Effect.catchCause(f)), handler.options);
+});
+/**
+ * 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 function fromEffectOrEventHandler(handler) {
+    if (isEventHandler(handler))
+        return handler;
+    return make(() => handler);
+}
+/**
+ * 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 isEventHandler(handler) {
+    return hasProperty(handler, EventHandlerTypeId);
+}
+/**
+ * Applies event options to a native DOM event.
+ */
+export function handleEventOptions(eventOptions, ev) {
+    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 preventDefault(handler) {
+    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 stopPropagation(handler) {
+    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 function stopImmediatePropagation(handler) {
+    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 once(handler) {
+    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 passive(handler) {
+    return make(handler.handler, { ...handler.options, passive: true, once: false });
+}