@intrig/plugin-react 0.0.1 → 0.0.2-2

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

@@ -1,97 +0,0 @@
-import { reactHookDocs } from './react-hook';
-
-// The descriptor type is imported in the implementation from "@intrig/plugin-sdk".
-// For the test we can just use the plain object shape to avoid tight coupling.
-
-describe('reactHookDocs', () => {
-  it('generates markdown that matches snapshot for a simple REST descriptor (no body, no path params)', async () => {
-    const descriptor = {
-      id: '1',
-      name: 'getUser',
-      type: 'rest' as const,
-      source: 'demo_api',
-      path: 'users',
-      data: {
-        method: 'GET',
-        paths: ['/api/users'],
-        operationId: 'getUser',
-        // no requestBody
-        // no variables
-      },
-    };
-
-    const result = await reactHookDocs(descriptor as any);
-
-    expect(result.path).toBe('react-hook.md');
-
-    const md = result.content;
-
-    expect(md).toMatchSnapshot();
-  });
-
-  it('snapshot — request body only (no path params)', async () => {
-    const descriptor = {
-      id: '2',
-      name: 'createUser',
-      type: 'rest' as const,
-      source: 'demo_api',
-      path: 'users',
-      data: {
-        method: 'POST',
-        paths: ['/api/users'],
-        operationId: 'createUser',
-        requestBody: 'CreateUserRequest',
-        // no variables
-      },
-    };
-
-    const result = await reactHookDocs(descriptor as any);
-    expect(result.path).toBe('react-hook.md');
-    expect(result.content).toMatchSnapshot();
-  });
-
-  it('snapshot — path params only (no request body)', async () => {
-    const descriptor = {
-      id: '3',
-      name: 'getUserById',
-      type: 'rest' as const,
-      source: 'demo_api',
-      path: 'users/{id}',
-      data: {
-        method: 'GET',
-        paths: ['/api/users/{id}'],
-        operationId: 'getUserById',
-        variables: [
-          { name: 'id', in: 'path', ref: '#/components/schemas/Id' },
-        ],
-      },
-    };
-
-    const result = await reactHookDocs(descriptor as any);
-    expect(result.path).toBe('react-hook.md');
-    expect(result.content).toMatchSnapshot();
-  });
-
-  it('snapshot — request body and path params', async () => {
-    const descriptor = {
-      id: '4',
-      name: 'updateUser',
-      type: 'rest' as const,
-      source: 'demo_api',
-      path: 'users/{id}',
-      data: {
-        method: 'PUT',
-        paths: ['/api/users/{id}'],
-        operationId: 'updateUser',
-        requestBody: 'UpdateUserRequest',
-        variables: [
-          { name: 'id', in: 'PATH', ref: '#/components/schemas/Id' },
-        ],
-      },
-    };
-
-    const result = await reactHookDocs(descriptor as any);
-    expect(result.path).toBe('react-hook.md');
-    expect(result.content).toMatchSnapshot();
-  });
-});

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

@@ -1,323 +0,0 @@
-import { camelCase, mdLiteral, pascalCase, ResourceDescriptor, RestData } from "@intrig/plugin-sdk"
-
-export function reactHookDocs(descriptor: ResourceDescriptor<RestData>) {
-  const md = mdLiteral('react-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 respVar = `${actionName}Resp`                         // e.g. getUserResp
-  const dataVar = `${actionName}Data`                         // e.g. getUserData
-  const clearName = `clear${pascalCase(descriptor.name)}`     // e.g. clearGetUser
-
-  const requestBodyVar = descriptor.data.requestBody
-    ? camelCase(descriptor.data.requestBody)
-    : undefined
-  const requestBodyType = descriptor.data.requestBody
-    ? pascalCase(descriptor.data.requestBody)
-    : 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`
-
-  return md`
-# Intrig React Hooks — Quick Guide
-
-## Copy-paste starter (fast lane)
-
-### 1) Hook import
-${"```ts"}
-import { use${pascalCase(descriptor.name)} } from '@intrig/react/${descriptor.path}/client';
-${"```"}
-
-### 2) Utility guards
-${"```ts"}
-import { isPending, isError, isSuccess } from '@intrig/react';
-${"```"}
-
-### 3) Hook instance (auto-clear on unmount)
-${"```ts"}
-const [${respVar}, ${actionName}] = use${pascalCase(descriptor.name)}({ clearOnUnmount: true });
-${"```"}
-
-Intrig stateful hooks expose a **NetworkState** plus **actions** to fetch / clear.
-Use this when you want a cached, reusable result tied to a global store.
-
----
-
-## TL;DR (copy–paste)
-${"```tsx"}
-import { use${pascalCase(descriptor.name)} } from '@intrig/react/${descriptor.path}/client';
-import { isPending, isError, isSuccess } from '@intrig/react';
-import { useEffect, useMemo } from 'react';
-
-export default function Example() {
-  const [${respVar}, ${actionName}] = use${pascalCase(descriptor.name)}({ clearOnUnmount: true });
-
-  useEffect(() => {
-    ${actionName}(${[requestBodyVar, paramsVar ?? '{}'].filter(Boolean).join(', ')});
-  }, [${[''+actionName, requestBodyVar, paramsVar].filter(Boolean).join(', ')}]);
-
-  const ${dataVar} = useMemo(
-    () => (isSuccess(${respVar}) ? ${respVar}.data : undefined),
-    [${respVar}]
-  );
-
-  if (isPending(${respVar})) return <>Loading…</>;
-  if (isError(${respVar})) return <>Error: {String(${respVar}.error)}</>;
-  return <pre>{JSON.stringify(${dataVar}, null, 2)}</pre>;
-}
-${"```"}
-
-${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';
-` : ''}// Prefer the concrete response type:
-import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.response';
-${"```"}
-` : ''}
-
----
-
-## Hook API
-${"```ts"}
-// Options are consistent across hooks.
-type UseHookOptions = {
-  /** Execute once after mount with provided params/body (if required). */
-  fetchOnMount?: boolean;
-  /** Reset the state on unmount (recommended). */
-  clearOnUnmount?: boolean;
-  /** Distinguish multiple instances of the same hook. */
-  key?: string;
-  /** Initial path params for endpoints that require them. */
-  params?: ${paramsType ?? 'unknown'};
-  /** Initial request body (for POST/PUT/etc.). */
-  body?: ${requestBodyType ?? 'unknown'};
-};
-
-// Prefer concrete types if your build emits them:
-// import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.response';
-
-type ${pascalCase(descriptor.name)}Data = ${'typeof '+responseTypeName !== 'undefined' ? responseTypeName : 'unknown'}; // replace with ${responseTypeName} if generated
-type ${pascalCase(descriptor.name)}Request = { params?: ${paramsType ?? 'unknown'}; body?: ${requestBodyType ?? 'unknown'}; };
-
-// Signature (shape shown; concrete generics vary per generated hook)
-declare function use${pascalCase(descriptor.name)}(options?: UseHookOptions): [
-  NetworkState<${pascalCase(descriptor.name)}Data>,
-  (req: ${pascalCase(descriptor.name)}Request) => void,
-  () => void
-];
-${"```"}
-
-### NetworkState & guards
-${"```ts"}
-import { isPending, isError, isSuccess } from '@intrig/react';
-${"```"}
-
----
-
-## Conceptual model (Stateful = single source of truth)
-- Lives in a shared store keyed by \`key\` + request signature.
-- Best for **read** endpoints you want to **reuse** or keep **warm** (lists, details, search).
-- Lifecycle helpers:
-  - \`fetchOnMount\` to kick off automatically.
-  - \`clearOnUnmount\` to clean up (recommended default).
-  - \`key\` to isolate multiple independent instances.
-
----
-
-## Usage patterns
-
-### 1) Controlled (most explicit)
-${"```tsx"}
-const [${respVar}, ${actionName}, ${clearName}] = use${pascalCase(descriptor.name)}();
-
-useEffect(() => {
-  ${actionName}(${[requestBodyVar, paramsVar ?? '{}'].filter(Boolean).join(', ')});
-  return ${clearName}; // optional cleanup
-}, [${[''+actionName, clearName].join(', ')}]);
-${"```"}
-
-<details><summary>Description</summary>
-<p><strong>Use when</strong> you need explicit control over when a request fires, what params/body it uses, and when to clean up. Ideal for search forms, pagination, conditional fetches.</p>
-</details>
-
-### 2) Lifecycle-bound (shorthand)
-${"```tsx"}
-const [${respVar}] = use${pascalCase(descriptor.name)}({
-  fetchOnMount: true,
-  clearOnUnmount: true,
-  ${requestBodyType ? `body: ${requestBodyVar},` : ''} ${paramsType ? `params: ${paramsVar ?? '{}'},` : 'params: {},'}
-});
-${"```"}
-
-<details><summary>Description</summary>
-<p><strong>Use when</strong> the data should follow the component lifecycle: fetch once on mount, reset on unmount.</p>
-</details>
-
-### 3) Passive observer (render when data arrives)
-${"```tsx"}
-const [${respVar}] = use${pascalCase(descriptor.name)}();
-return isSuccess(${respVar}) ? <>{String(${respVar}.data)}</> : null;
-${"```"}
-
-<details><summary>Description</summary>
-<p><strong>Use when</strong> another part of the app triggers the fetch and this component only reads the state.</p>
-</details>
-
-### 4) Keep previous success while refetching (sticky)
-${"```tsx"}
-const [${dataVar}, set${pascalCase(descriptor.name)}Data] = useState<any>();
-const [${respVar}, ${actionName}] = use${pascalCase(descriptor.name)}();
-
-useEffect(() => {
-  if (isSuccess(${respVar})) set${pascalCase(descriptor.name)}Data(${respVar}.data);
-}, [${respVar}]);
-
-return (
-  <>
-    {isPending(${respVar}) && ${dataVar} ? <div>Refreshing…</div> : null}
-    <pre>{JSON.stringify(isSuccess(${respVar}) ? ${respVar}.data : ${dataVar}, null, 2)}</pre>
-  </>
-);
-${"```"}
-
-<details><summary>Description</summary>
-<p><strong>Use when</strong> you want SWR-like UX without flicker.</p>
-</details>
-
-### 5) Multiple instances of the same hook (isolate with \`key\`)
-${"```tsx"}
-const a = use${pascalCase(descriptor.name)}({ key: 'A', fetchOnMount: true, ${paramsType ? `params: ${paramsVar ?? '{}'} ` : 'params: {}'} });
-const b = use${pascalCase(descriptor.name)}({ key: 'B', fetchOnMount: true, ${paramsType ? `params: ${paramsVar ?? '{}'} ` : 'params: {}'} });
-${"```"}
-
-<details><summary>Description</summary>
-<p>Use unique keys to prevent state collisions.</p>
-</details>
-
----
-
-## Before / After mini-migrations
-
-### If you mistakenly used Stateful for a simple submit → switch to Async
-${"```diff"}
-- const [${respVar}, ${actionName}] = use${pascalCase(descriptor.name)}();
-- ${actionName}(${[requestBodyVar, paramsVar ?? '{}'].filter(Boolean).join(', ')});
-+ const [fn] = use${pascalCase(descriptor.name)}Async();
-+ await fn(${[requestBodyVar, paramsVar].filter(Boolean).join(', ')});
-${"```"}
-
-### If you started with Async but need to read later in another component → Stateful
-${"```diff"}
-- const [fn] = use${pascalCase(descriptor.name)}Async();
-- const data = await fn(${[requestBodyVar, paramsVar].filter(Boolean).join(', ')});
-+ const [${respVar}, ${actionName}] = use${pascalCase(descriptor.name)}({ fetchOnMount: true, clearOnUnmount: true, ${paramsType ? `params: ${paramsVar ?? '{}'},` : 'params: {},'} ${requestBodyType ? `body: ${requestBodyVar}` : ''} });
-+ // read from ${respVar} anywhere with use${pascalCase(descriptor.name)}()
-${"```"}
-
----
-
-## Anti-patterns
-<details><summary>Don’t use Stateful for field validations or a one-off submit</summary>
-Use the Async variant instead: \`const [fn] = use${pascalCase(descriptor.name)}Async()\`.
-</details>
-<details><summary>Don’t use Async for long-lived lists or detail views</summary>
-Use Stateful so other components can read the same data and you can avoid refetch churn.
-</details>
-<details><summary>Don’t forget required \`params\` when using \`fetchOnMount\`</summary>
-Provide \`params\` (and \`body\` if applicable) or switch to the controlled pattern.
-</details>
-<details><summary>Rendering the same hook twice without a \`key\`</summary>
-If they should be independent, add a unique \`key\`.
-</details>
-
----
-
-## Error & UX guidance
-- **Loading:** early return or inline spinner. Prefer **sticky data** to avoid blanking content.
-- **Errors:** show a banner or inline errors depending on UX; keep previous good state if possible.
-- **Cleanup:** prefer \`clearOnUnmount: true\` as the default.
-
----
-
-## Concurrency patterns
-- **Refresh:** call the action again; combine with sticky data for smooth UX.
-- **Dedupe:** isolate instances with \`key\`.
-- **Parallel:** render two keyed instances; don’t share the same key.
-
----
-
-## Full examples
-
-### Short format (lifecycle-bound)
-${"```tsx"}
-import { use${pascalCase(descriptor.name)} } from '@intrig/react/${descriptor.path}/client';
-import { isPending, isError, isSuccess } from '@intrig/react';
-import { useMemo } from 'react';
-
-function ShortExample() {
-  const [${respVar}] = use${pascalCase(descriptor.name)}({
-    fetchOnMount: true,
-    clearOnUnmount: true,
-    ${requestBodyType ? `body: ${requestBodyVar},` : ''} ${paramsType ? `params: ${paramsVar ?? '{}'},` : 'params: {},'}
-  });
-
-  const ${dataVar} = useMemo(() => (isSuccess(${respVar}) ? ${respVar}.data : undefined), [${respVar}]);
-
-  if (isPending(${respVar})) return <>Loading…</>;
-  if (isError(${respVar})) return <>Error: {String(${respVar}.error)}</>;
-  return <pre>{JSON.stringify(${dataVar}, null, 2)}</pre>;
-}
-${"```"}
-
-<details><summary>Description</summary>
-<p>Compact lifecycle-bound approach. Great for read-only pages that load once and clean up on unmount.</p>
-</details>
-
-### Controlled format (explicit actions)
-${"```tsx"}
-import { use${pascalCase(descriptor.name)} } from '@intrig/react/${descriptor.path}/client';
-import { isPending, isError, isSuccess } from '@intrig/react';
-import { useEffect, useMemo } from 'react';
-
-function ControlledExample() {
-  const [${respVar}, ${actionName}, ${clearName}] = use${pascalCase(descriptor.name)}();
-
-  useEffect(() => {
-    ${actionName}(${[requestBodyVar, paramsVar ?? '{}'].filter(Boolean).join(', ')});
-    return ${clearName};
-  }, [${[''+actionName, clearName].join(', ')}]);
-
-  const ${dataVar} = useMemo(() => (isSuccess(${respVar}) ? ${respVar}.data : undefined), [${respVar}]);
-
-  if (isPending(${respVar})) return <>Loading…</>;
-  if (isError(${respVar})) return <>An error occurred: {String(${respVar}.error)}</>;
-  return <pre>{JSON.stringify(${dataVar}, null, 2)}</pre>;
-}
-${"```"}
-
----
-
-## Gotchas & Tips
-- Prefer **\`clearOnUnmount: true\`** in most components.
-- Use **\`key\`** for multiple independent instances.
-- Memoize derived values with **\`useMemo\`** to avoid churn.
-- Inline indicators keep the rest of the page interactive.
-
----
-
-## Reference: State helpers
-${"```ts"}
-if (isPending(${respVar})) { /* show spinner */ }
-if (isError(${respVar}))   { /* show error */ }
-if (isSuccess(${respVar})) { /* read ${respVar}.data */ }
-${"```"}
-`
-}

package/src/lib/templates/docs/schema.ts

@@ -1,105 +0,0 @@
-import { mdLiteral, ResourceDescriptor, Schema, typescript} from "@intrig/plugin-sdk"
-import {openApiSchemaToZod} from '../source/type/typeTemplate.js'
-import path from "path";
-
-/**
- * Schema documentation tab builders for React binding.
- * We keep a small, composable API similar to other docs templates.
- */
-
-export async function schemaTypescriptDoc(result: ResourceDescriptor<Schema>) {
-  const md = mdLiteral('schema-typescript.md')
-  const name = result.data.name
-  const source = result.source
-
-  const {tsType} = openApiSchemaToZod(result.data.schema);
-
-  const ts = typescript(path.resolve('src', source, 'temp', name, `${name}.ts`))
-
-  const importContent = await ts`
-    import type { ${name} } from '@intrig/react/${source}/components/schemas/${name}';
-  `;
-
-  const codeContent = await ts`
-    export type ${name} = ${tsType};
-  `
-
-  return md`
-# Typescript Type
-Use this TypeScript type anywhere you need static typing for this object shape in your app code: component props, function params/returns, reducers, and local state in .ts/.tsx files.
-
-## Import
-${'```ts'}
-${importContent}
-${'```'}
-
-## Definition
-${'```ts'}
-${codeContent}
-${'```'}
-  `
-}
-
-export async function schemaJsonSchemaDoc(result: ResourceDescriptor<Schema>) {
-  const md = mdLiteral('schema-json.md')
-  const name = result.data.name
-  const source = result.source
-
-  const ts = typescript(path.resolve('src', source, 'temp', name, `${name}.ts`))
-
-  const importContent = await ts`
-    import { ${name}_jsonschema } from '@intrig/react/${source}/components/schemas/${name}';
-  `;
-
-  const codeContent = await ts`
-    export const ${name}_jsonschema = ${JSON.stringify(result.data.schema, null, 2) ?? "{}"};
-  `
-
-  return md`
-# JSON Schema
-Use this JSON Schema with tools that consume JSON Schema: UI form builders (e.g. react-jsonschema-form), validators (AJV, validators in backends), and generators.
-
-## Import
-${'```ts'}
-${importContent}
-${'```'}
-
-## Definition
-${'```ts'}
-${codeContent}
-${'```'}
-  `
-}
-
-export async function schemaZodSchemaDoc(result: ResourceDescriptor<Schema>) {
-  const md = mdLiteral('schema-zod.md')
-  const name = result.data.name
-  const source = result.source
-
-  const {zodSchema} = openApiSchemaToZod(result.data.schema);
-
-  const ts = typescript(path.resolve('src', source, 'temp', name, `${name}.ts`))
-
-  const importContent = await ts`
-    import { ${name}Schema } from '@intrig/react/${source}/components/schemas/${name}';
-  `;
-
-  const codeContent = await ts`
-    export const ${name}Schema = ${zodSchema};
-  `
-
-  return md`
-# Zod Schema
-Use this Zod schema for runtime validation and parsing: form validation, client/server payload guards, and safe transformations before using or storing data.
-
-## Import
-${'```ts'}
-${importContent}
-${'```'}
-
-## Definition
-${'```ts'}
-${codeContent}
-${'```'}
-  `
-}