@intrig/plugin-react 0.0.1 → 0.0.2-2

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

@@ -1,92 +0,0 @@
-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

@@ -1,226 +0,0 @@
-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

@@ -1,182 +0,0 @@
-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

@@ -1,170 +0,0 @@
-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.
-
----
-`;
-}