@triggery/react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @triggery/react
+
+## 0.1.0
+
+First public preview release.
+
+React bindings for Triggery — hook-first orchestration layer
+
+See the [repository-level CHANGELOG](../../CHANGELOG.md#010--2026-05-16) for the full set of packages and the umbrella feature list. Future entries on this file are appended automatically by changesets.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksey Skhomenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @triggery/react
+
+React bindings for [Triggery](https://github.com/triggeryjs/triggery).
+
+Provides:
+
+- `useEvent(trigger, 'eventName')` — get a typed event emitter.
+- `useCondition(trigger, 'name', () => value, [deps])` — register pull-based condition data.
+- `useAction(trigger, 'name', handler)` — register an action executor.
+- `useInlineTrigger({ on, do, if?, required? })` — define an inline trigger inside a component.
+- `<TriggerScope id="...">` — isolate registrations to a scope.
+- `<TriggerRuntimeProvider runtime={...}>` — attach a custom runtime.
+
+## Install
+
+```bash
+pnpm add @triggery/react @triggery/core
+```
+
+## License
+
+MIT &copy; Aleksey Skhomenko

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Runtime, TriggerSchema, ActionKey, Trigger, ActionMap, ConditionKey, ConditionMap, EventKey, EventMap, TriggerInspectSnapshot, NamedHooks, createTrigger } from '@triggery/core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * React context used to inject a custom runtime. When no provider is present,
+ * hooks fall back to the global default runtime.
+ */
+declare const TriggerRuntimeContext: react.Context<Runtime | undefined>;
+/** Read the active runtime from context, or return the default runtime. */
+declare function useRuntime(): Runtime;
+/**
+ * Scope context — string id provided by `<TriggerScope id="…">`. Default is
+ * `''` (global). Hooks pass it through to `registerCondition`/`registerAction`
+ * so the runtime can match the registration against a trigger's `scope`.
+ */
+declare const TriggerScopeContext: react.Context<string>;
+/** Read the active scope from context. `''` means "global / no scope". */
+declare function useScope(): string;
+
+/**
+ * Return an event emitter. Its identity is stable across renders (`useCallback`
+ * under the hood). The trigger must list this event in its `events: [...]` schema
+ * passed to `createTrigger`.
+ *
+ * @example
+ * ```tsx
+ * const fireNewMessage = useEvent(messageTrigger, 'new-message');
+ * useEffect(() => socket.on('msg', fireNewMessage), [fireNewMessage]);
+ * ```
+ */
+declare function useEvent<S extends TriggerSchema, K extends EventKey<S>>(_trigger: Trigger<S>, eventName: K): EventMap<S>[K] extends void ? () => void : (payload: EventMap<S>[K]) => void;
+/**
+ * Register a condition getter for a trigger. The runtime calls `getter()` at
+ * fire-time only — there are no subscriptions and no re-renders.
+ *
+ * `deps` only invalidate the closure cache (same semantics as `useCallback`).
+ *
+ * @example
+ * ```tsx
+ * useCondition(messageTrigger, 'user', () => currentUser, [currentUser]);
+ * ```
+ */
+declare function useCondition<S extends TriggerSchema, K extends ConditionKey<S>>(trigger: Trigger<S>, name: K, getter: () => ConditionMap<S>[K], deps?: readonly unknown[]): void;
+/**
+ * Register an action handler for a trigger. The runtime invokes the handler whenever
+ * the trigger body calls `actions.<name>(...)`.
+ *
+ * @example
+ * ```tsx
+ * useAction(messageTrigger, 'showToast', (payload) => toast.success(payload.title));
+ * ```
+ */
+declare function useAction<S extends TriggerSchema, K extends ActionKey<S>>(trigger: Trigger<S>, name: K, handler: ActionMap<S>[K] extends void ? () => void | Promise<void> : (payload: ActionMap<S>[K]) => void | Promise<void>): void;
+/**
+ * Return the latest snapshot of a trigger (for in-app debug panels).
+ */
+declare function useInspect<S extends TriggerSchema>(trigger: Trigger<S>): TriggerInspectSnapshot | undefined;
+/**
+ * Subscribe to the active runtime's inspector buffer and return the most
+ * recent `limit` snapshots (newest first). Re-renders whenever a new run is
+ * recorded.
+ *
+ * Use this for in-app devtools panels, custom run lists, or any "show me the
+ * last N runs" UI. Combine with `<TriggerSnapshotView>` from
+ * `@triggery/devtools-panel` for a turnkey UI.
+ *
+ * @example
+ * ```tsx
+ * function DebugPanel() {
+ *   const history = useInspectHistory(50);
+ *   return <ul>{history.map((s) => <li key={s.runId}>{s.triggerId}: {s.status}</li>)}</ul>;
+ * }
+ * ```
+ */
+declare function useInspectHistory(limit?: number): readonly TriggerInspectSnapshot[];
+
+/**
+ * Build the named-hooks proxy for a trigger.
+ *
+ * For a schema with `events: { 'new-message' }`, `conditions: { user }` and
+ * `actions: { showToast }` this returns:
+ *
+ *   useNewMessageEvent      -> () => fire
+ *   useUserCondition        -> (getter, deps?) => void
+ *   useShowToastAction      -> (handler) => void
+ *
+ * Names are derived from string keys via `kebab-case -> PascalCase`:
+ *   - `'new-message'`  -> `useNewMessageEvent`
+ *   - `'user'`         -> `useUserCondition`
+ *   - `'showToast'`    -> `useShowToastAction`
+ *
+ * Use it like:
+ *
+ *   export const { useNewMessageEvent, useUserCondition, useShowToastAction } =
+ *     createNamedHooks(messageTrigger);
+ *
+ * Implementation detail: the underlying object is a `Proxy` keyed by the hook
+ * name. Each lookup synthesizes a hook that delegates to `useEvent` /
+ * `useCondition` / `useAction` with the right port name.
+ */
+declare function createNamedHooks<S extends TriggerSchema>(trigger: Trigger<S>): NamedHooks<S>;
+
+type TriggerRuntimeProviderProps = {
+    readonly runtime: Runtime;
+    readonly children: ReactNode;
+};
+/**
+ * Provide a custom runtime to all descendants. Without a provider, hooks use the
+ * global `defaultRuntime`.
+ *
+ * @example
+ * ```tsx
+ * const isolated = createRuntime();
+ * <TriggerRuntimeProvider runtime={isolated}>
+ *   <MyApp />
+ * </TriggerRuntimeProvider>
+ * ```
+ */
+declare function TriggerRuntimeProvider({ runtime, children }: TriggerRuntimeProviderProps): react_jsx_runtime.JSX.Element;
+
+type TriggerScopeProps = {
+    /**
+     * Scope id. Triggers created with `scope: <this id>` in their config will see
+     * the conditions/actions registered inside this subtree; triggers without a
+     * matching scope will not.
+     *
+     * Nested scopes replace the outer one (last writer wins) — there is no
+     * implicit composition.
+     */
+    readonly id: string;
+    readonly children: ReactNode;
+};
+/**
+ * Provide a scope id to descendants. Registrations made by `useCondition` /
+ * `useAction` inside this subtree are tagged with the scope, and only triggers
+ * declared with the same `scope` will receive them.
+ *
+ * For full isolation (separate inspector / scheduler / middleware), prefer
+ * `<TriggerRuntimeProvider>` — `TriggerScope` is a lighter, in-runtime
+ * partitioning.
+ *
+ * @example
+ * ```tsx
+ * const chatTrigger = createTrigger<...>({
+ *   id: 'message',
+ *   scope: 'chat',
+ *   events: ['new-message'],
+ *   handler: ({ event, actions }) => actions.showToast?.({ title: event.payload.author }),
+ * });
+ *
+ * // useCondition / useAction inside the scope register with scope='chat'.
+ * <TriggerScope id="chat">
+ *   <UserProvider />
+ *   <ChatToaster />
+ * </TriggerScope>
+ * ```
+ */
+declare function TriggerScope({ id, children }: TriggerScopeProps): react_jsx_runtime.JSX.Element;
+
+type UseInlineTriggerConfig<S extends TriggerSchema> = {
+    /** Event name to react to. Required. */
+    readonly on: keyof NonNullable<S['events']> & string;
+    /** Handler body. Receives the same context as a full `createTrigger` handler. */
+    readonly do: Parameters<typeof createTrigger<S>>[0]['handler'];
+    /** Optional debug id (defaults to a stable auto-generated one). */
+    readonly id?: string;
+};
+/**
+ * Define a trigger inline inside a component — an escape hatch for one-off
+ * reactions where pulling them into a separate `*.trigger.ts` file would be
+ * overkill. The trigger lives for the lifetime of the component (created on
+ * mount, disposed on unmount).
+ *
+ * Use cases: tiny analytics taps, modal-stack coordination scoped to one screen,
+ * keyboard shortcuts that only matter while a panel is open.
+ *
+ * For anything reusable across the app — prefer `createTrigger` in a dedicated
+ * `*.trigger.ts` file.
+ *
+ * @example
+ * ```tsx
+ * useInlineTrigger<{ events: { 'cta:click': { id: string } } }>({
+ *   on: 'cta:click',
+ *   do: ({ event }) => track('cta', event.payload),
+ * });
+ * ```
+ */
+declare function useInlineTrigger<S extends TriggerSchema>(config: UseInlineTriggerConfig<S>): void;
+
+export { TriggerRuntimeContext, TriggerRuntimeProvider, type TriggerRuntimeProviderProps, TriggerScope, TriggerScopeContext, type TriggerScopeProps, type UseInlineTriggerConfig, createNamedHooks, useAction, useCondition, useEvent, useInlineTrigger, useInspect, useInspectHistory, useRuntime, useScope };

package/dist/index.js

@@ -0,0 +1,169 @@
+import { getDefaultRuntime, createTrigger } from '@triggery/core';
+import { createContext, useContext, useCallback, useRef, useEffect, useState, useMemo } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/context.ts
+var TriggerRuntimeContext = createContext(void 0);
+function useRuntime() {
+  const ctxRuntime = useContext(TriggerRuntimeContext);
+  return ctxRuntime ?? getDefaultRuntime();
+}
+var TriggerScopeContext = createContext("");
+function useScope() {
+  return useContext(TriggerScopeContext);
+}
+function useEvent(_trigger, eventName) {
+  const runtime = useRuntime();
+  return useCallback(
+    ((payload) => {
+      runtime.fire(eventName, payload);
+    }),
+    [runtime, eventName]
+  );
+}
+function useCondition(trigger, name, getter, deps = []) {
+  const runtime = useRuntime();
+  const scope = useScope();
+  const getterRef = useRef(getter);
+  getterRef.current = getter;
+  const stableGetter = useCallback(() => getterRef.current(), deps);
+  useEffect(() => {
+    const token = runtime.registerCondition(trigger.id, name, stableGetter, { scope });
+    return () => token.unregister();
+  }, [runtime, trigger.id, name, stableGetter, scope]);
+}
+function useAction(trigger, name, handler) {
+  const runtime = useRuntime();
+  const scope = useScope();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  useEffect(() => {
+    const token = runtime.registerAction(
+      trigger.id,
+      name,
+      (payload) => handlerRef.current(payload),
+      { scope }
+    );
+    return () => token.unregister();
+  }, [runtime, trigger.id, name, scope]);
+}
+function useInspect(trigger) {
+  return trigger.inspect();
+}
+function useInspectHistory(limit = 20) {
+  const runtime = useRuntime();
+  const [history, setHistory] = useState(
+    () => runtime.getInspectorBuffer().slice(0, limit)
+  );
+  useEffect(() => {
+    setHistory(runtime.getInspectorBuffer().slice(0, limit));
+    const token = runtime.subscribe(() => {
+      setHistory(runtime.getInspectorBuffer().slice(0, limit));
+    });
+    return () => token.unregister();
+  }, [runtime, limit]);
+  return history;
+}
+
+// src/namedHooks.ts
+function createNamedHooks(trigger) {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (typeof prop !== "string") return void 0;
+      const cached = cache.get(prop);
+      if (cached) return cached;
+      const parsed = parseHookName(prop);
+      if (!parsed) return void 0;
+      const { kind, portName } = parsed;
+      let hook;
+      if (kind === "event") {
+        hook = () => (
+          // biome-ignore lint/suspicious/noExplicitAny: passthrough
+          useEvent(trigger, portName)
+        );
+      } else if (kind === "condition") {
+        hook = (getter, deps) => (
+          // biome-ignore lint/suspicious/noExplicitAny: passthrough
+          useCondition(trigger, portName, getter, deps)
+        );
+      } else {
+        hook = (handler) => (
+          // biome-ignore lint/suspicious/noExplicitAny: passthrough
+          useAction(trigger, portName, handler)
+        );
+      }
+      cache.set(prop, hook);
+      return hook;
+    },
+    has(_target, prop) {
+      return typeof prop === "string" && parseHookName(prop) !== null;
+    }
+  });
+}
+var SUFFIXES = {
+  event: "Event",
+  condition: "Condition",
+  action: "Action"
+};
+function parseHookName(hookName) {
+  if (!hookName.startsWith("use")) return null;
+  for (const [kind, suffix] of Object.entries(SUFFIXES)) {
+    if (!hookName.endsWith(suffix)) continue;
+    const middle = hookName.slice(3, hookName.length - suffix.length);
+    if (middle.length === 0) continue;
+    return { kind, portName: pascalToCamel(middle) };
+  }
+  return null;
+}
+function pascalToCamel(s) {
+  if (s.length === 0) return s;
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+function TriggerRuntimeProvider({ runtime, children }) {
+  return /* @__PURE__ */ jsx(TriggerRuntimeContext.Provider, { value: runtime, children });
+}
+function TriggerScope({ id, children }) {
+  return /* @__PURE__ */ jsx(TriggerScopeContext.Provider, { value: id, children });
+}
+var inlineCounter = 0;
+function useInlineTrigger(config) {
+  const runtime = useRuntime();
+  const scope = useScope();
+  const idRef = useRef(void 0);
+  if (idRef.current === void 0) {
+    idRef.current = config.id ?? `inline:${(++inlineCounter).toString(36)}`;
+  }
+  const handlerRef = useRef(config.do);
+  handlerRef.current = config.do;
+  const stableHandler = useMemo(
+    () => ((ctx) => handlerRef.current(ctx)),
+    []
+  );
+  const eventNameRef = useRef(config.on);
+  if (eventNameRef.current !== config.on) {
+    const env = globalThis.process?.env?.NODE_ENV;
+    if (env !== "production") {
+      console.warn(
+        `[triggery] useInlineTrigger(${idRef.current}): "on" must be stable between renders (got "${String(config.on)}" but was "${String(eventNameRef.current)}")`
+      );
+    }
+  }
+  useEffect(() => {
+    const trigger = createTrigger(
+      {
+        id: idRef.current,
+        // biome-ignore lint/suspicious/noExplicitAny: inline trigger has runtime-only schema
+        events: [eventNameRef.current],
+        handler: stableHandler,
+        ...scope !== "" && { scope }
+      },
+      runtime
+    );
+    return () => trigger.dispose();
+  }, [runtime, stableHandler, scope]);
+}
+
+export { TriggerRuntimeContext, TriggerRuntimeProvider, TriggerScope, TriggerScopeContext, createNamedHooks, useAction, useCondition, useEvent, useInlineTrigger, useInspect, useInspectHistory, useRuntime, useScope };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/hooks.ts","../src/namedHooks.ts","../src/TriggerRuntimeProvider.tsx","../src/TriggerScope.tsx","../src/useInlineTrigger.ts"],"names":["jsx","useRef","useEffect"],"mappings":"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","file":"index.js","sourcesContent":["import { getDefaultRuntime, type Runtime } from '@triggery/core';\nimport { createContext, useContext } from 'react';\n\n/**\n * React context used to inject a custom runtime. When no provider is present,\n * hooks fall back to the global default runtime.\n */\nexport const TriggerRuntimeContext = createContext<Runtime | undefined>(undefined);\n\n/** Read the active runtime from context, or return the default runtime. */\nexport function useRuntime(): Runtime {\n  const ctxRuntime = useContext(TriggerRuntimeContext);\n  return ctxRuntime ?? getDefaultRuntime();\n}\n\n/**\n * Scope context — string id provided by `<TriggerScope id=\"…\">`. Default is\n * `''` (global). Hooks pass it through to `registerCondition`/`registerAction`\n * so the runtime can match the registration against a trigger's `scope`.\n */\nexport const TriggerScopeContext = createContext<string>('');\n\n/** Read the active scope from context. `''` means \"global / no scope\". */\nexport function useScope(): string {\n  return useContext(TriggerScopeContext);\n}\n","import type {\n  ActionKey,\n  ActionMap,\n  ConditionKey,\n  ConditionMap,\n  EventKey,\n  EventMap,\n  Trigger,\n  TriggerInspectSnapshot,\n  TriggerSchema,\n} from '@triggery/core';\nimport { useCallback, useEffect, useRef, useState } from 'react';\nimport { useRuntime, useScope } from './context.ts';\n\n/**\n * Return an event emitter. Its identity is stable across renders (`useCallback`\n * under the hood). The trigger must list this event in its `events: [...]` schema\n * passed to `createTrigger`.\n *\n * @example\n * ```tsx\n * const fireNewMessage = useEvent(messageTrigger, 'new-message');\n * useEffect(() => socket.on('msg', fireNewMessage), [fireNewMessage]);\n * ```\n */\nexport function useEvent<S extends TriggerSchema, K extends EventKey<S>>(\n  _trigger: Trigger<S>,\n  eventName: K,\n): EventMap<S>[K] extends void ? () => void : (payload: EventMap<S>[K]) => void {\n  const runtime = useRuntime();\n  return useCallback(\n    ((payload?: unknown) => {\n      runtime.fire(eventName, payload);\n    }) as EventMap<S>[K] extends void ? () => void : (payload: EventMap<S>[K]) => void,\n    [runtime, eventName],\n  );\n}\n\n/**\n * Register a condition getter for a trigger. The runtime calls `getter()` at\n * fire-time only — there are no subscriptions and no re-renders.\n *\n * `deps` only invalidate the closure cache (same semantics as `useCallback`).\n *\n * @example\n * ```tsx\n * useCondition(messageTrigger, 'user', () => currentUser, [currentUser]);\n * ```\n */\nexport function useCondition<S extends TriggerSchema, K extends ConditionKey<S>>(\n  trigger: Trigger<S>,\n  name: K,\n  getter: () => ConditionMap<S>[K],\n  deps: readonly unknown[] = [],\n): void {\n  const runtime = useRuntime();\n  const scope = useScope();\n  // Keep the latest getter in a ref — the runtime reads through a stable wrapper.\n  const getterRef = useRef(getter);\n  getterRef.current = getter;\n  // biome-ignore lint/correctness/useExhaustiveDependencies: deps managed by caller\n  const stableGetter = useCallback(() => getterRef.current(), deps);\n\n  useEffect(() => {\n    const token = runtime.registerCondition(trigger.id, name, stableGetter, { scope });\n    return () => token.unregister();\n  }, [runtime, trigger.id, name, stableGetter, scope]);\n}\n\n/**\n * Register an action handler for a trigger. The runtime invokes the handler whenever\n * the trigger body calls `actions.<name>(...)`.\n *\n * @example\n * ```tsx\n * useAction(messageTrigger, 'showToast', (payload) => toast.success(payload.title));\n * ```\n */\nexport function useAction<S extends TriggerSchema, K extends ActionKey<S>>(\n  trigger: Trigger<S>,\n  name: K,\n  handler: ActionMap<S>[K] extends void\n    ? () => void | Promise<void>\n    : (payload: ActionMap<S>[K]) => void | Promise<void>,\n): void {\n  const runtime = useRuntime();\n  const scope = useScope();\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n\n  useEffect(() => {\n    const token = runtime.registerAction(\n      trigger.id,\n      name,\n      (payload) => (handlerRef.current as (payload: unknown) => void | Promise<void>)(payload),\n      { scope },\n    );\n    return () => token.unregister();\n  }, [runtime, trigger.id, name, scope]);\n}\n\n/**\n * Return the latest snapshot of a trigger (for in-app debug panels).\n */\nexport function useInspect<S extends TriggerSchema>(trigger: Trigger<S>) {\n  return trigger.inspect();\n}\n\n/**\n * Subscribe to the active runtime's inspector buffer and return the most\n * recent `limit` snapshots (newest first). Re-renders whenever a new run is\n * recorded.\n *\n * Use this for in-app devtools panels, custom run lists, or any \"show me the\n * last N runs\" UI. Combine with `<TriggerSnapshotView>` from\n * `@triggery/devtools-panel` for a turnkey UI.\n *\n * @example\n * ```tsx\n * function DebugPanel() {\n *   const history = useInspectHistory(50);\n *   return <ul>{history.map((s) => <li key={s.runId}>{s.triggerId}: {s.status}</li>)}</ul>;\n * }\n * ```\n */\nexport function useInspectHistory(limit = 20): readonly TriggerInspectSnapshot[] {\n  const runtime = useRuntime();\n  const [history, setHistory] = useState<readonly TriggerInspectSnapshot[]>(() =>\n    runtime.getInspectorBuffer().slice(0, limit),\n  );\n\n  useEffect(() => {\n    // Re-seed on mount in case fires happened between the initial render and\n    // the effect (the runtime may have new entries already).\n    setHistory(runtime.getInspectorBuffer().slice(0, limit));\n    const token = runtime.subscribe(() => {\n      setHistory(runtime.getInspectorBuffer().slice(0, limit));\n    });\n    return () => token.unregister();\n  }, [runtime, limit]);\n\n  return history;\n}\n","import type { NamedHooks, Trigger, TriggerSchema } from '@triggery/core';\nimport { useAction, useCondition, useEvent } from './hooks.ts';\n\n/**\n * Build the named-hooks proxy for a trigger.\n *\n * For a schema with `events: { 'new-message' }`, `conditions: { user }` and\n * `actions: { showToast }` this returns:\n *\n *   useNewMessageEvent      -> () => fire\n *   useUserCondition        -> (getter, deps?) => void\n *   useShowToastAction      -> (handler) => void\n *\n * Names are derived from string keys via `kebab-case -> PascalCase`:\n *   - `'new-message'`  -> `useNewMessageEvent`\n *   - `'user'`         -> `useUserCondition`\n *   - `'showToast'`    -> `useShowToastAction`\n *\n * Use it like:\n *\n *   export const { useNewMessageEvent, useUserCondition, useShowToastAction } =\n *     createNamedHooks(messageTrigger);\n *\n * Implementation detail: the underlying object is a `Proxy` keyed by the hook\n * name. Each lookup synthesizes a hook that delegates to `useEvent` /\n * `useCondition` / `useAction` with the right port name.\n */\nexport function createNamedHooks<S extends TriggerSchema>(trigger: Trigger<S>): NamedHooks<S> {\n  // Cache hooks per identifier so React doesn't see a new function reference\n  // every render (which would break hook-rules + cause unnecessary churn).\n  const cache = new Map<string, unknown>();\n\n  return new Proxy({} as NamedHooks<S>, {\n    get(_target, prop) {\n      if (typeof prop !== 'string') return undefined;\n      const cached = cache.get(prop);\n      if (cached) return cached;\n\n      const parsed = parseHookName(prop);\n      if (!parsed) return undefined;\n\n      const { kind, portName } = parsed;\n      // biome-ignore lint/suspicious/noExplicitAny: bridge layer\n      let hook: any;\n      if (kind === 'event') {\n        hook = () =>\n          // biome-ignore lint/suspicious/noExplicitAny: passthrough\n          useEvent(trigger as Trigger<S>, portName as any);\n      } else if (kind === 'condition') {\n        hook = (\n          // biome-ignore lint/suspicious/noExplicitAny: passthrough\n          getter: any,\n          deps?: readonly unknown[],\n        ) =>\n          // biome-ignore lint/suspicious/noExplicitAny: passthrough\n          useCondition(trigger as Trigger<S>, portName as any, getter, deps);\n      } else {\n        // biome-ignore lint/suspicious/noExplicitAny: passthrough\n        hook = (handler: any) =>\n          // biome-ignore lint/suspicious/noExplicitAny: passthrough\n          useAction(trigger as Trigger<S>, portName as any, handler);\n      }\n      cache.set(prop, hook);\n      return hook;\n    },\n    has(_target, prop) {\n      return typeof prop === 'string' && parseHookName(prop) !== null;\n    },\n  });\n}\n\ntype ParsedHook = {\n  kind: 'event' | 'condition' | 'action';\n  /** Port name back in original camelCase/kebab-case form (best-effort). */\n  portName: string;\n};\n\nconst SUFFIXES = {\n  event: 'Event',\n  condition: 'Condition',\n  action: 'Action',\n} as const;\n\nfunction parseHookName(hookName: string): ParsedHook | null {\n  if (!hookName.startsWith('use')) return null;\n  for (const [kind, suffix] of Object.entries(SUFFIXES) as [\n    keyof typeof SUFFIXES,\n    (typeof SUFFIXES)[keyof typeof SUFFIXES],\n  ][]) {\n    if (!hookName.endsWith(suffix)) continue;\n    const middle = hookName.slice(3, hookName.length - suffix.length);\n    if (middle.length === 0) continue;\n    return { kind, portName: pascalToCamel(middle) };\n  }\n  return null;\n}\n\n/**\n * Convert PascalCase back to camelCase. We don't try to round-trip kebab-case\n * (`'new-message'` -> `'newMessage'`) because keys in `createTrigger` schemas\n * can be either form, and the runtime stores them as the original string.\n *\n * For kebab-case keys, the user can fall back to the universal `useEvent(t, 'kebab-key')`\n * hook — named-hooks support is best-effort for camelCase keys.\n */\nfunction pascalToCamel(s: string): string {\n  if (s.length === 0) return s;\n  return s.charAt(0).toLowerCase() + s.slice(1);\n}\n","import type { Runtime } from '@triggery/core';\nimport type { ReactNode } from 'react';\nimport { TriggerRuntimeContext } from './context.ts';\n\nexport type TriggerRuntimeProviderProps = {\n  readonly runtime: Runtime;\n  readonly children: ReactNode;\n};\n\n/**\n * Provide a custom runtime to all descendants. Without a provider, hooks use the\n * global `defaultRuntime`.\n *\n * @example\n * ```tsx\n * const isolated = createRuntime();\n * <TriggerRuntimeProvider runtime={isolated}>\n *   <MyApp />\n * </TriggerRuntimeProvider>\n * ```\n */\nexport function TriggerRuntimeProvider({ runtime, children }: TriggerRuntimeProviderProps) {\n  return (\n    <TriggerRuntimeContext.Provider value={runtime}>{children}</TriggerRuntimeContext.Provider>\n  );\n}\n","import type { ReactNode } from 'react';\nimport { TriggerScopeContext } from './context.ts';\n\nexport type TriggerScopeProps = {\n  /**\n   * Scope id. Triggers created with `scope: <this id>` in their config will see\n   * the conditions/actions registered inside this subtree; triggers without a\n   * matching scope will not.\n   *\n   * Nested scopes replace the outer one (last writer wins) — there is no\n   * implicit composition.\n   */\n  readonly id: string;\n  readonly children: ReactNode;\n};\n\n/**\n * Provide a scope id to descendants. Registrations made by `useCondition` /\n * `useAction` inside this subtree are tagged with the scope, and only triggers\n * declared with the same `scope` will receive them.\n *\n * For full isolation (separate inspector / scheduler / middleware), prefer\n * `<TriggerRuntimeProvider>` — `TriggerScope` is a lighter, in-runtime\n * partitioning.\n *\n * @example\n * ```tsx\n * const chatTrigger = createTrigger<...>({\n *   id: 'message',\n *   scope: 'chat',\n *   events: ['new-message'],\n *   handler: ({ event, actions }) => actions.showToast?.({ title: event.payload.author }),\n * });\n *\n * // useCondition / useAction inside the scope register with scope='chat'.\n * <TriggerScope id=\"chat\">\n *   <UserProvider />\n *   <ChatToaster />\n * </TriggerScope>\n * ```\n */\nexport function TriggerScope({ id, children }: TriggerScopeProps) {\n  return <TriggerScopeContext.Provider value={id}>{children}</TriggerScopeContext.Provider>;\n}\n","import { createTrigger, type Trigger, type TriggerSchema } from '@triggery/core';\nimport { useEffect, useMemo, useRef } from 'react';\nimport { useRuntime, useScope } from './context.ts';\n\nlet inlineCounter = 0;\n\nexport type UseInlineTriggerConfig<S extends TriggerSchema> = {\n  /** Event name to react to. Required. */\n  readonly on: keyof NonNullable<S['events']> & string;\n  /** Handler body. Receives the same context as a full `createTrigger` handler. */\n  readonly do: Parameters<typeof createTrigger<S>>[0]['handler'];\n  /** Optional debug id (defaults to a stable auto-generated one). */\n  readonly id?: string;\n};\n\n/**\n * Define a trigger inline inside a component — an escape hatch for one-off\n * reactions where pulling them into a separate `*.trigger.ts` file would be\n * overkill. The trigger lives for the lifetime of the component (created on\n * mount, disposed on unmount).\n *\n * Use cases: tiny analytics taps, modal-stack coordination scoped to one screen,\n * keyboard shortcuts that only matter while a panel is open.\n *\n * For anything reusable across the app — prefer `createTrigger` in a dedicated\n * `*.trigger.ts` file.\n *\n * @example\n * ```tsx\n * useInlineTrigger<{ events: { 'cta:click': { id: string } } }>({\n *   on: 'cta:click',\n *   do: ({ event }) => track('cta', event.payload),\n * });\n * ```\n */\nexport function useInlineTrigger<S extends TriggerSchema>(config: UseInlineTriggerConfig<S>): void {\n  const runtime = useRuntime();\n  const scope = useScope();\n  // Stable id — auto-generated unless the caller pinned one.\n  const idRef = useRef<string | undefined>(undefined);\n  if (idRef.current === undefined) {\n    idRef.current = config.id ?? `inline:${(++inlineCounter).toString(36)}`;\n  }\n\n  // Keep the latest handler in a ref so the runtime always calls the freshest\n  // body (closure capture without re-creating the trigger on every render).\n  const handlerRef = useRef(config.do);\n  handlerRef.current = config.do;\n\n  const stableHandler = useMemo(\n    () => ((ctx: Parameters<typeof config.do>[0]) => handlerRef.current(ctx)) as typeof config.do,\n    [],\n  );\n\n  // Capture event-name at first render — runtime needs the index built upfront.\n  const eventNameRef = useRef(config.on);\n  if (eventNameRef.current !== config.on) {\n    // DEV-only sanity: changing `on` between renders is a misuse.\n    const env = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env\n      ?.NODE_ENV;\n    if (env !== 'production') {\n      // eslint-disable-next-line no-console -- DEV warn\n      console.warn(\n        `[triggery] useInlineTrigger(${idRef.current}): \"on\" must be stable between renders ` +\n          `(got \"${String(config.on)}\" but was \"${String(eventNameRef.current)}\")`,\n      );\n    }\n  }\n\n  useEffect(() => {\n    const trigger = createTrigger<S>(\n      {\n        id: idRef.current as string,\n        // biome-ignore lint/suspicious/noExplicitAny: inline trigger has runtime-only schema\n        events: [eventNameRef.current] as any,\n        handler: stableHandler,\n        ...(scope !== '' && { scope }),\n      },\n      runtime,\n    ) as Trigger<S>;\n    return () => trigger.dispose();\n  }, [runtime, stableHandler, scope]);\n}\n"]}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@triggery/react",
+  "version": "0.1.0",
+  "description": "React bindings for Triggery — hook-first orchestration layer",
+  "license": "MIT",
+  "author": "Aleksey Skhomenko",
+  "homepage": "https://triggeryjs.github.io/triggery",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/triggeryjs/triggery.git",
+    "directory": "packages/react"
+  },
+  "bugs": "https://github.com/triggeryjs/triggery/issues",
+  "funding": [
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/triggery"
+    },
+    {
+      "type": "boosty",
+      "url": "https://boosty.to/triggery"
+    }
+  ],
+  "keywords": [
+    "react",
+    "triggery",
+    "hooks",
+    "orchestration",
+    "business-logic"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "@triggery/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "happy-dom": "^20.9.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6",
+    "@triggery/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}