{
  "id": "@typed/ui/Dom/Events#chainEvent",
  "canonicalId": "@typed/ui/Dom/Events#chainEvent",
  "symbol": {
    "id": "@typed/ui/Dom/Events#chainEvent",
    "packageName": "@typed/ui",
    "moduleName": "Dom/Events",
    "exportName": "chainEvent",
    "kind": "function",
    "signatures": [
      "export declare function chainEvent<Ev extends Event, E1 = never, R1 = never, E2 = never, R2 = never>(user: EventHandlerInput<Ev, E1, R1>, internal: EventHandlerInput<Ev, E2, R2>): EventHandler.EventHandler<Ev, E1 | E2, R1 | R2> | undefined;"
    ],
    "summary": "Combines a user handler with component-required behavior for one native event.",
    "sections": {
      "Why": "Component hosts must combine user and required behavior without hiding the\nprecise Effect boundary. User callback invocation constructs the user Effect\nfirst. Internal callback invocation may then construct an internal Effect;\nonly execution of that returned Effect is sequenced after the user Effect.",
      "Ownership and lifetime": "The returned `EventHandler` owns no listener by itself. The rendering Scope\ninstalls it and removes it; `once` and AbortSignal state are honored for each\ninput independently. Capture and passive options are conservatively merged.",
      "DOM behavior": "The user handler receives a retained `Proxy` around the browser event so a\n`preventDefault()` call made while its Effect runs can still cancel the\ninternal step. The proxy is not identity-equal to the native event. Its\nproperties—including `currentTarget`—are read from that native event, so\n`currentTarget` becomes null after browser dispatch exactly as it normally\ndoes. The internal handler receives the original native event, never the\nproxy.",
      "Invocation and Effect sequencing": "`userHandler.handler(proxy)` is called first to construct `userEffect`. If\nthat invocation has already called `preventDefault()`—for example through an\nEventHandler option—the internal handler is not invoked. Otherwise,\n`internalHandler.handler(nativeEvent)` is called immediately to construct\n`internalEffect`, before `userEffect` runs. A void-returning internal callback\ntherefore performs its callback body eagerly and cannot be undone by a later\n`preventDefault()` inside `userEffect`. The composed Effect runs `userEffect`,\nchecks tracked default prevention again, and only then runs a returned\n`internalEffect` when it is still allowed."
    },
    "examples": [
      {
        "language": "ts",
        "code": "import { chainEvent } from \"@typed/ui/Dom/Events\"\nimport { EventHandler } from \"@typed/template\"\nimport { Effect } from \"effect\"\n\nconst calls: Array<string> = []\nconst handler = chainEvent(\n  EventHandler.make((event: MouseEvent) =>\n    Effect.sync(() => {\n      calls.push(\"user effect\")\n      event.preventDefault()\n    })),\n  EventHandler.make(() => {\n    calls.push(\"internal callback\") // runs while constructing the Effect\n    return Effect.sync(() => calls.push(\"internal effect\"))\n  })\n)!\n\nconst program = handler.handler(new MouseEvent(\"click\", { cancelable: true }))\n// calls is now [\"internal callback\"]\nawait Effect.runPromise(program)\n// calls is [\"internal callback\", \"user effect\"];\n// the returned internal Effect was gated by preventDefault."
      }
    ],
    "relations": [],
    "source": {
      "file": "packages/ui/src/Dom/Events.ts",
      "line": 69
    },
    "since": "1.0.0",
    "category": "Event composition"
  },
  "exposure": {
    "recordKind": "declaration",
    "id": "@typed/ui/Dom/Events#chainEvent",
    "packageName": "@typed/ui",
    "packageVersion": "1.0.0-beta.13",
    "moduleName": "Dom/Events",
    "consumerSpecifier": "@typed/ui/Dom/Events",
    "exportName": "chainEvent",
    "qualifiedName": "chainEvent",
    "declarationKey": "declaration:3aee64cc9f0addc4aa5f75a6",
    "family": "function",
    "signatures": [
      "export declare function chainEvent<Ev extends Event, E1 = never, R1 = never, E2 = never, R2 = never>(user: EventHandlerInput<Ev, E1, R1>, internal: EventHandlerInput<Ev, E2, R2>): EventHandler.EventHandler<Ev, E1 | E2, R1 | R2> | undefined;"
    ],
    "sourceSpans": [
      {
        "file": "packages/ui/src/Dom/Events.ts",
        "start": {
          "line": 69,
          "column": 1
        },
        "end": {
          "line": 114,
          "column": 2
        }
      }
    ],
    "aliases": [
      "@typed/ui#Dom.chainEvent",
      "@typed/ui/Dom#chainEvent",
      "@typed/ui/Dom/index#chainEvent",
      "@typed/ui/index#Dom.chainEvent"
    ],
    "isAlias": false,
    "static": false
  },
  "declaration": {
    "declarationKey": "declaration:3aee64cc9f0addc4aa5f75a6",
    "name": "chainEvent",
    "family": "function",
    "facets": [
      {
        "family": "function",
        "syntaxKind": "FunctionDeclaration",
        "signatures": [
          "export declare function chainEvent<Ev extends Event, E1 = never, R1 = never, E2 = never, R2 = never>(user: EventHandlerInput<Ev, E1, R1>, internal: EventHandlerInput<Ev, E2, R2>): EventHandler.EventHandler<Ev, E1 | E2, R1 | R2> | undefined;"
        ],
        "typeParameters": [
          "Ev extends Event",
          "E1 = never",
          "R1 = never",
          "E2 = never",
          "R2 = never"
        ],
        "sourceSpans": [
          {
            "file": "packages/ui/src/Dom/Events.ts",
            "start": {
              "line": 69,
              "column": 1
            },
            "end": {
              "line": 114,
              "column": 2
            }
          }
        ],
        "static": false,
        "readonly": false,
        "optional": false
      }
    ],
    "signatures": [
      "export declare function chainEvent<Ev extends Event, E1 = never, R1 = never, E2 = never, R2 = never>(user: EventHandlerInput<Ev, E1, R1>, internal: EventHandlerInput<Ev, E2, R2>): EventHandler.EventHandler<Ev, E1 | E2, R1 | R2> | undefined;"
    ],
    "typeParameters": [
      "Ev extends Event",
      "E1 = never",
      "R1 = never",
      "E2 = never",
      "R2 = never"
    ],
    "summary": "Combines a user handler with component-required behavior for one native event.",
    "sections": {
      "Why": "Component hosts must combine user and required behavior without hiding the\nprecise Effect boundary. User callback invocation constructs the user Effect\nfirst. Internal callback invocation may then construct an internal Effect;\nonly execution of that returned Effect is sequenced after the user Effect.",
      "Ownership and lifetime": "The returned `EventHandler` owns no listener by itself. The rendering Scope\ninstalls it and removes it; `once` and AbortSignal state are honored for each\ninput independently. Capture and passive options are conservatively merged.",
      "DOM behavior": "The user handler receives a retained `Proxy` around the browser event so a\n`preventDefault()` call made while its Effect runs can still cancel the\ninternal step. The proxy is not identity-equal to the native event. Its\nproperties—including `currentTarget`—are read from that native event, so\n`currentTarget` becomes null after browser dispatch exactly as it normally\ndoes. The internal handler receives the original native event, never the\nproxy.",
      "Invocation and Effect sequencing": "`userHandler.handler(proxy)` is called first to construct `userEffect`. If\nthat invocation has already called `preventDefault()`—for example through an\nEventHandler option—the internal handler is not invoked. Otherwise,\n`internalHandler.handler(nativeEvent)` is called immediately to construct\n`internalEffect`, before `userEffect` runs. A void-returning internal callback\ntherefore performs its callback body eagerly and cannot be undone by a later\n`preventDefault()` inside `userEffect`. The composed Effect runs `userEffect`,\nchecks tracked default prevention again, and only then runs a returned\n`internalEffect` when it is still allowed."
    },
    "examples": [
      {
        "language": "ts",
        "code": "import { chainEvent } from \"@typed/ui/Dom/Events\"\nimport { EventHandler } from \"@typed/template\"\nimport { Effect } from \"effect\"\n\nconst calls: Array<string> = []\nconst handler = chainEvent(\n  EventHandler.make((event: MouseEvent) =>\n    Effect.sync(() => {\n      calls.push(\"user effect\")\n      event.preventDefault()\n    })),\n  EventHandler.make(() => {\n    calls.push(\"internal callback\") // runs while constructing the Effect\n    return Effect.sync(() => calls.push(\"internal effect\"))\n  })\n)!\n\nconst program = handler.handler(new MouseEvent(\"click\", { cancelable: true }))\n// calls is now [\"internal callback\"]\nawait Effect.runPromise(program)\n// calls is [\"internal callback\", \"user effect\"];\n// the returned internal Effect was gated by preventDefault."
      }
    ],
    "sourceSpans": [
      {
        "file": "packages/ui/src/Dom/Events.ts",
        "start": {
          "line": 69,
          "column": 1
        },
        "end": {
          "line": 114,
          "column": 2
        }
      }
    ],
    "since": "1.0.0",
    "category": "Event composition"
  }
}