@vertesia/appgen-docs 1.5.0-dev.20260910.051115Z → 1.6.0-dev.20260912.110338Z

package/lib/docs/recipes/client-interactions.md

@@ -0,0 +1,45 @@
+# Current-project Interactions Recipe
+
+This recipe is generated with the installed `@vertesia/client` and `@vertesia/common` versions. Use it instead
+of searching dependency source for the browser client signature.
+
+## List interactions from React
+
+```tsx
+import type { InteractionRef } from '@vertesia/common';
+import { useFetch } from '@vertesia/ui/core';
+import { useUserSession } from '@vertesia/ui/session';
+
+export function InteractionCatalog() {
+    const { client } = useUserSession();
+    const { data = [] } = useFetch<InteractionRef[]>(() => client.interactions.list(), {
+        deps: [client],
+        defaultValue: [],
+    });
+
+    return <ul>{data.map((interaction) => <li key={interaction.id}>{interaction.name}</li>)}</ul>;
+}
+```
+
+## Stable signatures
+
+- `client.interactions.list(payload?: InteractionSearchPayload): Promise<InteractionRef[]>`.
+- Empty input is valid. Use `client.interactions.list()` unless the task requires a server-side filter.
+- The useful `InteractionRef` fields are `id`, `name`, `endpoint`, `description?`, `status`, `version`,
+  `tags`, and `updated_at`.
+- `InteractionRef` deliberately has no `type` field. When a current-project catalog must display type, call
+  `client.interactions.catalog.listStoredInteractions()`, which returns `Promise<CatalogInteractionRef[]>`; do not
+  search generated declarations for `InteractionRef.type` or infer it from another field.
+- `listStoredInteractions()` sends `GET /api/v1/interactions/catalog/stored` (plus optional `status` or `tag`
+  query parameters). Its JSON response is the bare `CatalogInteractionRef[]` array, never an `{ items: [...] }`
+  wrapper. A focused Playwright mock can route `**/api/v1/interactions/catalog/stored**` and fulfill that bare array.
+- The useful `CatalogInteractionRef` fields are `type` (`'stored'` for this endpoint), `id`, `name`, `title`,
+  `description?`, `version?`, and `tags`. Use `client.interactions.catalog.list()` only when the task explicitly
+  asks for the combined system, app, and stored catalog rather than the current project's stored interactions.
+- This recipe fully specifies the method, return type, endpoint, and response shape. Do not probe the live API, inspect
+  `node_modules`, or call `app_docs_grep`/`app_docs_read` to reconfirm them. Treat a concrete workspace typecheck or
+  Playwright failure as the only reason to inspect one exact symbol afterward.
+- Keep SDK methods attached to their topic: call `client.interactions.list()`; do not destructure `list`.
+- The session client is already scoped to the signed-in user's current project. Do not construct another client in
+  browser code and do not hardcode a project id.
+- For schemas, use `client.interactions.export({})`; for the normal catalog, use `list()`.

package/lib/docs/recipes/ui-components.md

@@ -0,0 +1,92 @@
+# UI Components Recipe
+
+This recipe is generated with the installed `@vertesia/ui` version. Use it for common app screens instead of
+searching dependency source. For an API not covered here, search `appgen/ui-interfaces.d.ts` once by exact symbol.
+
+For a current-project interaction catalog built with the table, button, and fetch APIs below, this recipe is complete.
+After reading it, do not search generated declarations or dependency source for `Table`, `TBody`, `useFetch`, or
+the interaction catalog merely to reconfirm these signatures. Implement the screen and let the first workspace typecheck
+identify any real version drift; only then search once for the exact symbol named by that diagnostic.
+
+## Imports
+
+```tsx
+import {
+    Button,
+    Table,
+    TableHeaderCell,
+    TBody,
+    THead,
+    TR,
+    useFetch,
+} from '@vertesia/ui/core';
+```
+
+These are runtime React values, not types. Import `Table`, `TBody`, `THead`, `TR`, `TableHeaderCell`, `Button`,
+and `useFetch` with a normal `import`; using `import type` makes JSX fail with TS1361.
+
+## Loading table with refresh
+
+`TBody.columns` is required. It is the number of rendered columns and drives the loading skeleton.
+Use `TableHeaderCell` instead of raw `<th>` so column scope is accessible by default.
+
+```tsx
+const { data = [], error, isLoading, refetch } = useFetch(loadRows, { deps: [projectId], defaultValue: [] });
+
+<Button type="button" onClick={() => void refetch()} isLoading={isLoading}>
+    Refresh
+</Button>
+
+{error ? <p role="alert">{error.message}</p> : null}
+<Table>
+    <THead>
+        <TR>
+            <TableHeaderCell>Name</TableHeaderCell>
+            <TableHeaderCell>Status</TableHeaderCell>
+        </TR>
+    </THead>
+    <TBody columns={2} isLoading={isLoading}>
+        {data.map((row) => (
+            <TR key={row.id}>
+                <td>{row.name}</td>
+                <td>{row.status}</td>
+            </TR>
+        ))}
+    </TBody>
+</Table>
+{!isLoading && !error && data.length === 0 ? <p>No results found.</p> : null}
+```
+
+## Stable signatures
+
+- `useFetch<T>(fetcher, { deps, defaultValue, onSuccess, onError })` returns
+  `{ data, isLoading, error, setData, refetch }`.
+- `TBody` accepts `{ columns: number; isLoading?: boolean; rows?: number; children: ReactNode }`.
+- `Button` accepts normal button props plus `isLoading`, `isDisabled`, `variant`, and `size`.
+- Icon-only buttons need `aria-label`. Text buttons should keep their visible text in the accessible name.
+- Use a native `<section aria-label="…">` for a labeled table/overflow region. Do not put `role="region"` on a
+  `<div>`; Biome's `lint/a11y/useSemanticElements` requires the semantic element.
+- Prefer semantic theme classes and plain HTML for layout. Do not guess private `@vertesia/ui` paths.
+
+## Generated app tests
+
+- The standard generated app runs Vitest in a Node environment and intentionally does not install jsdom,
+  happy-dom, or Testing Library. Do not search dependency trees or add a DOM-test dependency for a UI-only change.
+- Put loading/error/empty/populated/refresh decisions in a separate production `*.state.ts` or `*.model.ts` module
+  imported and used by the component. Cover that state matrix by importing the pure module directly from the focused unit
+  test. Do not export the helper only from the component's TSX module: importing that file also loads the real
+  `@vertesia/ui` runtime, which the standard Node-only Vitest environment cannot execute. Do not copy the helper into
+  the test or walk rendered React element internals; the tested module must remain on the production import path.
+- Source Playwright specs import `type { Page }` from `@playwright/test` and `{ expect, test }` from
+  `./vertesia`. Type shared helpers as `page: Page`; never hand-write a structural Page or Route type because
+  Playwright's overloaded callbacks will reject narrower substitutes. Use `page.route` to mock only the real API
+  path involved in the primary flow (interaction listing uses a path containing `/interactions`), then exercise the
+  page through accessible roles. Use the declared `test:e2e` script and its `PLAYWRIGHT_BASE_URL`; do not invent a
+  second browser harness.
+- Scope repeated text to its semantic container and request an exact accessible name. For example, use
+  `table.getByRole('cell', { name: interactionName, exact: true })` when the same name can also occur in tags or
+  descriptions; an unscoped text or name locator can match several elements and waste a browser retry.
+- For a responsive table, prove document-level overflow is absent and intentional overflow stays on one labeled table
+  region. Assert positive horizontal overflow only at the narrow viewport—a desktop table may fit—and scroll that region
+  before using `toBeInViewport()` on the final required column. DOM presence or `toBeVisible()` alone does not prove an
+  off-screen mobile column is reachable.