@affordant/react 0.2.0

package/README.md

@@ -0,0 +1,47 @@
+# @affordant/react
+
+React adapter for [Affordant](https://leroy-florian.github.io/Affordant/). Gate your UI on what the server offers, and invoke affordances with **either invoker** — the vanilla Promise one or the Effect one. The framework axis (React) and the effect-system axis (Promise / Effect) stay orthogonal and composable.
+
+## Gating (pure, invoker-agnostic)
+
+```tsx
+import { useAffordance } from '@affordant/react'
+
+function CancelButton({ order }) {
+  const cancel = useAffordance(order, 'cancel')
+  if (!cancel.can) return null
+  return <button onClick={...}>Cancel</button>
+}
+```
+
+## Vanilla (Promise) invoker
+
+```tsx
+import { useAffordance, useFollow } from '@affordant/react'
+
+const cancel = useAffordance(order, 'cancel')
+const { run, running } = useFollow()
+
+<button disabled={!cancel.can || running} onClick={() => run(cancel.action!, { token })}>
+  Cancel
+</button>
+```
+
+## Effect invoker
+
+The Effect path composes [`@affordant/effect`](https://www.npmjs.com/package/@affordant/effect) with the [`effect-react-bridge`](https://www.npmjs.com/package/effect-react-bridge) runtime — no Effect coupling leaks into the vanilla path.
+
+```ts
+import { makeEffectHooks } from 'effect-react-bridge'
+import { makeAffordanceHooks } from '@affordant/react/effect'
+
+const bridge = makeEffectHooks({ runtime })
+const { useFollow } = makeAffordanceHooks(bridge)
+// useFollow().run(action, init) is now an interruptible Effect with a typed error
+```
+
+`react` is a peer dependency; `effect`, `effect-react-bridge` and `@affordant/effect` are optional peers, needed only for `@affordant/react/effect`.
+
+## License
+
+MIT

package/dist/effect.d.ts

@@ -0,0 +1,29 @@
+import type { EffectHooks } from 'effect-react-bridge';
+import { type FollowError } from '@affordant/effect';
+import type { FollowInit } from 'affordant';
+import type { HateoasAction } from '@affordant/contract';
+export interface EffectFollowResult {
+    readonly running: boolean;
+    readonly error: FollowError | null;
+    readonly run: (action: HateoasAction, init?: FollowInit) => Promise<Response>;
+}
+export interface AffordanceEffectHooks {
+    /**
+     * The Effect invoker as a hook, run through the supplied
+     * `effect-react-bridge` runtime: tracks `running` / `error` and interrupts
+     * the request when the component unmounts.
+     */
+    useFollow(): EffectFollowResult;
+}
+/**
+ * Compose the Effect invoker (`@affordant/effect`) with an
+ * `effect-react-bridge` runtime to get React hooks. The bridge stays
+ * domain-agnostic; this is the thin Affordant-specific glue.
+ *
+ * ```ts
+ * const { useEffectFn } = makeEffectHooks({ runtime })
+ * const affordances = makeAffordanceHooks({ useEffectFn } as EffectHooks<never>)
+ * ```
+ */
+export declare function makeAffordanceHooks<R>(hooks: EffectHooks<R>): AffordanceEffectHooks;
+//# sourceMappingURL=effect.d.ts.map

package/dist/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC9E;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,SAAS,IAAI,kBAAkB,CAAA;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,qBAAqB,CASnF"}

package/dist/effect.js

@@ -0,0 +1,20 @@
+import { follow as effectFollow } from '@affordant/effect';
+/**
+ * Compose the Effect invoker (`@affordant/effect`) with an
+ * `effect-react-bridge` runtime to get React hooks. The bridge stays
+ * domain-agnostic; this is the thin Affordant-specific glue.
+ *
+ * ```ts
+ * const { useEffectFn } = makeEffectHooks({ runtime })
+ * const affordances = makeAffordanceHooks({ useEffectFn } as EffectHooks<never>)
+ * ```
+ */
+export function makeAffordanceHooks(hooks) {
+    return {
+        useFollow() {
+            const { running, error, run } = hooks.useEffectFn((action, init) => effectFollow(action, init));
+            return { running, error, run };
+        },
+    };
+}
+//# sourceMappingURL=effect.js.map

package/dist/effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.js","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAoB,MAAM,mBAAmB,CAAA;AAmB5E;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAI,KAAqB;IAC1D,OAAO;QACL,SAAS;YACP,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,WAAW,CAC/C,CAAC,MAAqB,EAAE,IAAiB,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CACzE,CAAA;YACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;QAChC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { type FollowInit } from 'affordant';
+import type { HateoasAction, HateoasResource } from '@affordant/contract';
+export type { HateoasAction, HateoasMethod, HateoasResource } from '@affordant/contract';
+export type { FollowInit } from 'affordant';
+/** What the server currently offers for a `rel` on a resource. */
+export interface Affordance {
+    /** Whether the server offers this affordance right now. */
+    readonly can: boolean;
+    /** The action descriptor, or `null` when not offered. */
+    readonly action: HateoasAction | null;
+}
+/**
+ * Gate UI on an affordance. Pure and invoker-agnostic: it only reads what
+ * the server offered, mirroring `can` / `actionFor` as a memoised hook.
+ *
+ * ```tsx
+ * const cancel = useAffordance(order, 'cancel')
+ * return cancel.can ? <button onClick={...}>Cancel</button> : null
+ * ```
+ */
+export declare function useAffordance<T>(resource: HateoasResource<T> | null | undefined, rel: string): Affordance;
+export interface FollowState {
+    readonly running: boolean;
+    readonly error: unknown;
+}
+export interface UseFollowResult extends FollowState {
+    readonly run: (action: HateoasAction, init?: FollowInit) => Promise<Response>;
+}
+/**
+ * The vanilla (Promise) invoker as a hook: tracks `running` / `error` around
+ * the client's `follow`. This is one of Affordant's two interchangeable
+ * invokers; for the Effect one, see `@affordant/react/effect`.
+ */
+export declare function useFollow(): UseFollowResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAA2C,KAAK,UAAU,EAAE,MAAM,WAAW,CAAA;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAEzE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACxF,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAC/C,GAAG,EAAE,MAAM,GACV,UAAU,CAKZ;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC9E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,eAAe,CAgB3C"}

package/dist/index.js

@@ -0,0 +1,36 @@
+import { useCallback, useMemo, useState } from 'react';
+import { actionFor, can, follow as vanillaFollow } from 'affordant';
+/**
+ * Gate UI on an affordance. Pure and invoker-agnostic: it only reads what
+ * the server offered, mirroring `can` / `actionFor` as a memoised hook.
+ *
+ * ```tsx
+ * const cancel = useAffordance(order, 'cancel')
+ * return cancel.can ? <button onClick={...}>Cancel</button> : null
+ * ```
+ */
+export function useAffordance(resource, rel) {
+    return useMemo(() => ({ can: can(resource, rel), action: actionFor(resource, rel) }), [resource, rel]);
+}
+/**
+ * The vanilla (Promise) invoker as a hook: tracks `running` / `error` around
+ * the client's `follow`. This is one of Affordant's two interchangeable
+ * invokers; for the Effect one, see `@affordant/react/effect`.
+ */
+export function useFollow() {
+    const [state, setState] = useState({ running: false, error: null });
+    const run = useCallback(async (action, init) => {
+        setState({ running: true, error: null });
+        try {
+            const response = await vanillaFollow(action, init);
+            setState({ running: false, error: null });
+            return response;
+        }
+        catch (error) {
+            setState({ running: false, error });
+            throw error;
+        }
+    }, []);
+    return { ...state, run };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACtD,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,IAAI,aAAa,EAAmB,MAAM,WAAW,CAAA;AAcpF;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA+C,EAC/C,GAAW;IAEX,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,EACrE,CAAC,QAAQ,EAAE,GAAG,CAAC,CAChB,CAAA;AACH,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAc,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAEhF,MAAM,GAAG,GAAG,WAAW,CAAC,KAAK,EAAE,MAAqB,EAAE,IAAiB,EAAE,EAAE;QACzE,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QACxC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;YAClD,QAAQ,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YACzC,OAAO,QAAQ,CAAA;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,QAAQ,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;YACnC,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,CAAA;AAC1B,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@affordant/react",
+  "version": "0.2.0",
+  "description": "React adapter for Affordant: gate UI on the server's affordances and invoke them with either invoker — the vanilla Promise one or the Effect one.",
+  "license": "MIT",
+  "author": "Florian Leroy",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Leroy-Florian/Affordant.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://leroy-florian.github.io/Affordant/",
+  "bugs": "https://github.com/Leroy-Florian/Affordant/issues",
+  "keywords": [
+    "hateoas",
+    "hypermedia",
+    "affordance",
+    "react",
+    "hooks"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./effect": {
+      "types": "./dist/effect.d.ts",
+      "import": "./dist/effect.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "affordant": "^0.2.0",
+    "@affordant/contract": "^0.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "effect": "^3.21.0",
+    "effect-react-bridge": ">=0.1.0",
+    "@affordant/effect": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "effect": {
+      "optional": true
+    },
+    "effect-react-bridge": {
+      "optional": true
+    },
+    "@affordant/effect": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@affordant/effect": "*",
+    "effect-react-bridge": "*"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}