@intrig/plugin-react 0.0.1

package/src/lib/templates/docs/async-hook.spec.ts

@@ -0,0 +1,92 @@
+import { reactAsyncFunctionHookDocs } from './async-hook';
+
+// We use a plain object cast to any to avoid direct dependency on the types from "@intrig/plugin-sdk" in test.
+
+describe('reactAsyncFunctionHookDocs', () => {
+  it('snapshot — simple REST descriptor (no body, no path params)', async () => {
+    const descriptor = {
+      id: '1',
+      name: 'validateUsername',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'users',
+      data: {
+        method: 'GET',
+        paths: ['/api/users/validate-username'],
+        operationId: 'validateUsername',
+        // no requestBody
+        // no variables
+      },
+    };
+
+    const result = await reactAsyncFunctionHookDocs(descriptor as any);
+
+    expect(result.path).toBe('async-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('snapshot — request body only (no path params)', async () => {
+    const descriptor = {
+      id: '2',
+      name: 'checkPasswordStrength',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'security',
+      data: {
+        method: 'POST',
+        paths: ['/api/security/check-password'],
+        operationId: 'checkPasswordStrength',
+        requestBody: 'CheckPasswordStrengthRequest',
+      },
+    };
+
+    const result = await reactAsyncFunctionHookDocs(descriptor as any);
+    expect(result.path).toBe('async-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('snapshot — path params only (no request body)', async () => {
+    const descriptor = {
+      id: '3',
+      name: 'verifyUserById',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'users/{id}',
+      data: {
+        method: 'GET',
+        paths: ['/api/users/{id}/verify'],
+        operationId: 'verifyUserById',
+        variables: [
+          { name: 'id', in: 'path', ref: '#/components/schemas/Id' },
+        ],
+      },
+    };
+
+    const result = await reactAsyncFunctionHookDocs(descriptor as any);
+    expect(result.path).toBe('async-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('snapshot — request body and path params', async () => {
+    const descriptor = {
+      id: '4',
+      name: 'recalculateUserScore',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'users/{id}',
+      data: {
+        method: 'PUT',
+        paths: ['/api/users/{id}/score'],
+        operationId: 'recalculateUserScore',
+        requestBody: 'RecalculateUserScoreRequest',
+        variables: [
+          { name: 'id', in: 'PATH', ref: '#/components/schemas/Id' },
+        ],
+      },
+    };
+
+    const result = await reactAsyncFunctionHookDocs(descriptor as any);
+    expect(result.path).toBe('async-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+});

package/src/lib/templates/docs/async-hook.ts

@@ -0,0 +1,226 @@
+import { camelCase, mdLiteral, pascalCase, ResourceDescriptor, RestData } from "@intrig/plugin-sdk"
+
+export function reactAsyncFunctionHookDocs(descriptor: ResourceDescriptor<RestData>) {
+  const md = mdLiteral('async-hook.md')
+
+  // ===== Derived names (preserve these) =====
+  const hasPathParams = (descriptor.data.variables ?? []).some(
+    (v: any) => v.in?.toUpperCase() === 'PATH',
+  )
+
+  const actionName = camelCase(descriptor.name)                  // e.g. getUser
+  const abortName = `abort${pascalCase(descriptor.name)}`       // e.g. abortGetUser
+
+  const requestBodyVar = descriptor.data.requestBody
+    ? camelCase(descriptor.data.requestBody)                    // e.g. createUser
+    : undefined
+  const requestBodyType = descriptor.data.requestBody
+    ? pascalCase(descriptor.data.requestBody)                   // e.g. CreateUser
+    : undefined
+
+  const paramsVar = hasPathParams ? `${actionName}Params` : undefined          // e.g. getUserParams
+  const paramsType = hasPathParams ? `${pascalCase(descriptor.name)}Params` : undefined // e.g. GetUserParams
+  const responseTypeName = `${pascalCase(descriptor.name)}ResponseBody`        // e.g. GetUserResponseBody
+
+  const callArgs = [requestBodyVar, paramsVar].filter(Boolean).join(', ')
+
+  return md`
+# Intrig Async Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+${"```ts"}
+import { use${pascalCase(descriptor.name)}Async } from '@intrig/react/${descriptor.path}/client';
+${"```"}
+
+### 2) Create an instance
+${"```ts"}
+const [${actionName}, ${abortName}] = use${pascalCase(descriptor.name)}Async();
+${"```"}
+
+### 3) Call it (awaitable)
+${"```ts"}
+// body?, params? — pass what your endpoint needs (order: body, params)
+await ${actionName}(${callArgs});
+${"```"}
+
+Async hooks are for one-off, low-friction calls (e.g., validations, submissions). They return an **awaitable function** plus an **abort** function. No NetworkState.
+
+---
+
+## TL;DR (copy–paste)
+${"```tsx"}
+import { use${pascalCase(descriptor.name)}Async } from '@intrig/react/${descriptor.path}/client';
+import { useCallback, useEffect } from 'react';
+
+export default function Example() {
+  const [${actionName}, ${abortName}] = use${pascalCase(descriptor.name)}Async();
+
+  const run = useCallback(async () => {
+    try {
+      const result = await ${actionName}(${callArgs});
+      // do something with result
+      console.log(result);
+    } catch (e) {
+      // request failed or was aborted
+      console.error(e);
+    }
+  }, [${actionName}]);
+
+  // Optional: abort on unmount
+  useEffect(() => ${abortName}, [${abortName}]);
+
+  return <button onClick={run}>Call</button>;
+}
+${"```"}
+
+${requestBodyType || paramsType ? `### Optional types (if generated by your build)
+${"```ts"}
+${requestBodyType ? `import type { ${requestBodyType} } from '@intrig/react/${descriptor.source}/components/schemas/${requestBodyType}';
+` : ''}${paramsType ? `import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.params';
+` : ''}import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.response';
+${"```"}
+` : ''}
+
+---
+
+## Hook API
+${"```ts"}
+// Prefer concrete types if your build emits them:
+// import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.response';
+// ${paramsType ? `import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.params';` : ''}
+
+type ${pascalCase(descriptor.name)}Data = ${'unknown'}; // replace with ${responseTypeName} if generated
+type ${pascalCase(descriptor.name)}Request = {
+  body?: ${requestBodyType ?? 'unknown'};
+  params?: ${paramsType ?? 'unknown'};
+};
+
+// Signature (shape shown; return type depends on your endpoint)
+declare function use${pascalCase(descriptor.name)}Async(): [
+  (body?: ${pascalCase(descriptor.name)}Request['body'], params?: ${pascalCase(descriptor.name)}Request['params']) => Promise<${pascalCase(descriptor.name)}Data>,
+  () => void // abort
+];
+${"```"}
+
+### Why async hooks?
+- **No state machine:** just \`await\` the result.
+- **Great for validations & submits:** uniqueness checks, field-level checks, updates.
+- **Abortable:** cancel in-flight work on demand.
+
+---
+
+## Usage Patterns
+
+### 1) Simple try/catch (recommended)
+${"```tsx"}
+const [${actionName}] = use${pascalCase(descriptor.name)}Async();
+
+try {
+  const res = await ${actionName}(${callArgs});
+  // use res
+} catch (e) {
+  // network error or abort
+}
+${"```"}
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> you just need the value or an error. Ideal for validators, uniqueness checks, or quick lookups.</p>
+</details>
+
+### 2) Abort on unmount (safe cleanup)
+${"```tsx"}
+const [${actionName}, ${abortName}] = use${pascalCase(descriptor.name)}Async();
+
+useEffect(() => ${abortName}, [${abortName}]);
+${"```"}
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> the component may unmount while a request is in-flight (route changes, conditional UI).</p>
+</details>
+
+### 3) Debounced validation (e.g., on input change)
+${"```tsx"}
+const [${actionName}, ${abortName}] = use${pascalCase(descriptor.name)}Async();
+
+const onChange = useMemo(() => {
+  let t: any;
+  return (${requestBodyVar ? `${requestBodyVar}: ${requestBodyType ?? 'any'}` : 'value: string'}) => {
+    clearTimeout(t);
+    t = setTimeout(async () => {
+      try {
+        // Optionally abort before firing a new request
+        ${abortName}();
+        await ${actionName}(${[requestBodyVar ?? '/* body from value */', paramsVar ?? '/* params? */'].join(', ')});
+      } catch {}
+    }, 250);
+  };
+}, [${actionName}, ${abortName}]);
+${"```"}
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> validating as the user types. Debounce to reduce chatter; consider <code>${abortName}()</code> before firing a new call.</p>
+</details>
+
+### 4) Guard against races (latest-only)
+${"```tsx"}
+const [${actionName}, ${abortName}] = use${pascalCase(descriptor.name)}Async();
+
+const latestOnly = async () => {
+  ${abortName}();
+  return ${actionName}(${callArgs});
+};
+${"```"}
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> only the most recent call should win (search suggestions, live filters).</p>
+</details>
+
+---
+
+## Full example
+${"```tsx"}
+import { use${pascalCase(descriptor.name)}Async } from '@intrig/react/${descriptor.path}/client';
+import { useCallback } from 'react';
+
+function MyComponent() {
+  const [${actionName}, ${abortName}] = use${pascalCase(descriptor.name)}Async();
+
+  const run = useCallback(async () => {
+    try {
+      const data = await ${actionName}(${callArgs});
+      alert(JSON.stringify(data));
+    } catch (e) {
+      console.error('Call failed/aborted', e);
+    }
+  }, [${actionName}]);
+
+  return (
+    <>
+      <button onClick={run}>Call remote</button>
+      <button onClick={${abortName}}>Abort</button>
+    </>
+  );
+}
+${"```"}
+
+---
+
+## Gotchas & Tips
+- **No \`NetworkState\`:** async hooks return a Promise, not a state machine.
+- **Abort:** always available; call it to cancel the latest in-flight request.
+- **Errors:** wrap calls with \`try/catch\` to handle network failures or abort errors.
+- **Debounce & throttle:** combine with timers to cut down chatter for typeahead/validators.
+- **Types:** prefer generated \`${responseTypeName}\` and \`${paramsType ?? '...Params'}\` if your build emits them.
+
+---
+
+## Reference: Minimal cheat sheet
+${"```ts"}
+const [fn, abort] = use${pascalCase(descriptor.name)}Async();
+await fn(${callArgs});
+abort(); // optional
+${"```"}
+`
+}

package/src/lib/templates/docs/download-hook.spec.ts

@@ -0,0 +1,182 @@
+import { reactDownloadHookDocs } from './download-hook';
+
+// We use a plain object cast to any to avoid direct dependency on the types from "@intrig/plugin-sdk" in test.
+
+describe('reactDownloadHookDocs', () => {
+  it('snapshot — simple REST descriptor (no body, no path params)', async () => {
+    const descriptor = {
+      id: '1',
+      name: 'downloadReport',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'reports',
+      data: {
+        method: 'GET',
+        paths: ['/api/reports/download'],
+        operationId: 'downloadReport',
+        // no requestBody
+        // no variables
+      },
+    };
+
+    const result = await reactDownloadHookDocs(descriptor as any);
+
+    expect(result.path).toBe('download-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('snapshot — request body only (no path params)', async () => {
+    const descriptor = {
+      id: '2',
+      name: 'downloadCustomReport',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'reports',
+      data: {
+        method: 'POST',
+        paths: ['/api/reports/download-custom'],
+        operationId: 'downloadCustomReport',
+        requestBody: 'DownloadCustomReportRequest',
+        // no variables
+      },
+    };
+
+    const result = await reactDownloadHookDocs(descriptor as any);
+    expect(result.path).toBe('download-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('snapshot — path params only (no request body)', async () => {
+    const descriptor = {
+      id: '3',
+      name: 'downloadFileById',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'files/{id}',
+      data: {
+        method: 'GET',
+        paths: ['/api/files/{id}/download'],
+        operationId: 'downloadFileById',
+        variables: [
+          { name: 'id', in: 'path', ref: '#/components/schemas/Id' },
+        ],
+      },
+    };
+
+    const result = await reactDownloadHookDocs(descriptor as any);
+    expect(result.path).toBe('download-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('snapshot — request body and path params', async () => {
+    const descriptor = {
+      id: '4',
+      name: 'downloadUserDocument',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'users/{userId}/documents',
+      data: {
+        method: 'POST',
+        paths: ['/api/users/{userId}/documents/download'],
+        operationId: 'downloadUserDocument',
+        requestBody: 'DownloadUserDocumentRequest',
+        variables: [
+          { name: 'userId', in: 'PATH', ref: '#/components/schemas/UserId' },
+        ],
+      },
+    };
+
+    const result = await reactDownloadHookDocs(descriptor as any);
+    expect(result.path).toBe('download-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('handles multiple path params', async () => {
+    const descriptor = {
+      id: '5',
+      name: 'downloadProjectAsset',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'projects/{projectId}/assets/{assetId}',
+      data: {
+        method: 'GET',
+        paths: ['/api/projects/{projectId}/assets/{assetId}/download'],
+        operationId: 'downloadProjectAsset',
+        variables: [
+          { name: 'projectId', in: 'path', ref: '#/components/schemas/ProjectId' },
+          { name: 'assetId', in: 'PATH', ref: '#/components/schemas/AssetId' },
+        ],
+      },
+    };
+
+    const result = await reactDownloadHookDocs(descriptor as any);
+    expect(result.path).toBe('download-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('handles query params mixed with path params', async () => {
+    const descriptor = {
+      id: '6',
+      name: 'downloadTaskFile',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'tasks/{taskId}/files',
+      data: {
+        method: 'GET',
+        paths: ['/api/tasks/{taskId}/files/download'],
+        operationId: 'downloadTaskFile',
+        variables: [
+          { name: 'taskId', in: 'path', ref: '#/components/schemas/TaskId' },
+          { name: 'format', in: 'query', ref: '#/components/schemas/Format' },
+          { name: 'includeMetadata', in: 'QUERY', ref: '#/components/schemas/Boolean' },
+        ],
+      },
+    };
+
+    const result = await reactDownloadHookDocs(descriptor as any);
+    expect(result.path).toBe('download-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('handles empty variables array', async () => {
+    const descriptor = {
+      id: '7',
+      name: 'downloadBackup',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'backup',
+      data: {
+        method: 'GET',
+        paths: ['/api/backup/download'],
+        operationId: 'downloadBackup',
+        variables: [], // empty array instead of undefined
+      },
+    };
+
+    const result = await reactDownloadHookDocs(descriptor as any);
+    expect(result.path).toBe('download-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('handles case-insensitive path parameter detection', async () => {
+    const descriptor = {
+      id: '8',
+      name: 'downloadInvoice',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'invoices/{invoiceId}',
+      data: {
+        method: 'GET',
+        paths: ['/api/invoices/{invoiceId}/download'],
+        operationId: 'downloadInvoice',
+        variables: [
+          { name: 'invoiceId', in: 'Path', ref: '#/components/schemas/InvoiceId' }, // Mixed case
+        ],
+      },
+    };
+
+    const result = await reactDownloadHookDocs(descriptor as any);
+    expect(result.path).toBe('download-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+});

package/src/lib/templates/docs/download-hook.ts

@@ -0,0 +1,170 @@
+import { camelCase, mdLiteral, pascalCase, ResourceDescriptor, RestData } from "@intrig/plugin-sdk";
+
+export function reactDownloadHookDocs(descriptor: ResourceDescriptor<RestData>) {
+  const md = mdLiteral('download-hook.md');
+
+  // ===== Derived names (preserve these) =====
+  const hasPathParams = (descriptor.data.variables ?? []).some(
+    (v: any) => v.in?.toUpperCase() === 'PATH',
+  );
+
+  const actionName = camelCase(descriptor.name);                  // e.g. downloadTaskFile
+  const respVar = `${actionName}Resp`;                            // e.g. downloadTaskFileResp
+
+  const paramsVar = hasPathParams ? `${actionName}Params` : undefined; // e.g. downloadTaskFileParams
+  const paramsType = hasPathParams ? `${pascalCase(descriptor.name)}Params` : undefined; // e.g. DownloadTaskFileParams
+
+  const pascal = pascalCase(descriptor.name);
+  const responseTypeName = `${pascal}ResponseBody`; // e.g. DownloadTaskFileResponseBody
+
+  return md`
+# Intrig Download Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### Auto-download (most common)
+${"```ts"}
+import { use${pascal}Download } from '@intrig/react/${descriptor.path}/client';
+${"```"}
+${"```ts"}
+import { isPending, isError } from '@intrig/react';
+${"```"}
+${"```tsx"}
+const [${respVar}, ${actionName}] = use${pascal}Download({ clearOnUnmount: true });
+// e.g., in a click handler:
+${actionName}(${paramsType ? paramsVar ?? '{}' : '{}'});
+${"```"}
+
+### Manual/stateful (you handle the blob/UI)
+${"```ts"}
+import { use${pascal} } from '@intrig/react/${descriptor.path}/client';
+${"```"}
+${"```ts"}
+import { isSuccess, isPending, isError } from '@intrig/react';
+${"```"}
+${"```tsx"}
+const [${respVar}, ${actionName}] = use${pascal}({ clearOnUnmount: true });
+// later:
+${actionName}(${paramsType ? paramsVar ?? '{}' : '{}'});
+${"```"}
+
+---
+
+## TL;DR (auto-download)
+${"```tsx"}
+import { use${pascal}Download } from '@intrig/react/${descriptor.path}/client';
+import { isPending, isError } from '@intrig/react';
+
+export default function Example() {
+  const [${respVar}, ${actionName}] = use${pascal}Download({ clearOnUnmount: true });
+
+  return (
+    <button
+      onClick={() => ${actionName}(${paramsType ? paramsVar ?? '{}' : '{}'})}
+      disabled={isPending(${respVar})}
+    >
+      {isPending(${respVar}) ? 'Downloading…' : 'Download'}
+    </button>
+  );
+}
+${"```"}
+
+${paramsType ? `### Optional types (if generated by your build)
+${"```ts"}
+import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pascal}.params';
+import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pascal}.response';
+${"```"}
+` : ''}
+
+---
+
+## Hook APIs
+
+### \`use${pascal}Download\` (auto-download)
+- **What it does:** requests the file with \`responseType: 'blob'\` + \`adapter: 'fetch'\`, derives filename from \`Content-Disposition\` if present, creates a temporary object URL, clicks a hidden \`<a>\`, **downloads**, then resets state to \`init\`.
+- **Signature:** \`[state, download, clear]\`
+  - \`download(params: ${paramsType ?? 'Record<string, unknown>'}) => void\`
+
+### \`use${pascal}\` (manual/stateful)
+- **What it does:** same request but **does not** auto-save. You control preview/saving using \`state.data\` + \`state.headers\`.
+- **Signature:** \`[state, fetchFile, clear]\`
+  - \`fetchFile(params: ${paramsType ?? 'Record<string, unknown>'}) => void\`
+
+---
+
+## Usage Patterns
+
+### 1) Auto-download on click (recommended)
+${"```tsx"}
+const [${respVar}, ${actionName}] = use${pascal}Download({ clearOnUnmount: true });
+
+<button
+  onClick={() => ${actionName}(${paramsType ? paramsVar ?? '{}' : '{}'})}
+  disabled={isPending(${respVar})}
+>
+  {isPending(${respVar}) ? 'Downloading…' : 'Download file'}
+</button>
+{isError(${respVar}) ? <p className="text-red-500">Failed to download.</p> : null}
+${"```"}
+
+<details><summary>Description</summary>
+<p>Most users just need a button that saves the file. This variant handles object URL creation, filename extraction, click, and state reset.</p>
+</details>
+
+### 2) Auto-download on mount (e.g., “Your file is ready” page)
+${"```tsx"}
+useEffect(() => {
+  ${actionName}(${paramsType ? paramsVar ?? '{}' : '{}'});
+}, [${actionName}]);
+${"```"}
+
+<details><summary>Description</summary>
+<p>Good for post-processing routes that immediately start a download.</p>
+</details>
+
+### 3) Manual handling (preview or custom filename)
+${"```tsx"}
+const [${respVar}, ${actionName}] = use${pascal}({ clearOnUnmount: true });
+
+useEffect(() => {
+  if (isSuccess(${respVar})) {
+    const ct = ${respVar}.headers?.['content-type'] ?? 'application/octet-stream';
+    const parts = Array.isArray(${respVar}.data) ? ${respVar}.data : [${respVar}.data];
+    const url = URL.createObjectURL(new Blob(parts, { type: ct }));
+    // preview/save with your own UI...
+    return () => URL.revokeObjectURL(url);
+  }
+}, [${respVar}]);
+${"```"}
+
+<details><summary>Description</summary>
+<p>Use when you need to inspect headers, show a preview, or control the filename/UI flow.</p>
+</details>
+
+---
+
+## Behavior notes (what the auto-download variant does)
+- Forces \`responseType: 'blob'\` and \`adapter: 'fetch'\`.
+- If \`content-type\` is JSON, stringifies payload so the saved file is human-readable.
+- Parses \`Content-Disposition\` to derive a filename; falls back to a default.
+- Creates and clicks a temporary link, then **resets state to \`init\`**.
+
+---
+
+## Gotchas & Tips
+- **Expose headers in CORS:** server should send  
+  \`Access-Control-Expose-Headers: Content-Disposition, Content-Type\`
+- **Disable double clicks:** guard with \`isPending(state)\`.
+- **Revoke URLs** when you create them manually in the stateful variant.
+- **iOS Safari:** blob downloads may open a new tab—consider server-side direct-download URLs for a smoother UX.
+
+---
+
+## Troubleshooting
+- **No filename shown:** your server didn’t include \`Content-Disposition\`. Add it.
+- **Got JSON instead of a file:** server returned \`application/json\` (maybe an error). The auto hook saves it as text; surface the error in UI.
+- **Nothing happens on click:** ensure you’re using the **Download** variant and the request succeeds (check Network tab); verify CORS headers.
+
+---
+`;
+}